Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/google/psp


https://github.com/google/psp

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

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