Keyring for use with AWS Key Management Service (KMS).

New in version 2.0.0.


AwsKmsKeyring([client_supplier, …]) Keyring that uses AWS Key Management Service (KMS) Customer Master Keys (CMKs) to manage wrapping keys.
class aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring(client_supplier=NOTHING, is_discovery=False, generator_key_id=None, key_ids=NOTHING, grant_tokens=NOTHING)

Bases: aws_encryption_sdk.keyrings.base.Keyring

Keyring that uses AWS Key Management Service (KMS) Customer Master Keys (CMKs) to manage wrapping keys.

Set generator_key_id to require that the keyring use that CMK to generate the data key. If you do not set generator_key_id, the keyring will not generate a data key.

Set key_ids to specify additional CMKs that the keyring will use to encrypt the data key.

The keyring will attempt to use any CMKs identified by CMK ARN in either generator_key_id or key_ids on decrypt.

You can identify CMKs by any valid key ID for the keyring to use on encrypt, but for the keyring to attempt to use them on decrypt you MUST specify the CMK ARN.

If you specify is_discovery=True the keyring will be a KMS discovery keyring, doing nothing on encrypt and attempting to decrypt any AWS KMS-encrypted data key on decrypt.


You must either set is_discovery=True or provide key IDs.

You can use the ClientSupplier to customize behavior further, such as to provide different credentials for different regions or to restrict which regions are allowed.

See the AWS KMS Keyring specification for more details.

New in version 2.0.0.

  • client_supplier (ClientSupplier) – Client supplier that provides AWS KMS clients (optional)
  • is_discovery (bool) – Should this be a discovery keyring (optional)
  • generator_key_id (str) – Key ID of AWS KMS CMK to use when generating data keys (optional)
  • key_ids (List[str]) – Key IDs that will be used to encrypt and decrypt data keys (optional)
  • grant_tokens (List[str]) – AWS KMS grant tokens to include in requests (optional)
on_decrypt(decryption_materials, encrypted_data_keys)

Attempt to decrypt the encrypted data keys.


Optionally modified decryption materials.

Return type:



Generate a data key using generator keyring and encrypt it using any available wrapping key in any child keyring.

Parameters:encryption_materials (EncryptionMaterials) – Encryption materials for keyring to modify.
Returns:Optionally modified encryption materials.
Return type:EncryptionMaterials
Raises:EncryptKeyError – if unable to encrypt data key.