aws_encryption_sdk.key_providers.base

Base class interface for Master Key Providers.

Classes

`MasterKey`(**kwargs)	Parent interface for Master Key classes.
`MasterKeyConfig`(key_id)	Configuration object for MasterKey objects.
`MasterKeyProvider`(**kwargs)	Parent interface for Master Key Provider classes.
`MasterKeyProviderConfig`()	Provides a common ancestor for MasterKeyProvider configuration objects and a stand-in point if common params are needed later.

class aws_encryption_sdk.key_providers.base.MasterKeyProviderConfig

Bases: object

Provides a common ancestor for MasterKeyProvider configuration objects and a stand-in point if common params are needed later.

Method generated by attrs for class MasterKeyProviderConfig.

class aws_encryption_sdk.key_providers.base.MasterKeyProvider(**kwargs)

Bases: object

Parent interface for Master Key Provider classes.

Parameters: config (aws_encryption_sdk.key_providers.base.MasterKeyProviderConfig) – Configuration object

Set key index and member set for all new instances here to avoid requiring child classes to call super init.

vend_masterkey_on_decrypt = True: Determines whether a MasterKeyProvider attempts to add a MasterKey on decrypt_data_key call.

abstract provider_id(): String defining provider ID.

Note

Must be implemented by specific MasterKeyProvider implementations.

master_keys_for_encryption(encryption_context, plaintext_rostream, plaintext_length=None)

Returns a set containing all Master Keys added to this Provider, or any member Providers, which should be used to encrypt data keys for the specified data.

Note

This does not necessarily include all Master Keys accessible from this Provider.

Note

The Primary Master Key is the first Master Key added to this Master Key Provider and is the Master Key which will be used to generate the data key.

Warning

If plaintext_rostream seek position is modified, it must be returned before leaving method.

Parameters

encryption_context (dict) – Encryption context passed to client
plaintext_rostream (aws_encryption_sdk.internal.utils.streams.ROStream) – Source plaintext read-only stream
plaintext_length (int) – Length of source plaintext (optional)

Returns

Tuple containing Primary Master Key and List of all Master Keys added to this Provider and any member Providers

Return type

tuple containing aws_encryption_sdk.key_providers.base.MasterKey and list of aws_encryption_sdk.key_providers.base.MasterKey

add_master_key(key_id)

Adds a single Master Key to this provider.

Parameters: key_id (bytes) – Key ID with which to create MasterKey

add_master_keys_from_list(key_ids)

Adds multiple Master Keys to this provider.

Parameters: key_ids (list) – List of Master Key IDs

add_master_key_provider(key_provider)

Adds a single Master Key Provider to this provider.

Parameters: key_provider (aws_encryption_sdk.key_providers.base.MasterKeyProvider) – Master Key Provider to add to this provider

add_master_key_providers_from_list(key_providers)

Adds multiple Master Key Providers to this provider.

Parameters: key_provider (list of aws_encryption_sdk.key_providers.base.MasterKeyProvider) – List of Master Key Providers to add to this provider

master_key_for_encrypt(key_id)

Returns a master key for encrypt based on the specified key_id, adding it to this provider if not already present.

Parameters: key_id (bytes) – Key ID with which to find or create Master Key
Returns: Master Key based on key_id
Return type: aws_encryption_sdk.key_providers.base.MasterKey

master_key(key_id)

Returns a master key for encrypt based on the specified key_id, adding it to this provider if not already present.

Parameters: key_id (bytes) – Key ID with which to find or create Master Key
Returns: Master Key based on key_id
Return type: aws_encryption_sdk.key_providers.base.MasterKey

master_key_for_decrypt(key_info)

Returns a master key for decrypt based on the specified key_info. This is only added to this master key provider for the decrypt path.

Parameters: key_info (bytes) – Key info from encrypted data key
Returns: Master Key based on key_info
Return type: aws_encryption_sdk.key_providers.base.MasterKey

decrypt_data_key(encrypted_data_key, algorithm, encryption_context)

Iterates through all currently added Master Keys and Master Key Providers to attempt to decrypt data key.

Parameters

encrypted_data_key (aws_encryption_sdk.structures.EncryptedDataKey) – Encrypted data key to decrypt
algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm object which directs how this Master Key will encrypt the data key
encryption_context (dict) – Encryption context to use in encryption

Returns

Decrypted data key

Return type

aws_encryption_sdk.structures.DataKey

Raises

DecryptKeyError – if unable to decrypt encrypted data key

decrypt_data_key_from_list(encrypted_data_keys, algorithm, encryption_context)

Receives a list of encrypted data keys and returns the first one which this provider is able to decrypt.

Parameters

encrypted_data_keys (list of aws_encryption_sdk.structures.EncryptedDataKey) – List of encrypted data keys
algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm object which directs how this Master Key will encrypt the data key
encryption_context (dict) – Encryption context to use in encryption

Returns

Decrypted data key

Return type

aws_encryption_sdk.structures.DataKey

Raises

DecryptKeyError – if unable to decrypt any of the supplied encrypted data keys

class aws_encryption_sdk.key_providers.base.MasterKeyConfig(key_id)

Bases: object

Configuration object for MasterKey objects.

Parameters: key_id (bytes) – Key ID for Master Key

Method generated by attrs for class MasterKeyConfig.

class aws_encryption_sdk.key_providers.base.MasterKey(**kwargs)

Bases: aws_encryption_sdk.key_providers.base.MasterKeyProvider

Parent interface for Master Key classes.

Parameters

key_id (bytes) – Key ID for Master Key
config (aws_encryption_sdk.key_providers.base.MasterKeyConfig) – Configuration object

Performs universal prep work for all MasterKeys.

property key_provider

Provides the MasterKeyInfo object identifying this MasterKey.

Returns: This MasterKey’s Identifying Information
Return type: aws_encryption_sdk.structures.MasterKeyInfo

owns_data_key(data_key)

Determines if data_key object is owned by this MasterKey.

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

master_keys_for_encryption(encryption_context, plaintext_rostream, plaintext_length=None)

Returns self and a list containing self, to match the format of output for a Master Key Provider.

Warning

If plaintext_stream seek position is modified, it must be returned before leaving method.

Parameters

encryption_context (dict) – Encryption context passed to client
plaintext_rostream (aws_encryption_sdk.internal.utils.streams.ROStream) – Source plaintext read-only stream
plaintext_length (int) – Length of source plaintext (optional)

Returns

Tuple containing self and a list of self

Return type

tuple containing aws_encryption_sdk.key_providers.base.MasterKey and list of aws_encryption_sdk.key_providers.base.MasterKey

generate_data_key(algorithm, encryption_context)

Generates and returns data key for use encrypting message.

Parameters

algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm on which to base data key
encryption_context (dict) – Encryption context to use in encryption

Returns

Generated data key

Return type

aws_encryption_sdk.structures.DataKey

encrypt_data_key(data_key, algorithm, encryption_context)

Encrypts a supplied data key.

Parameters

data_key (aws_encryption_sdk.structures.RawDataKey or aws_encryption_sdk.structures.DataKey) – Unencrypted data key
algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm object which directs how this Master Key will encrypt the data key
encryption_context (dict) – Encryption context to use in encryption

Returns

Data key containing encrypted data key

Return type

aws_encryption_sdk.structures.EncryptedDataKey

Raises

IncorrectMasterKeyError – if Data Key’s key provider does not match this Master Key

decrypt_data_key(encrypted_data_key, algorithm, encryption_context)

Decrypts an encrypted data key and returns the plaintext.

Parameters

encrypted_data_key (aws_encryption_sdk.structures.EncryptedDataKey) – Encrypted data key
algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm object which directs how this Master Key will encrypt the data key
encryption_context (dict) – Encryption context to use in decryption

Returns

Decrypted data key

Return type

aws_encryption_sdk.structures.DataKey

Raises

IncorrectMasterKeyError – if Data Key’s key provider does not match this Master Key