PGP encryption
PGP is a standard set of encryption, decryption, and signing algorithms which provide cryptographic privacy and authentication.
When using PGP to encrypt payloads, partners must support:
- Encrypting and decrypting payloads with multiple PGP keys.
- Signing payloads with multiple PGP keys.
- Verifying a payload with multiple signatures, any one of which can be the signature with the key provided by Google.
- Decryption of Web-safe base64 encoded payloads.
PGP public keys provided to Google must have a subkey used for encryption. The subkey allows for independent rotation from the master key. The master key is used for identity verification. Private keys must be 2048 (or greater) bit RSA keys that expire in one year with a max lifetime of two years.
Before beginning development you need to exchange PGP keys with Google. In this step, you generate a PGP public-private key pair, provide the public key to Google, and receive a public key back from Google. During development, you will only need to exchange sandbox keys used for development and testing outside of production. Before production testing and launch, you will need to perform another exchange of production keys.
Generating a new PGP key
Assuming you have a GPG binary in your system path, you can use the following POSIX command to create a new key pair.
$ gpg --full-generate-key
When prompted, select an RSA key with at least 2048 bits of entropy and an expiration of 1-2 years. This command should create both a master key (labeled SC, for 'S'igning and 'C'ertificate generation) and a subkey (labeled E, for 'E'ncryption).
JWE encryption
JSON Web Encryption (JWE) is a standard defined by rfc7516 for encrypting content at the application level.
When using JWE to encrypt payloads, Partners must support the following options:
- Decrypting payloads from one of multiple JWE keys.
- Compact Serialization
- JWE compression (i.e., zip="DEF")
- The RSA-OAEP/RSA-OAEP-256 or ECDH-ES algorithms for key management
- RSAES-PKCS1-V1_5 is discouraged but acceptable
- The A256GCM algorithm for content encryption.
Private keys must be RSA/ECDH-ES keys that expire in one year with a max lifetime of two years. All private key identities must always stay on the partner's server and, accordingly, all signature values must be calculated on the partner's server.
The client and server will encrypt the JSON body in accordance with the JSON Web Encryption (JWE) specification. The entire body of the POST or response will be a JWE token, using JWE's "Compact Serialization" option.
Before beginning development you need to exchange JWE keys with Google. In this step, you generate a public-private key pair, provide the public key to Google, and receive a public key back from Google. During development, you will only need to exchange sandbox keys used for development and testing outside of production. Before production testing and launch, you will need to perform another exchange of production keys.
Partners must support sending and receiving messages using JWE compression (i.e., zip="DEF"). Requests and responses will be encrypted using asymmetric (public key) encryption using mutually exchanged JWE keys. Additionally, JWS signature verification can be used along with JWE where the content is signed before encryption and verified after decryption. JWS also uses asymmetric keys; private key for signing and public key for verification.