AWS Cryptographic Material Providers Library

Common errors

• botocore.exceptions.ClientError: An error occurred (AccessDeniedException) when calling the Decrypt operation: User: arn:aws:iam::... is not authorized to perform: kms:Decrypt on resource: arn:aws:kms:...

  cause The IAM principal (user, role, etc.) executing the code lacks the necessary KMS permissions (e.g., `kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey`) for the specified KMS key.
  fix Ensure the IAM principal has the required KMS permissions for the KMS key(s) used by the keyring. Verify both the IAM policy attached to the principal and the Key Policy of the KMS key.

• TypeError: KmsKeyring.__init__() got an unexpected keyword argument 'some_argument'

  cause This error typically occurs when using an argument that is not supported by the specific version of `KmsKeyring` installed, or if the `aws-encryption-sdk` (which imports `KmsKeyring`) is out of sync with `aws-cryptographic-material-providers`.
  fix Check the official documentation or the `KmsKeyring` source code for the correct constructor arguments for your installed version. Ensure both `aws-cryptographic-material-providers` and `aws-encryption-sdk` (if used together) are compatible versions.

• pip._vendor.packaging.requirements.InvalidRequirement: Invalid requirement, parse error at "'~=1.34.0)'"

  cause While not directly from the library, users often encounter this when manually specifying `boto3` or `cryptography` versions in `requirements.txt` with incorrect syntax, or when a packaging tool has an issue.
  fix Correct the syntax in your `requirements.txt` (e.g., `boto3 ~=1.34.0` should be `boto3~=1.34.0` without space after `~=` for some older pip versions, or ensure it's `boto3>=1.34.0,<1.35.0`). For this library, it's best to rely on its transitive dependencies and avoid manual version pinning unless necessary.

Warnings

• breaking The library now requires Python 3.11 or newer. Older Python versions (e.g., 3.8, 3.9, 3.10) are no longer supported, leading to installation or runtime errors.
  Fix: Upgrade your Python environment to 3.11 or later. Check the `requires_python` field in PyPI for the latest requirements.
• gotcha Strict dependency on specific `boto3` and `cryptography` versions. Installing incompatible versions of these libraries can lead to runtime errors or unexpected behavior due to API changes or missing features.
  Fix: Always install `aws-cryptographic-material-providers` in a clean virtual environment or ensure `pip install -U aws-cryptographic-material-providers` to let pip resolve compatible dependencies. Avoid manually pinning `boto3` or `cryptography` to versions outside the library's specified ranges (`~=1.34.0` for boto3, `~=42.0.5` for cryptography in 1.11.2).
• gotcha Relying on implicit `boto3` client creation for `KmsKeyring` can lead to issues in complex environments or when using specific region/config overrides. It's best practice to explicitly pass a configured `boto3` KMS client.
  Fix: When initializing `KmsKeyring`, provide an explicit `boto3.client('kms', region_name='...')` instance. For example: `kms_client = boto3.client('kms'); keyring = KmsKeyring(generator_key_id=KMS_KEY_ARN, client=kms_client)`.

Install

• pip install aws-cryptographic-material-providers Install latest version

Imports

• KmsKeyring
  wrong:

  from aws_cryptographic_material_providers import KmsKeyring

  correct:

  from aws_encryption_sdk.keyrings.kms import KmsKeyring

  KmsKeyring is part of the aws_encryption_sdk namespace, even though it's provided by the aws-cryptographic-material-providers package.

Quickstart

This quickstart demonstrates how to initialize `KmsKeyring` and use it with the `EncryptionSDKClient` from the `aws-encryption-sdk` to encrypt and decrypt data. A valid AWS KMS Key ARN and appropriate AWS credentials are required for successful execution. If `KMS_KEY_ARN` is not set, it will only demonstrate the keyring instantiation.

import os
from aws_encryption_sdk import EncryptionSDKClient
from aws_encryption_sdk.keyrings.kms import KmsKeyring
import boto3

# Replace with your KMS Key ARN (e.g., arn:aws:kms:REGION:ACCOUNT:key/KEY_ID)
KMS_KEY_ARN = os.environ.get("KMS_KEY_ARN", "arn:aws:kms:us-east-1:123456789012:key/EXAMPLE-KEY-ID")

if "EXAMPLE-KEY-ID" in KMS_KEY_ARN:
    print("WARNING: Please set the KMS_KEY_ARN environment variable to a valid KMS key.")
    print("Example: export KMS_KEY_ARN=arn:aws:kms:us-east-1:123456789012:key/your-key-id")

# Initialize the AWS Encryption SDK client
client = EncryptionSDKClient()

# Initialize the KMS Keyring
# For production, consider passing an explicit boto3 KMS client for better control:
# kms_client = boto3.client("kms", region_name=os.environ.get("AWS_REGION", "us-east-1"))
# keyring = KmsKeyring(generator_key_id=KMS_KEY_ARN, client=kms_client)
keyring = KmsKeyring(generator_key_id=KMS_KEY_ARN)

# Example data to encrypt
plain_text = b"my secret data"

if "EXAMPLE-KEY-ID" not in KMS_KEY_ARN:
    # Encrypt the data
    ciphertext, header = client.encrypt(source=plain_text, keyring=keyring)
    print(f"Encrypted data (first 50 bytes): {ciphertext[:50]}...")

    # Decrypt the data
    decrypted_text, _ = client.decrypt(source=ciphertext, keyring=keyring)
    print(f"Decrypted data: {decrypted_text}")

    assert decrypted_text == plain_text
    print("Encryption and decryption successful!")
else:
    print("\nKMS Keyring initialized. To perform actual encryption/decryption, set KMS_KEY_ARN and ensure AWS credentials are configured.")
    print("This quickstart demonstrates the instantiation and use of KmsKeyring within the AWS Encryption SDK context.")