0.1.0-preview
A keyring which does local AES-GCM encryption and decryption of data keys using a local wrapping key.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Advanced Encryption Standard in Galois/Counter Mode (AES-GCM) is an Authenticated Encryption with Associated Data (AEAD) cipher.
Advanced Encryption Standard (AES) Specification: NIST FIPS 297
Galois/Counter Mode (GCM) Specification: NIST Special Publication 800-38D
On keyring initialization, the following inputs are REQUIRED:
A UTF-8 encoded value that, together with the key name, identifies a particular wrapping key.
This value is also used for bookkeeping purposes, for example recorded in keyring traces.
A UTF-8 encoded value that, together with the key namespace, identifies a particular wrapping key.
This value is also used for bookkeeping purposes, for example recorded in keyring traces.
The AES key input to AES-GCM to encrypt plaintext data keys
The wrapping key MUST be a secret value consisting of cryptographically secure pseudo-random bytes. It MUST be randomly generated from a cryptographically secure entropy source. The length of the wrapping key MUST be 128, 192, or 256.
This structure is a sequence of bytes in big-endian format to be used as the key provider information field in encrypted data keys produced by raw AES keyrings.
The following table describes the fields that form the raw AES keyring key provider information. The bytes are appended in the order shown.
| Field | Length (bytes) | Interpreted as |
|---|---|---|
| Key Name | length of Key Name | UTF-8 encoded bytes |
| Authentication Tag Length | 4 | UInt32 |
| IV Length | 4 | UInt32 |
| IV | IV Length | Bytes |
The Key Name of this keyring.
The length, in bits, of the authentication tag outputted by the AES-GCM encryption.
This value MUST be 128.
The length, in bytes, of the initialization vector (IV) inputted into the AES-GCM encryption.
This value MUST be 12.
The bytes to use as the IV in the AES-GCM encryption.
This structure is a sequence of bytes in big-endian format to be used as the ciphertext field in encrypted data keys produced by raw AES keyrings.
The following table describes the fields that form the ciphertext for this keyring. The bytes are appended in the order shown.
| Field | Length (bytes) | Interpreted as |
|---|---|---|
| Encrypted Key | length of AES-GCM ciphertext output | Bytes |
| Authentication Tag | Authentication Tag Length | Bytes |
The ciphertext outputted from the AES-GCM encryption of the plaintext data key.
The authentication tag outputted from the AES-GCM encryption.
On encrypt MUST take encryption materials as input.
If the encryption materials do not contain a plaintext data key, on encrypt MUST generate a random plaintext data key and set it on the encryption materials.
The keyring MUST encrypt the plaintext data key in the encryption materials using AES-GCM.
The keyring must use AES-GCM with the following specifics:
- it uses the encryption context in the encryption materials as the additional authenticated data (AAD)
- the AAD is serialized in the same format as the serialization of message header AAD key value pairs
- it uses this keyring's wrapping key as the AES-GCM cipher key
- it uses a randomly generated IV of 12 bytes
- it uses a authentication tag bit length of 128
Based on the ciphertext output of the AES-GCM decryption, the keyring MUST construct an encrypted data key with the following specifics:
- the key provider ID is this keyring's key namespace
- the key provider information is serialized as the raw AES keyring key provider information
- the ciphertext is serialized as the raw AES keyring ciphertext
The keyring MUST append the constructed encrypted data key to the encrypted data key list in the encryption materials.
The keyring MUST append a record to the keyring trace in the input encryption materials. This record MUST contain this keyring's key name and key namespace, and the flags field of this record MUST include the following flags:
If this keyring generated the plaintext data key in the encryption materials, the keyring trace in the returned encryption materials MUST also include a record that contains this keyring's key name and key namespace with a flags field containing the GENERATED DATA KEY flag. Note that this MAY be the same trace as the one with the ENCRYPTED DATA KEY flag.
On encrypt MUST output the modified encryption materials.
On decrypt MUST take decryption materials and a list of encrypted data keys as input.
The keyring MUST perform the following actions on each encrypted data key in the input encrypted data key list, serially, until it successfully decrypts one.
For each encrypted data key, the keyring MUST first attempt to deserialize the serialized ciphertext to obtain the encrypted key and authentication tag, and deserialize the serialized key provider info to obtain the key name, IV, IV length, and authentication tag length.
The keyring MUST attempt to decrypt the encrypted data key if and only if the following is true:
- the ciphertext and key provider information are successfully deserialized.
- the key name obtained from the encrypted data key's key provider information has a value equal to this keyring's key name.
- the key provider ID of the encrypted data key has a value equal to this keyring's key namespace.
- the IV length obtained from the encrypted data key's key provider information has a value equal to 12.
- the authentication tag length obtained from the key provider information has a value equal to 128.
If decrypting, the keyring MUST use AES-GCM with the following specifics:
- it uses the encrypt key obtained from deserialization as the AES-GCM input ciphertext.
- it uses the authentication tag obtained from deserialization as the AES-GCM input authentication tag.
- it uses this keyring's wrapping key as the AES-GCM cipher key.
- it uses the IV obtained from deserialization as the AES-GCM IV.
- it uses the encryption context from the decryption materials as the AES-GCM AAD.
- the AAD is serialized in the same format as the serialization of message header AAD key value pairs
If a decryption succeeds, this keyring MUST:
- append a new record to the keyring trace in the input decryption materials. This record MUST contain this keyring's key name and key namespace, and the flags field of this record MUST include the following flags:
- add the resulting plaintext data key to the decryption materials and return the modified materials.
If no decryption succeeds, the decryption MUST NOT make any update to the decryption materials.
[TODO: What security properties are guaranteed by this keyring]
- IV exhaustion/how many keys can we wrap this way?
- wrapping key use; both how many times it is used to encrypt data keys and where/whether/how it is used elsewhere.
- Does not write any information about what wrapping algorithm suite was used to wrap the data key.
- Puts data that doesn't belong in the provider info, into the provider info