psp-open-source project ======================= This is the README file for the psp-open-source project. The PSP Security Protocol (PSP) is a security protocol created by Google for encryption in transit. PSP uses several of the concepts from IPsec ESP to provide an encryption encapsulation layer on-top of IP that is streamlined and custom-built to address the requirements of large-scale data centers. PSP is described in the "PSP Architecture Specification", which can be found in the /doc subdirectory. The project also contains a reference software implementation written in the 'C' language and a suite of packet-level test cases. The project contains the following subdirectories: /src - source code for the reference software implementation /pcap - pcap files used for testing /cfg - configuration files used for testing /test - bash scripts that implement the suite of test cases /doc - documentation including the "PSP Architecture Specification" in .pdf format /wireshark - wireshark plugin for PSP A more detailed description of the subdirectories is provided below. /src ==== Contains 3 programs and a Makefile. All the executables are built by the 'make' command. The 3 programs are: create_pcap ----------- Creates a cleartext pcap file that can be used for testing. The created packets are of the form Eth-IP-UDP-Payload with a fixed size of 1434 octets (unless the -e option is specified). All of the created packets are for the same flow (i.e., they all have the same MAC addresses, IP addresses, and UDP port numbers). Command Line Args: [-n N] [-f file_name] [-i ver] [-e] N is the number of packets to create, defaults to 1 file_name is the name of the pcap output file, defaults to "cleartext.pcap" ver is 4 or 6, 4 indicates create ipv4 packets, 6 indicates create ipv6 packets, default is 4 the -e option indicates that empty packets are to be created, where empty means the size of the l4 payload is 0 psp_encrypt ----------- Program to perform PSP encryption. Reads plaintext packets from a pcap input file. Performs the following for each packet: - Adds appropriate PSP encapsulation - Computes ICV - Encrypts data Then writes each PSP-encrypted packet to a pcap output Command Line Args: [-c psp_cfg_file_name] [-i in_file] [-o out_file] [-v] [-e] -v enables verbose mode -e forces a single bit error in each output packet, which will cause authentication to fail Defaults: psp_cfg_file: "psp_encrypt.cfg" in_file: "cleartext.pcap" out_file: "psp_encrypt.pcap" The format of the PSP encryption configuration file is: series of 32 hex bytes (e.g., 34 44 8a ...): Master Key 0 series of 32 hex bytes (e.g., 56 39 52 ...): Master Key 1 32b hex value (e.g., 9A345678), msb selects master key: SPI encap string (either "transport" or "tunnel"): PSP Encap Mode crypro algorithm string (either "aes-gcm-128" or "aes-gcm-256"): Crypto Algorithm non-negative integer with units of 4 bytes (e.g., 1): Transport Mode Crypt Offset non-negative integer with units of 4 bytes (e.g., 6): IPv4 Tunnel Mode Crypt Offset non-negative integer with units of 4 bytes (e.g., 11): IPv6 Tunnel Mode Crypt Offset virtual cookie string (either "vc" or "no-vc") Include VC in PSP Header The program uses OpenSSL crypto libraries. psp_decrypt ----------- Program to perform PSP decryption. Reads PSP-encrypted packets from a pcap input file. Performs the following for each packet: - Removes the PSP encapsulation (supports transport and tunnel encaps) - Checks that ICV is correct - Decrypts data Then writes each cleartext packet to a pcap output Command Line Args: [-c psp_cfg_file_name] [-i input_file_name] [-o output_file_name] [-v] -v enables verbose mode Defaults: psp_cfg_file: "psp_decrypt.cfg" input_file_name: "psp_encrypt.pcap" output_file_name: "psp_decrypt.pcap" The format of the PSP encryption configuration file is: series of 32 hex bytes (e.g., 34 44 8a ...): Master Key 0 series of 32 hex bytes (e.g., 56 39 52 ...): Master Key 1 The program uses OpenSSL crypto libraries. /pcap ===== Contains the following files with cleartext packets created by the create_pcap program: v4_cleartext.pcap v6_cleartext.pcap v4_cleartext_empty.pcap v6_cleartext_empty.pcap The cleartext packets are used as input for the test cases. The files with the '_empty' suffix contain packets with an L4 payload size of 0 bytes. There is also '.txt' version of each cleartext pcap file. These files have names of the form 'v4_cleartext_pcap.txt'. The '.txt' files are created using 'tcpdump' as follows: tcpdump -qns 0 -xx -r v4_cleartext.pcap > v4_cleartext_pcap.txt The purpose of the '.txt' files is to enable a 'diff' of the files input to the test cases and the files output by the test cases. In general, the test cases operate as follows: - a cleartext packet is encrypted by psp_encrypt - the output from psp_encrypt is used as input to psp_decrypt - the output from psp_decrypt is compared against the original cleartext packet Other pcap files will be created in the /pcap subdirectory when the test cases execute. /cfg ==== Contains configuration files used as input to psp_encrypt and psp_decrypt. There are multiple configuration files with different values for the various test cases. /test ===== Contains a suite of test cases, which are described below. all_tests execute all the test cases v4_transport_crypt_off_128 IPv4 input packet, transport mode encapsulation, encryption starts after L4 ports, AES-GCM-128, v4_transport_no_crypt_off_128 same as v4_transport_crypt_off_128 except encryption starts afer PSP header v4_transport_crypt_off_128_vc same as v4_transport_crypt_off_128 except PSP header includes a Virtualization Cookie (VC) field v4_transport_no_crypt_off_128_vc same as v4_transport_no_crypt_off_128 except PSP header includes a VC field, in this test case the VC field is encrypted v4_transport_crypt_off_128_empty similar to v4_transport_crypt_off_128 except size of L4 payload is 0 bytes and crypt off is configured such that no encryption is performed only authentication v4_transport_crypt_off_256 same as v4_transport_crypt_off_128 except uses AES-GCM-256 v4_transport_no_crypt_off_256 same as v4_transport_no_crypt_off_128 except uses AES-GCM-256 v4_transport_crypt_off_128_err a single bit error is forced in the packet after encryption and ICV computation, the expected result is an authentication failure v4_tunnel_crypt_off_128 v4_tunnel_no_crypt_off_128 v4_tunnel_crypt_off_256 v4_tunnel_no_crypt_off_256 same as transport mode tests with similar names except that tunnel mode encapsulation is used v6_transport_crypt_off_128 v6_transport_no_crypt_off_128 v6_transport_crypt_off_256 v6_transport_no_crypt_off_256 v6_tunnel_crypt_off_128 v6_tunnel_no_crypt_off_128 v6_tunnel_crypt_off_256 v6_tunnel_no_crypt_off_256 v6_tunnel_crypt_off_256_vc v6_tunnel_no_crypt_off_256_vc v6_tunnel_crypt_off_256_empty v6_tunnel_crypt_off_256_err same as IPv4 tests with similar names except that IPv6 input packet is used