aws-kms-mrk-keyring.md

AWS KMS MRK Keyring

Version

0.2.2

Changelog

• 0.2.2

  • Initial record

Implementations

Language	Confirmed Compatible with Spec Version	Minimum Version Confirmed	Implementation

Overview

A keyring which interacts with AWS Key Management Service (AWS KMS) to create, encrypt, and decrypt data keys using AWS KMS defined Customer Master Keys (CMKs).

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.

Interface

MUST implement the AWS Encryption SDK Keyring interface

Initialization

On initialization the caller MUST provide:

• An AWS KMS key identifier
• An AWS KMS SDK client
• An optional list of Grant Tokens

The AWS KMS key identifier MUST NOT be null or empty. The AWS KMS key identifier MUST be a valid identifier. The AWS KMS SDK client MUST NOT be null.

OnEncrypt

OnEncrypt MUST take encryption materials as input.

If the input encryption materials do not contain a plaintext data key OnEncrypt MUST attempt to generate a new plaintext data key by calling AWS KMS GenerateDataKey.

If the keyring calls AWS KMS GenerateDataKeys, it MUST use the configured AWS KMS client to make the call. The keyring MUST call AWS KMS GenerateDataKeys with a request constructed as follows:

• KeyId: this keyring's KMS key identifier.
• NumberOfBytes: the key derivation input length specified by the algorithm suite included in the input encryption materials.
• EncryptionContext: the encryption context included in the input encryption materials.
• GrantTokens: this keyring's grant tokens

If the call to AWS KMS GenerateDataKey does not succeed, OnEncrypt MUST NOT modify the encryption materials and MUST fail.

If the Generate Data Key call succeeds, OnEncrypt MUST verify that the response Plaintext length matches the specification of the algorithm suite's Key Derivation Input Length field. The Generate Data Key response’s KeyId MUST be A valid AWS KMS key ARN. If verified, OnEncrypt MUST do the following with the response from AWS KMS GenerateDataKey:

• set the plaintext data key on the encryption materials as the response Plaintext.

• append a new encrypted data key to the encrypted data key list in the encryption materials, constructed as follows:

  • the ciphertext is the response CiphertextBlob.
  • the key provider id is "aws-kms".
  • the key provider information is the response KeyId.

• OnEncrypt MUST output the modified encryption materials

If the input encryption materials do contain a plaintext data key, OnEncrypt MUST attempt to encrypt the plaintext data key using the configured AWS KMS key identifier.

The keyring MUST call AWS KMS Encrypt using the configured AWS KMS client. The keyring MUST AWS KMS Encrypt call with a request constructed as follows:

• KeyId: The configured AWS KMS key identifier.

• PlaintextDataKey: the plaintext data key in the encryption materials.

• EncryptionContext: the encryption context included in the input encryption materials.

• GrantTokens: this keyring's grant tokens

If the call to AWS KMS Encrypt does not succeed, OnEncrypt MUST fail.

If the Encrypt call succeeds the response’s KeyId MUST be A valid AWS KMS key ARN. If verified, OnEncrypt MUST do the following with the response from AWS KMS Encrypt:

• append a new encrypted data key to the encrypted data key list in the encryption materials, constructed as follows:

  • The ciphertext is the response CiphertextBlob.
  • The key provider id is "aws-kms".
  • The key provider information is the response KeyId. Note that the KeyId in the response is always in key ARN format.

If all Encrypt calls succeed, 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 contained a valid plaintext data key OnDecrypt MUST immediately return the unmodified decryption materials.

The set of encrypted data keys MUST first be filtered to match this keyring’s configuration. For the encrypted data key to match

• Its provider ID MUST exactly match the value “aws-kms”.
• The provider info MUST be a valid AWS KMS ARN with a resource type of key or OnDecrypt MUST fail.
• The the function AWS KMS MRK Match for Decrypt called with the configured AWS KMS key identifier and the provider info MUST return true.

For each encrypted data key in the filtered set, one at a time, the OnDecrypt MUST attempt to decrypt the data key. If this attempt results in an error, then these errors MUST be collected.

To attempt to decrypt a particular encrypted data key, OnDecrypt MUST call AWS KMS Decrypt with the configured AWS KMS client.

When calling AWS KMS Decrypt, the keyring MUST call with a request constructed as follows:

• KeyId: The configured AWS KMS key identifier.

• CiphertextBlob: the encrypted data key ciphertext.

• EncryptionContext: the encryption context included in the input decryption materials.

• GrantTokens: this keyring's grant tokens

If the call to AWS KMS Decrypt succeeds OnDecrypt verifies

• The KeyId field in the response MUST equal the configured AWS KMS key identifier.
• The length of the response’s Plaintext MUST equal the key derivation input length specified by the algorithm suite included in the input decryption materials.

If the response does not satisfies these requirements then an error MUST be collected and the next encrypted data key in the filtered set MUST be attempted.

If the response does satisfies these requirements then OnDecrypt MUST do the following with the response:

• set the plaintext data key on the decryption materials as the response Plaintext.
• immediately return the modified decryption materials.

If OnDecrypt fails to successfully decrypt any encrypted data key, then it MUST yield an error that includes all the collected errors.