AWS KMS Hierarchical keyring technical details - AWS Encryption SDK

AWS KMS Hierarchical keyring technical details

The AWS KMS Hierarchical keyring uses a unqiue data key to encrypt each message and encrypts each data key with a unique wrapping key derived from an active branch key. It uses a key derivation in counter mode with a pseudorandom function with HMAC SHA-256 to derive the 32 byte wrapping key with the following inputs.

  • A 16 byte random salt

  • The active branch key

  • The UTF-8 encoded value for the key provider identifier "aws-kms-hierarchy"

The Hierarchical keyring uses the derived wrapping key to encrypt a copy of the plaintext data key using AES-GCM-256 with a 16 byte authentication tag and the following inputs.

  • The derived wrapping key is used as the AES-GCM cipher key

  • The data key is used as the AES-GCM message

  • A 12 byte random initialization vector (IV) is used as the AES-GCM IV

  • Additional authenticated data (AAD) containing the following serialized values.

    Value Length in bytes Interpreted as
    "aws-kms-hierarchy" 17 UTF-8 encoded
    The branch key identifier Variable UTF-8 encoded
    The branch key version 16 UTF-8 encoded
    Encryption context Variable UTF-8 encoded key value pairs