AWS Cryptography Internal Primitives

Common errors

• AttributeError: module 'aws_cryptography_internal_primitives.keys' has no attribute 'SomeRemovedClass'

  cause An internal class or function was refactored, renamed, or removed without notice due to an upstream update in a higher-level AWS Cryptography library.
  fix Do not use this internal library directly. Instead, migrate to higher-level, stable AWS cryptography libraries which manage these internal dependencies and provide API stability.

• TypeError: CryptoKey() got an unexpected keyword argument 'new_arg'

  cause The constructor signature for an internal primitive like `CryptoKey` changed in a minor version update, breaking direct usage of the internal API.
  fix This library is for internal use and does not provide API stability guarantees. Update your higher-level AWS Cryptography SDKs and ensure you are not directly interacting with this internal package.

• ImportError: cannot import name 'InternalUtilityFunction' from 'aws_cryptography_internal_primitives.some_module'

  cause An internal utility function or class was moved to a different module, renamed, or deleted as part of an internal refactoring.
  fix Avoid relying on internal modules of this library. Only use official, public AWS SDKs for cryptographic needs, as they provide stable interfaces and abstract away internal changes.

Warnings

• breaking This library is not intended for direct use by customers. It is an internal dependency for higher-level AWS Cryptography libraries. Its public API is subject to breaking changes at any time without notice, even in minor versions.
  Fix: Use higher-level AWS Cryptography libraries like the AWS Encryption SDK or AWS KMS client instead of directly consuming this package.
• gotcha Directly consuming this library bypasses the security, usability, and best practices features provided by higher-level AWS Cryptography SDKs, potentially leading to insecure implementations, complex key management issues, or non-compliance.
  Fix: Refer to official AWS Encryption SDK or AWS KMS client documentation for secure and supported cryptographic operations. Do not implement cryptographic primitives directly unless you are a security expert fully aware of the implications.
• breaking The API surface of `aws-cryptography-internal-primitives` is unstable and has no versioning guarantees regarding public contracts. Upgrades to higher-level AWS Cryptography libraries might silently introduce breaking changes if you depend on this library directly.
  Fix: Avoid direct dependencies on this library; rely on stable, public AWS SDKs that manage these internal dependencies for you.

Install

• pip install aws-cryptography-internal-primitives Install stable version

Imports

• SymmetricCryptoKey

  from aws_cryptography_internal_primitives.keys import SymmetricCryptoKey

  Illustrative internal component; direct use is strongly discouraged and not officially supported.
• MasterKeyConfig

  from aws_cryptography_internal_primitives.material_providers import MasterKeyConfig

  Illustrative internal component; direct use is strongly discouraged and not officially supported.

Quickstart

This code demonstrates the creation of an internal `SymmetricCryptoKey` object for illustrative purposes only. *This library is strictly for internal AWS use* and not intended for direct customer consumption. Direct use of these primitives is strongly discouraged as the API is unstable, subject to breaking changes without notice, and does not offer the security and usability guarantees of higher-level AWS Cryptography SDKs (e.g., AWS Encryption SDK or AWS KMS Client). Do NOT use this code in production.

# WARNING: This library is for internal AWS use only and NOT intended for direct consumption.
# The following code is for illustrative purposes only and should NOT be used in production.
# Expect breaking changes without notice if you use this directly.
import os
from aws_cryptography_internal_primitives.keys import SymmetricCryptoKey, KeyType, KeyLength

# This example demonstrates creating a SymmetricCryptoKey, an internal primitive.
# Direct use is discouraged due to internal design and lack of stability guarantees.
raw_aes_key = os.urandom(32) # 256-bit AES key

# Create an internal symmetric key object
internal_aes_key = SymmetricCryptoKey(
    material=raw_aes_key,
    key_type=KeyType.SYMMETRIC,
    key_length=KeyLength.AES_256
)

print(f"Internal Key Type: {internal_aes_key.key_type.name}")
print(f"Internal Key Length: {internal_aes_key.key_length.value} bits")
print(f"Key material is present: {internal_aes_key.material is not None}")
# DO NOT print or expose raw key material in real applications!