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.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.NOTHING, grant_tokens=_Nothing.NOTHING)

Bases: 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: MasterKey

Master Key class for KMS CMKs.

Parameters

config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyConfig) – Configuration object (config or individual parameters required)
key_id (bytes) – KMS CMK ID
client (botocore.client.KMS) – Boto3 KMS client
grant_tokens (list) – List of grant tokens to pass to KMS on CMK operations

Performs transformations needed for KMS.

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

Bases: 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: 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

config (aws_encryption_sdk.key_providers.kms.KMSMasterKeyConfig) – Configuration object (config or individual parameters required)
key_id (bytes) – KMS CMK ID
client (botocore.client.KMS) – Boto3 KMS client
grant_tokens (list) – List of grant tokens to pass to KMS on CMK operations

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.NOTHING, key_ids=_Nothing.NOTHING, region_names=_Nothing.NOTHING, grant_tokens=_Nothing.NOTHING, discovery_filter=None, discovery_region=None)

Bases: 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: 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 KMSMasterKey

master_key_config_class: alias of 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: 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: 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 MRKAwareKMSMasterKey

master_key_config_class: alias of 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: 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: 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.