AWS KMS Hierarchical keyring technical details - AWS Encryption SDK
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

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