aws-kms-keyring.md

AWS KMS Keyring

Version

0.3.0

Changelog

• 0.3.0

  • Incorporate KMS Keyring Redesign

• 0.2.2

  • Rename Key IDs to Key Names for increased clarity
  • Update Key Names and Generator sections to reinforce support for all AWS KMS key identifiers
  • Pull request link for discussions

• 0.2.1

  • Clarify naming of KMS to AWS KMS

• 0.2.0

  • Remove Keyring Trace

• 0.1.0-preview

  • 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 keys.

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
• MUST provide an AWS KMS SDK client
• MAY provide a 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 MUST be the keyring's KMS key identifier.
• NumberOfBytes MUST be the key derivation input length specified by the algorithm suite included in the input encryption materials.
• EncryptionContext MUST be the encryption context included in the input encryption materials.
• GrantTokens MUST be 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 set the plaintext data key on the encryption materials as the response Plaintext.

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

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

• 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 MUST be the configured AWS KMS key identifier.
• PlaintextDataKey MUST be the plaintext data key in the encryption materials.
• EncryptionContext MUST be the encryption context included in the input encryption materials.
• GrantTokens MUST be 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 append a new encrypted data key to the encrypted data key list in the encryption materials, constructed as follows:

• The ciphertext MUST be the response CiphertextBlob.
• The key provider id MUST be "aws-kms".
• The key provider information MUST be 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 return an error.

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 provider info MUST match the configured AWS KMS key identifier.

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 MUST be the configured AWS KMS key identifier.
• CiphertextBlob MUST be the encrypted data key ciphertext.
• EncryptionContext MUST be the encryption context included in the input decryption materials.
• GrantTokens MUST be 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 satisfy these requirements then OnDecrypt:

• MUST set the plaintext data key on the decryption materials as the response Plaintext.
• MUST 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.