Application layer encryption

Cards QR APIs support either PGP or JWE for application layer encryption.

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 maximum 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).

PGP Library Configuration

Sending Payloads

  1. When signing, you should use SHA384 as the digest algorithm; do not use SHA1or MD5
  2. When encrypting, you should use AES256 as the symmetric encryption algorithm; do not use CAST5 or IDEA
  3. When encrypting or signing messages, be sure to select the sub key with the corresponding purpose; use the CAN_SIGN key for signing and the ENCRYPT_COMMS/ENCRYPT_STORAGE key for encrypting

Receiving Payloads

  1. When verifying a payload, make sure your library supports modern hash algorithms like SHA384. Google will begin using it on all new keys as of May 14, 2023.
  2. When decrypting a payload, make sure your library supports modern symmetric encryption algorithms like AES256. Google will begin using it on all new keys as of May 14, 2023.

GPG Payload Encryption Example

The below command is an example of how to select secure options when using GPG. It is expected that this operation is performed in a trusted environment where people do not have access to the private keys or sensitive input files.

gpg --output signed-and-encrypted.pgp \
  --sign --digest-algo SHA384 \
  --encrypt --cipher-algo AES256 \
  --armor \
  --recipient {key_id} \
  input.txt

GPG will automatically select the right key from the bundle for each operation you ask it to perform.