Prerequisites Installation Version 4.x of the AWS Encryption SDK for Python

AWS Encryption SDK for Python

This topic explains how to install and use the AWS Encryption SDK for Python. For details about programming with the AWS Encryption SDK for Python, see the aws-encryption-sdk-python repository on GitHub. For API documentation, see Read the Docs.

Topics

Prerequisites
Installation
Version 4.x of the AWS Encryption SDK for Python
Examples

Prerequisites

Before you install the AWS Encryption SDK for Python, be sure you have the following prerequisites.

A supported version of Python

Python 3.8 or later is required by the AWS Encryption SDK for Python versions 3.2.0 and later.

Note

The AWS Cryptographic Material Providers Library (MPL) is an optional dependency for the AWS Encryption SDK for Python introduced in version 4.x. If you intend to install the MPL, you must use Python 3.11 or later.

Earlier versions of the AWS Encryption SDK support Python 2.7 and Python 3.4 and later, but we recommend that you use the latest version of the AWS Encryption SDK.

To download Python, see Python downloads.

The pip installation tool for Python

pip is included in Python 3.6 and later versions, although you might want to upgrade it. For more information about upgrading or installing pip, see Installation in the pip documentation.

Installation

Install the latest version of the AWS Encryption SDK for Python.

Note

All versions of the AWS Encryption SDK for Python earlier than 3.0.0 are in the end-of-support phase.

You can safely update from version 2.0.x and later to the latest version of the AWS Encryption SDK without any code or data changes. However, new security features introduced in version 2.0.x are not backward-compatible. To update from versions earlier than 1.7.x to version 2.0.x and later, you must first update to the latest 1.x version of the AWS Encryption SDK. For details, see Migrating your AWS Encryption SDK.

Use pip to install the AWS Encryption SDK for Python, as shown in the following examples.

To install the latest version


pip install "aws-encryption-sdk[MPL]"

The [MPL] suffix installs the AWS Cryptographic Material Providers Library (MPL). The MPL contains constructs for encrypting and decrypting your data. The MPL is an optional dependency for the AWS Encryption SDK for Python introduced in version 4.x. We highly recommend installing the MPL. However, if you do not intend to use the MPL, you can omit the [MPL] suffix.

For more details about using pip to install and upgrade packages, see Installing Packages.

The AWS Encryption SDK for Python requires the cryptography library (pyca/cryptography) on all platforms. All versions of pip automatically install and build the cryptography library on Windows. pip 8.1 and later automatically installs and builds cryptography on Linux. If you are using an earlier version of pip and your Linux environment doesn't have the tools needed to build the cryptography library, you need to install them. For more information, see Building Cryptography on Linux.

Versions 1.10.0 and 2.5.0 of the AWS Encryption SDK for Python pin the cryptography dependency between 2.5.0 and 3.3.2. Other versions of the AWS Encryption SDK for Python install the latest version of cryptography. If you require a version of cryptography later than 3.3.2, we recommend that you use the latest major version of the AWS Encryption SDK for Python.

For the latest development version of the AWS Encryption SDK for Python, go to the aws-encryption-sdk-python repository in GitHub.

After you install the AWS Encryption SDK for Python, get started by looking at the Python example code in this guide.

Version 4.x of the AWS Encryption SDK for Python

This sections describes new features introduced by version 4.x of the AWS Encryption SDK for Python when used with the optional Cryptographic Material Providers Library (MPL) dependency.

When you use version 4.x of the AWS Encryption SDK for Python with the MPL, you can use keyrings to perform envelope encryption. The AWS Encryption SDK provides keyrings that are compatible with the master key providers that you used in previous versions. For more information, see Keyring compatibility. For examples on migrating from master key providers to keyrings, see Migration Examples in the aws-encryption-sdk-python repository on GitHub.

The examples in this topic instantiate the AWS Encryption SDK client with the default commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT. For more information, see Setting your commitment policy.

AWS KMS keyrings in the AWS Encryption SDK for Python

The basic AWS KMS keyrings in the AWS Encryption SDK for Python take only one KMS key. They also require an AWS KMS client, which gives you an opportunity to configure the client for the AWS Region of the KMS key.

To create a AWS KMS keyring with one or more wrapping keys, use a multi-keyring. The AWS Encryption SDK for Python has a special multi-keyring that takes one or more AWS KMS keys, and a standard multi-keyring that takes one or more keyrings of any supported type. Some programmers prefer to use a multi-keyring method to create all of their keyrings, and the AWS Encryption SDK for Python supports that strategy.

The AWS Encryption SDK for Python provides basic single-key keyrings and multi-keyrings for all typical use-cases, including AWS KMS multi-Region keys.

For example, to create a AWS KMS keyring with one AWS KMS key, you can use the create_aws_kms_keyring() method.


# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
        
# Create a boto3 client for AWS KMS
kms_client = boto3.client('kms', region_name="us-west-2")
        
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
    "encryption": "context",
    "is not": "secret",
    "but adds": "useful metadata",
    "that can help you": "be confident that",
    "the data you are handling": "is what you think it is",
}

# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create the AWS KMS keyring 
keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
    kms_key_id=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab,
    kms_client=kms_client
)

kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
    input=keyring_input
)

To create a keyring with one or more AWS KMS keys, use the create_aws_kms_multi_keyring() method. This example uses two KMS keys. To specify one KMS key, use only the generator parameter. The kms_key_ids parameter that specifies additional KMS keys is optional.

The input for this keyring doesn't take an AWS KMS client. Instead, the AWS Encryption SDK uses the default AWS KMS client for each Region represented by a KMS key in the keyring. For example, if the KMS key identified by the value of the generator parameter is in the US West (Oregon) Region (us-west-2), the AWS Encryption SDK creates a default AWS KMS client for the us-west-2 Region. If you need to customize the AWS KMS client, use the create_aws_kms_keyring() method.


# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
        
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
    "encryption": "context",
    "is not": "secret",
    "but adds": "useful metadata",
    "that can help you": "be confident that",
    "the data you are handling": "is what you think it is",
}

# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create the AWS KMS keyring 
kms_multi_keyring_input: CreateAwsKmsMultiKeyringInput = CreateAwsKmsMultiKeyringInput(
    generator=default_region_kms_key_id,
    kms_key_ids=[second_region_kms_key_id]
)

kms_multi_keyring: IKeyring = mat_prov.create_aws_kms_multi_keyring(
    input=kms_multi_keyring_input
)

AWS Encryption SDK for Python supports AWS KMS keyrings that use symmetric encryption (SYMMETRIC_DEFAULT) or asymmetric RSA KMS keys. AWS KMS keyrings created with asymmetric RSA KMS keys can only contain one key pair.

To encrypt with an asymmetric RSA AWS KMS keyring, you do not need kms:GenerateDataKey or kms:Encrypt because you must specify the public key material that you want to use for encryption when you create the keyring. No AWS KMS calls are made when encrypting with this keyring. To decrypt with an asymmetric RSA AWS KMS keyring, you need kms:Decrypt permission.

To create an asymmetric RSA AWS KMS keyring, you must provide the public key and private key ARN from your asymmetric RSA KMS key. The public key must be PEM encoded. The following example creates an AWS KMS keyring with an asymmetric RSA key pair.


# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
        
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
    "encryption": "context",
    "is not": "secret",
    "but adds": "useful metadata",
    "that can help you": "be confident that",
    "the data you are handling": "is what you think it is",
}

# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create the AWS KMS keyring 
keyring_input: CreateAwsKmsRsaKeyringInput = CreateAwsKmsRsaKeyringInput(
    public_key=public_key,
    kms_key_id=kms_key_id,
    encryption_algorithm="RSAES_OAEP_SHA_256",
    kms_client=kms_client
)

kms_rsa_keyring: IKeyring = mat_prov.create_aws_kms_rsa_keyring(
    input=keyring_input
)

Required encryption contexts in version 4.x

When you use version 4.x of the AWS Encryption SDK for Python with the MPL, you can use the required encryption context CMM to require encryption contexts in your cryptographic operations. An encryption context is a set of non-secret key–value pairs. The encryption context is cryptographically bound to the encrypted data so that the same encryption context is required to decrypt the field. When you use the required encryption context CMM, you can specify one or more required encryption context keys (required keys) that must be included in all encrypt and decrypt calls.

Note

The required encryption context CMM is only supported by the following versions:

Version 3.x of the AWS Encryption SDK for Java
Version 4.x of the AWS Encryption SDK for .NET
Version 4.x of the AWS Encryption SDK for Python, when used with the optional Cryptographic Material Providers Library (MPL) dependency.

If you encrypt data using the required encryption context CMM, you can only decrypt it with one of these supported versions.

On encrypt, the AWS Encryption SDK verifies that all required encryption context keys are included in the encryption context that you specified. The AWS Encryption SDK signs the encryption contexts that you specified. Only the key-value pairs that are not required keys are serialized and stored in plaintext in the header of the encrypted message that the encrypt operation returns.

On decrypt, you must provide an encryption context that contains all of the key-value pairs that represent the required keys. The AWS Encryption SDK uses this encryption context and the key-value pairs stored in the encrypted message’s header to reconstruct the original encryption context that you specified in the encrypt operation. If the AWS Encryption SDK cannot reconstruct the original encryption context, then the decrypt operation fails. If you provide a key-value pair that contains the required key with an incorrect value, the encrypted message cannot be decrypted. You must provide the same key-value pair that was specified on encrypt.

Important

Carefully consider which values you choose for the required keys in your encryption context. You must be able to provide the same keys and their corresponding values again on decrypt. If you're unable to reproduce the required keys, the encrypted message cannot be decrypted.

The following example initializes an AWS KMS keyring with the required encryption context CMM.


# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
        
# Create your encryption context
encryption_context: Dict[str, str] = {
    "key1": "value1",
    "key2": "value2",
    "requiredKey1": "requiredValue1",
    "requiredKey2": "requiredValue2"
}

# Create a list of required encryption context keys
required_encryption_context_keys: List[str] = ["requiredKey1", "requiredKey2"]

# Instantiate the material providers library
mpl: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create the AWS KMS keyring 
 keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
    kms_key_id=kms_key_id,
    kms_client=boto3.client('kms', region_name="us-west-2")
)
kms_keyring: IKeyring = mpl.create_aws_kms_keyring(keyring_input)
      
# Create the required encryption context CMM
underlying_cmm: ICryptographicMaterialsManager = \
    mpl.create_default_cryptographic_materials_manager(
        CreateDefaultCryptographicMaterialsManagerInput(
            keyring=kms_keyring
        )
    )

required_ec_cmm: ICryptographicMaterialsManager = \
    mpl.create_required_encryption_context_cmm(
        CreateRequiredEncryptionContextCMMInput(
            required_encryption_context_keys=required_encryption_context_keys,
            underlying_cmm=underlying_cmm,
        )
    )

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Examples