aws_encryption_sdk.key_providers.base

Base class interface for Master Key Providers.

Classes

MasterKey Parent interface for Master Key classes.
MasterKeyConfig(key_id) Configuration object for MasterKey objects.
MasterKeyProvider 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.MasterKey

Bases: aws_encryption_sdk.key_providers.base.MasterKeyProvider

Parent interface for Master Key classes.

Parameters:

Performs universal prep work for all MasterKeys.

decrypt_data_key(encrypted_data_key, algorithm, encryption_context)

Decrypts an encrypted data key and returns the plaintext.

Parameters:
  • 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

encrypt_data_key(data_key, algorithm, encryption_context)

Encrypts a supplied data key.

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

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

key_provider

Provides the MasterKeyInfo object identifying this MasterKey.

Returns:This MasterKey’s Identifying Information
Return type:aws_encryption_sdk.structures.MasterKeyInfo
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

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
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
class aws_encryption_sdk.key_providers.base.MasterKeyProvider

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.

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_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
add_master_keys_from_list(key_ids)

Adds multiple Master Keys to this provider.

Parameters:key_ids (list) – List of Master Key IDs
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

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
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_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

provider_id

String defining provider ID.

Note

Must be implemented by specific MasterKeyProvider implementations.

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.