aws_encryption_sdk.key_providers.kms

Master Key Providers for use with AWS KMS

Classes

BaseKMSMasterKeyProvider(**kwargs)

Master Key Provider for KMS.

DiscoveryAwsKmsMasterKeyProvider(**kwargs)

Discovery Master Key Provider for KMS. This can only be used for decryption. It is configured with an optional

DiscoveryFilter([account_ids, partition])

DiscoveryFilter to control accounts and partitions that can be used by a KMS Master Key Provider.

KMSMasterKey(**kwargs)

Master Key class for KMS CMKs.

KMSMasterKeyConfig(key_id[, client, ...])

Configuration object for KMSMasterKey objects.

KMSMasterKeyProviderConfig([...])

Configuration object for KMSMasterKeyProvider objects.

MRKAwareDiscoveryAwsKmsMasterKeyProvider(...)

Discovery Master Key Provider for KMS that has smarts for handling Multi-Region keys

MRKAwareKMSMasterKey(**kwargs)

Master Key class for KMS MRKAware CMKs.

MRKAwareKMSMasterKeyConfig(key_id, client[, ...])

Configuration object for MRKAwareKMSMasterKey objects.

MRKAwareStrictAwsKmsMasterKeyProvider(**kwargs)

A Strict Master Key Provider for KMS that has smarts for handling Multi-Region keys.

StrictAwsKmsMasterKeyProvider(**kwargs)

Strict Master Key Provider for KMS.

class aws_encryption_sdk.key_providers.kms.DiscoveryFilter(account_ids=NOTHING, partition=None)

Bases: object

DiscoveryFilter to control accounts and partitions that can be used by a KMS Master Key Provider.

Parameters
  • account_ids (list) – List of AWS Account Ids that are allowed to be used for decryption

  • partition (str) – The AWS partition to which account_ids belong

Method generated by attrs for class DiscoveryFilter.

class aws_encryption_sdk.key_providers.kms.KMSMasterKeyConfig(key_id, client=NOTHING, grant_tokens=NOTHING)

Bases: aws_encryption_sdk.key_providers.base.MasterKeyConfig

Configuration object for KMSMasterKey objects.

Parameters
  • key_id (str) – KMS CMK ID

  • client (botocore.client.KMS) – Boto3 KMS client

  • grant_tokens (list) – List of grant tokens to pass to KMS on CMK operations

Method generated by attrs for class KMSMasterKeyConfig.

client_default()

Create a client if one was not provided.

class aws_encryption_sdk.key_providers.kms.KMSMasterKey(**kwargs)

Bases: aws_encryption_sdk.key_providers.base.MasterKey

Master Key class for KMS CMKs.

Parameters

Performs transformations needed for KMS.

class aws_encryption_sdk.key_providers.kms.MRKAwareKMSMasterKeyConfig(key_id, client, grant_tokens=NOTHING)

Bases: aws_encryption_sdk.key_providers.base.MasterKeyConfig

Configuration object for MRKAwareKMSMasterKey objects. Mostly the same as KMSMasterKey, except the client parameter is required rather than optional.

Parameters
  • key_id (str) – KMS CMK ID

  • client (botocore.client.KMS) – Boto3 KMS client

  • grant_tokens (list) – List of grant tokens to pass to KMS on CMK operations

Method generated by attrs for class MRKAwareKMSMasterKeyConfig.

class aws_encryption_sdk.key_providers.kms.MRKAwareKMSMasterKey(**kwargs)

Bases: aws_encryption_sdk.key_providers.kms.KMSMasterKey

Master Key class for KMS MRKAware CMKs. The logic for this class is almost entirely the same as a normal KMSMasterKey (“single-region key”). The primary difference is that this class is more flexible in what ciphertexts it will try to decrypt; specifically, it knows how to treat related multi-region keys as identical for the purposes of checking whether it is allowed to decrypt.

Parameters

Sets configuration required by this provider type.

validate_config()

Validates the provided configuration.

owns_data_key(data_key)

Determines if data_key object is owned by this MasterKey. This method overrides the method from the base class, because for MRKs we need to check for MRK equality on the key ids rather than exact string equality.

Parameters

data_key (aws_encryption_sdk.structures.DataKey, aws_encryption_sdk.structures.RawDataKey, or aws_encryption_sdk.structures.EncryptedDataKey) – Data key to evaluate

Returns

Boolean statement of ownership

Return type

bool

class aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig(botocore_session=NOTHING, key_ids=NOTHING, region_names=NOTHING, grant_tokens=NOTHING, discovery_filter=None, discovery_region=None)

Bases: aws_encryption_sdk.key_providers.base.MasterKeyProviderConfig

Configuration object for KMSMasterKeyProvider objects.

Parameters
  • botocore_session (botocore.session.Session) – botocore session object (optional)

  • key_ids (list) – List of KMS CMK IDs with which to pre-populate provider (optional)

  • region_names (list) – List of regions for which to pre-populate clients (optional)

  • grant_tokens (list) – List of grant tokens to pass to KMS on CMK operations

  • discovery_filter (DiscoveryFilter) – Filter indicating AWS accounts and partitions whose keys will be trusted for decryption

  • discovery_region (str) – The region to be used for discovery for MRK-aware providers

Method generated by attrs for class KMSMasterKeyProviderConfig.

class aws_encryption_sdk.key_providers.kms.BaseKMSMasterKeyProvider(**kwargs)

Bases: aws_encryption_sdk.key_providers.base.MasterKeyProvider

Master Key Provider for KMS.

Note

Cannot be instantiated directly. Callers should use one of the implementing classes.

Prepares mutable attributes.

master_key_class

alias of aws_encryption_sdk.key_providers.kms.KMSMasterKey

master_key_config_class

alias of aws_encryption_sdk.key_providers.kms.KMSMasterKeyConfig

abstract validate_config()

Validates the provided configuration.

Note

Must be implemented by specific KMSMasterKeyProvider implementations.

add_regional_client(region_name)

Adds a regional client for the specified region if it does not already exist.

Parameters

region_name (str) – AWS Region ID (ex: us-east-1)

add_regional_clients_from_list(region_names)

Adds multiple regional clients for the specified regions if they do not already exist.

Parameters

region_names (list) – List of regions for which to pre-populate clients

class aws_encryption_sdk.key_providers.kms.StrictAwsKmsMasterKeyProvider(**kwargs)

Bases: aws_encryption_sdk.key_providers.kms.BaseKMSMasterKeyProvider

Strict Master Key Provider for KMS. It is configured with an explicit list of AWS KMS master keys that should be used for encryption and decryption. On encryption, the plaintext will be encrypted with all configured master keys. On decryption, it only attempts to decrypt ciphertexts that have been wrapped with a CMK that matches one of the configured CMK ARNs. If the ciphertext is encrypted with a master key that was not explicitly configured, decryption will fail. To create a StrictAwsKmsMasterKeyProvider you must provide one or more CMKs. For providers that will only be used for encryption, you can use any valid KMS key identifier. For providers that will be used for decryption, you must use the key ARN; key ids, alias names, and alias ARNs are not supported.

>>> import aws_encryption_sdk
>>> kms_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(key_ids=[
...     'arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222',
...     'arn:aws:kms:us-east-1:3333333333333:key/33333333-3333-3333-3333-333333333333'
... ])

Note

If no botocore_session is provided, the default botocore session will be used.

Note

If multiple AWS Identities are needed, one of two options are available:

  • Additional KMSMasterKeyProvider instances may be added to the primary MasterKeyProvider.

  • KMSMasterKey instances may be manually created and added to this KMSMasterKeyProvider.

Parameters
  • config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig) – Configuration object (optional)

  • botocore_session (botocore.session.Session) – botocore session object (optional)

  • key_ids (list) – List of KMS CMK IDs with which to pre-populate provider (optional)

  • region_names (list) – List of regions for which to pre-populate clients (optional)

Sets configuration required by this provider type.

validate_config()

Validates the provided configuration.

class aws_encryption_sdk.key_providers.kms.MRKAwareStrictAwsKmsMasterKeyProvider(**kwargs)

Bases: aws_encryption_sdk.key_providers.kms.StrictAwsKmsMasterKeyProvider

A Strict Master Key Provider for KMS that has smarts for handling Multi-Region keys.

TODO MORE

Parameters
  • config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig) – Configuration object (optional)

  • botocore_session (botocore.session.Session) – botocore session object (optional)

  • key_ids (list) – List of KMS CMK IDs with which to pre-populate provider (optional)

  • region_names (list) – List of regions for which to pre-populate clients (optional)

Sets configuration required by this provider type.

master_key_class

alias of aws_encryption_sdk.key_providers.kms.MRKAwareKMSMasterKey

master_key_config_class

alias of aws_encryption_sdk.key_providers.kms.MRKAwareKMSMasterKeyConfig

validate_unique_mrks()

Make sure the set of configured key ids does not contain any related MRKs

class aws_encryption_sdk.key_providers.kms.DiscoveryAwsKmsMasterKeyProvider(**kwargs)

Bases: aws_encryption_sdk.key_providers.kms.BaseKMSMasterKeyProvider

Discovery Master Key Provider for KMS. This can only be used for decryption. It is configured with an optional

Discovery Filter containing AWS account ids and partitions that should be trusted for decryption. If a ciphertext was encrypted with an AWS KMS master key that matches an account and partition listed by this provider, decryption will succeed. Otherwise, decryption will fail. If no Discovery Filter is configured, the provider will attempt to decrypt any ciphertext created by an AWS KMS Master Key Provider.

>>> import aws_encryption_sdk
>>> kms_key_provider = aws_encryption_sdk.DiscoveryAwsKmsMasterKeyProvider(discovery_filter=DiscoveryFilter(
...     account_ids=['2222222222222', '3333333333333']
... )

Note

If no botocore_session is provided, the default botocore session will be used.

Parameters
  • config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig) – Configuration object (optional)

  • botocore_session (botocore.session.Session) – botocore session object (optional)

  • key_ids (list) – List of KMS CMK IDs with which to pre-populate provider (optional)

  • region_names (list) – List of regions for which to pre-populate clients (optional)

Sets configuration required by this provider type.

validate_config()

Validates the provided configuration.

class aws_encryption_sdk.key_providers.kms.MRKAwareDiscoveryAwsKmsMasterKeyProvider(**kwargs)

Bases: aws_encryption_sdk.key_providers.kms.DiscoveryAwsKmsMasterKeyProvider

Discovery Master Key Provider for KMS that has smarts for handling Multi-Region keys

TODO MORE

Note

If no botocore_session is provided, the default botocore session will be used.

Parameters
  • config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig) – Configuration object (optional)

  • botocore_session (botocore.session.Session) – botocore session object (optional)

  • key_ids (list) – List of KMS CMK IDs with which to pre-populate provider (optional)

  • region_names (list) – List of regions for which to pre-populate clients (optional)

Sets configuration required by this provider type.

validate_config()

Validates the provided configuration.