Skip to content

Latest commit

 

History

History
231 lines (148 loc) · 12.2 KB

raw-aes-keyring.md

File metadata and controls

231 lines (148 loc) · 12.2 KB

Raw AES Keyring

Version

0.4.1

Changelog

Implementations

Language Confirmed Compatible with Spec Version Minimum Version Confirmed Implementation
C 0.1.0-preview 0.1.0 raw_aes_keyring.c
NodeJS 0.1.0-preview 0.1.0 raw_aes_keyring_node.ts
Browser JS 0.1.0-preview 0.1.0 raw_aes_keyring_browser.ts
Python 0.1.0-preview n/a keyrings/raw.py
Java 0.1.0-preview n/a RawAesKeyring.java

Overview

A keyring which does local AES-GCM encryption and decryption of data keys using a local wrapping key.

Definitions

Conventions used in this document

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.

AES-GCM

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

Initialization

On keyring initialization, the caller MUST provide the following:

Wrapping Key

The AES key input to be used with the configured wrapping algorithm 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.

Wrapping Algorithm

The algorithm to be used with the configured wrapping key to encrypt plaintext data keys.

The keyring MUST support the following algorithm configurations:

  • AES_GCM with key size 128 bits, IV length 12 bytes, and tag length 16 bytes
  • AES_GCM with key size 192 bits, IV length 12 bytes, and tag length 16 bytes
  • AES_GCM with key size 256 bits, IV length 12 bytes, and tag length 16 bytes

Initialization MUST fail if the length of the wrapping key does not match the length specified by the wrapping algorithm.

Structure

Key Provider Information

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

Key Name

The Key Name of this keyring.

Authentication Tag Length

The length, in bits, of the authentication tag returned by the AES-GCM encryption.

This value MUST match the authentication tag length of the keyring's configured wrapping algorithm.

IV Length

The length, in bytes, of the initialization vector (IV) input into the AES-GCM encryption.

This value MUST match the IV length of the keyring's configured wrapping algorithm.

IV

The bytes to use as the IV in the AES-GCM encryption.

Ciphertext

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 as Bytes Bytes

Encrypted Key

The ciphertext returned by the AES-GCM encryption of the plaintext data key.

Authentication Tag

The authentication tag returned by the AES-GCM encryption.

Operation

OnEncrypt

OnEncrypt MUST take encryption materials as input.

If the encryption materials do not contain a plaintext data key, OnEncrypt 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 attempt to serialize the encryption materials' encryption context according to the encryption context serialization specification. If the keyring cannot serialize the encryption context, OnEncrypt MUST fail.

The keyring uses AES-GCM with the following specifics:

  • It MUST use the serialized encryption context as the additional authenticated data (AAD).
  • It MUST use this keyring's wrapping key as the AES-GCM cipher key.
  • It MUST use a cryptographically random generated IV of length specified by this keyring's wrapping algorithm.
  • It MUST use an authentication tag bit of length specified by this keyring's wrapping algorithm.

Based on the ciphertext output of the AES-GCM decryption, the keyring MUST construct an encrypted data key with the following specifics:

The keyring MUST append the constructed encrypted data key to the encrypted data key list in the encryption materials.

OnEncrypt MUST output the modified encryption materials.

OnDecrypt

OnDecrypt MUST take decryption materials and a list of encrypted data keys as input.

If the decryption materials already contain a plaintext data key, the keyring MUST fail and MUST NOT modify the decryption materials.

The keyring MUST attempt to serialize the decryption materials' encryption context according to the encryption context serialization specification. If the keyring cannot serialize the encryption context, OnDecrypt MUST fail.

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 attempts to decrypt the encrypted data key if and only if the following is true:

  • The ciphertext and key provider information MUST be successfully deserialized.
  • The key name obtained from the encrypted data key's key provider information MUST have a value equal to this keyring's key name.
  • The key provider ID of the encrypted data key MUST have a value equal to this keyring's key namespace.
  • The IV length obtained from the encrypted data key's key provider information MUST have a value equal to the length specified by this keyring's wrapping algorithm.
  • The authentication tag length obtained from the key provider information MUST have a value equal to the length specified by this keyring's wrapping algorithm.

If decrypting, the keyring uses AES-GCM with the following specifics:

  • It MUST use the encrypt key obtained from deserialization as the AES-GCM input ciphertext.
  • It MUST use the authentication tag obtained from deserialization as the AES-GCM input authentication tag.
  • It MUST use this keyring's wrapping key as the AES-GCM cipher key.
  • It MUST use the IV obtained from deserialization as the AES-GCM IV.
  • It MUST use the serialized encryption context as the AES-GCM AAD.

If a decryption succeeds, this keyring MUST add the resulting plaintext data key to the decryption materials and return the modified materials.

If no decryption succeeds, the keyring MUST fail and MUST NOT modify the decryption materials.