Encryption format
All encryption performed by JumpWire encodes data using the following format:
Length | Field |
1 byte | Label encoding type |
1 byte | Label length |
- | Labels |
1 byte | Key tag encoding type |
1 byte | Key tag length |
- | Key tag |
- | Ciphertext |
Labels are joined with the string | before encoding. The ciphertext may include additional metadata, depending on the algorithm used.
The key tag indicates both the encryption algorithm and the 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_ .
Several different modes are supported when encrypting with AES.
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:
Length | Field |
16 bytes | IV |
16 bytes | Auth tag |
- | Ciphertext |
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:
Length | Field |
16 bytes | IV |
- | Ciphertext |
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.
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.
Length | Field |
1 byte | KMS Key tag encoding type |
1 byte | KMS Key tag length |
- | KMS Key tag |
1 byte | KMS Key ID encoding type |
1 byte | KMS Key ID length |
- | KMS Key ID |
1 byte | Data key encoding type |
1 byte | Data key length |
- | Data key (encrypted with KMS key) |
| Encoded ciphertext (see base format above) |
