Encryption format

Base format

All encryption performed by JumpWire encodes data using the following format:

Labels are joined with the string | before encoding. The ciphertext may include additional metadata, depending on the algorithmn used.

The key tag indicates both the encryption algorithm and specific key used. The key is identified by an MD5 fingerprint. For example, a tag of AES.GCM.V1.97FAD3230C7BCA8CC37515C3DE12E509 would indicate that the key 97FAD3230C7BCA8CC37515C3DE12E509 was used to encrypt the data with AES-GCM.

Finally, the resulting binary blob is Base64 encoded and prefixed with the identifier jumpwire_ .

AES Ciphertexts

Several different modes are supported when encrypting with AES.

AES-GCM

AES-GCM with a 256-bit key is used by default when encrypting data in flight in JumpWire. GCM mode uses a randomly generated 16-byte IV. The IV is prepended to the encrypted ciphertext before encoding the tag and labels.

The Ciphertext field in the base encryption format for AES-GCM contains the following:

AES-CBC

AES-CBC with a 256 bit key is used when configuring PostgreSQL or MySQL to encrypt data automatically on inserts and updates. Like AES-GCM, a 16-byte IV is randomly generated for each encryption operation.

The plaintext is padded to a block size of 16 bytes using PKCS#7 and the IV is prepended to the ciphertext before encoding tags and labels.

The Ciphertext field in the base encryption format for AES-CBC contains the following:

AES-ECB

AES-ECB with a 128 bit key is used when configuring MariaDB to encrypt data automatically on inserts and updates. MariaDB does not support any other modes.

The plaintext is padded to a block size of 16 bytes using PKCS#7. With AES-ECB, no IV is used so repeating encrypting with the same key and plaintext will generate identical ciphertexts.

The Ciphertext field in the base encryption format for AES-ECB does not contain any additional metadata.

AWS KMS

When using AWS KMS as the source of truth for encryption keys, there is some additional metadata encoded with each encryption operation. A data key is generated on startup from a master KMS key and cached in JumpWire (more details on this are available in the Encryption key stores article). The data key, encrypted with the master KMS key, is prepended to the AES encrypted ciphertext. This allows for keys to be decrypted on a cold-start without any risk of data loss.

The format for KMS encrypted data is below. The encoded ciphertext in this format encompasses all of the metadata used by an AES encryption - this is the output of the base format outlined above.