⚠️ WORK IN PROGRESS⚠️ This project is in active development and not ready for production use. The API is subject to change, and security audits have not been performed. Use at your own risk in development/testing environments only.
An Elixir implementation of the AWS Encryption SDK, providing client-side encryption compatible with all other AWS Encryption SDK implementations (Python, Java, JavaScript, C, CLI).
Version: 0.5.0 (pre-release)
- ✅ Algorithm suite definitions (all 11 ESDK suites)
- ✅ HKDF key derivation per RFC 5869
- ✅ Message format serialization/deserialization (v1 and v2 headers)
- ✅ Basic encrypt/decrypt operations
- ✅ Framed and non-framed body formats
- ✅ Key commitment verification for committed algorithm suites
- ✅ Test vector harness for cross-SDK compatibility testing
- ✅ Keyring behaviour interface
- ✅ Raw AES keyring
- ✅ Raw RSA keyring (all 5 padding schemes)
- ✅ Multi-keyring composition
- ✅ Cryptographic Materials Manager (CMM) with Default implementation
- ✅ Client module with commitment policy enforcement
- ✅ ECDSA signing for signed algorithm suites (P-384)
- ✅ Support for all 17 algorithm suites
- ✅ AWS KMS Keyring
- ✅ AWS KMS Discovery Keyring
- ✅ AWS KMS MRK Keyring
- ✅ AWS KMS MRK Discovery Keyring
- ❌ Streaming encryption/decryption
- ❌ Caching CMM
- ❌ Required Encryption Context CMM
- 469 tests passing
- 93.8% code coverage
Add aws_encryption_sdk to your list of dependencies in mix.exs:
def deps do
[
{:aws_encryption_sdk, "~> 0.5.0"}
]
endalias AwsEncryptionSdk.Client
alias AwsEncryptionSdk.Cmm.Default
alias AwsEncryptionSdk.Keyring.RawAes
# Create a raw AES keyring
key = :crypto.strong_rand_bytes(32)
{:ok, keyring} = RawAes.new(key: key, namespace: "my-app", name: "data-key-1")
# Create CMM and client
cmm = Default.new(keyring)
client = Client.new(cmm)
# Encrypt data
plaintext = "Hello, World!"
{:ok, ciphertext} = Client.encrypt(client, plaintext,
encryption_context: %{"purpose" => "example"}
)
# Decrypt data
{:ok, {decrypted, context}} = Client.decrypt(client, ciphertext)
# decrypted == "Hello, World!"The SDK provides four KMS keyring types for different use cases:
| Scenario | Recommended Keyring |
|---|---|
| Single key, known at encrypt/decrypt | AwsKms |
| Unknown key at decrypt time | AwsKmsDiscovery |
| Cross-region disaster recovery | AwsKmsMrk |
| Cross-region discovery | AwsKmsMrkDiscovery |
| Multiple keys for redundancy | Multi with KMS generator |
alias AwsEncryptionSdk.Client
alias AwsEncryptionSdk.Cmm.Default
alias AwsEncryptionSdk.Keyring.AwsKms
alias AwsEncryptionSdk.Keyring.KmsClient.ExAws
# Create KMS client
{:ok, kms_client} = ExAws.new(region: "us-west-2")
# Create keyring with your KMS key ARN
{:ok, keyring} = AwsKms.new(
"arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012",
kms_client
)
# Create CMM and client
cmm = Default.new(keyring)
client = Client.new(cmm)
# Encrypt data
{:ok, ciphertext} = Client.encrypt(client, "Hello, World!",
encryption_context: %{"purpose" => "example"}
)
# Decrypt data
{:ok, {plaintext, _context}} = Client.decrypt(client, ciphertext)The SDK uses ExAws for AWS integration. Configure credentials via:
- Environment variables:
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY - Instance profile: Automatic on EC2/ECS/Lambda
- Explicit configuration:
{:ok, client} = ExAws.new(
region: "us-west-2",
config: [
access_key_id: "AKIAIOSFODNN7EXAMPLE",
secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
]
)See examples/ for complete working examples.
- Elixir 1.16 or later
- Erlang/OTP 26 or later
See CHANGELOG.md for detailed change history.
Planned for future releases:
- Streaming - Large file encryption/decryption
- Caching CMM - Performance optimization for repeated operations
- Required Encryption Context CMM - Enforce required context keys
See CONTRIBUTING.md for guidelines.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.