{"id":7021,"library":"aws-cryptography-internal-primitives","title":"AWS Cryptography Internal Primitives","description":"This library contains internal primitives used by higher-level AWS Cryptography libraries, such as the AWS Encryption SDK. It is *not intended for direct public consumption* and is explicitly marked for internal use only by AWS. Direct usage is strongly discouraged due to potential breaking changes without notice. The current version is 1.11.2, and it is actively maintained with irregular releases driven by upstream AWS Cryptography library requirements.","status":"active","version":"1.11.2","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cryptography-internal-primitives-python","tags":["aws","cryptography","security","internal","footgun","private-api"],"install":[{"cmd":"pip install aws-cryptography-internal-primitives","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Underlying cryptographic operations for key material handling and primitives.","package":"cryptography","optional":false}],"imports":[{"note":"Illustrative internal component; direct use is strongly discouraged and not officially supported.","symbol":"SymmetricCryptoKey","correct":"from aws_cryptography_internal_primitives.keys import SymmetricCryptoKey"},{"note":"Illustrative internal component; direct use is strongly discouraged and not officially supported.","symbol":"MasterKeyConfig","correct":"from aws_cryptography_internal_primitives.material_providers import MasterKeyConfig"}],"quickstart":{"code":"# WARNING: This library is for internal AWS use only and NOT intended for direct consumption.\n# The following code is for illustrative purposes only and should NOT be used in production.\n# Expect breaking changes without notice if you use this directly.\nimport os\nfrom aws_cryptography_internal_primitives.keys import SymmetricCryptoKey, KeyType, KeyLength\n\n# This example demonstrates creating a SymmetricCryptoKey, an internal primitive.\n# Direct use is discouraged due to internal design and lack of stability guarantees.\nraw_aes_key = os.urandom(32) # 256-bit AES key\n\n# Create an internal symmetric key object\ninternal_aes_key = SymmetricCryptoKey(\n    material=raw_aes_key,\n    key_type=KeyType.SYMMETRIC,\n    key_length=KeyLength.AES_256\n)\n\nprint(f\"Internal Key Type: {internal_aes_key.key_type.name}\")\nprint(f\"Internal Key Length: {internal_aes_key.key_length.value} bits\")\nprint(f\"Key material is present: {internal_aes_key.material is not None}\")\n# DO NOT print or expose raw key material in real applications!\n","lang":"python","description":"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."},"warnings":[{"fix":"Use higher-level AWS Cryptography libraries like the AWS Encryption SDK or AWS KMS client instead of directly consuming this package.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid direct dependencies on this library; rely on stable, public AWS SDKs that manage these internal dependencies for you.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"AttributeError: module 'aws_cryptography_internal_primitives.keys' has no attribute 'SomeRemovedClass'"},{"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.","cause":"The constructor signature for an internal primitive like `CryptoKey` changed in a minor version update, breaking direct usage of the internal API.","error":"TypeError: CryptoKey() got an unexpected keyword argument 'new_arg'"},{"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.","cause":"An internal utility function or class was moved to a different module, renamed, or deleted as part of an internal refactoring.","error":"ImportError: cannot import name 'InternalUtilityFunction' from 'aws_cryptography_internal_primitives.some_module'"}]}