README

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