AWS Encryption SDK for Elixir

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).

Current Status

Version: 0.7.0

Features

Algorithm suite definitions (all 17 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

Test Coverage

852 tests passing
92.6% code coverage

Installation

Add aws_encryption_sdk to your list of dependencies in mix.exs:

def deps do
  [
    {:aws_encryption_sdk, "~> 0.7.0"}
  ]
end

Usage

Basic Encryption with Raw Keyring

alias 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!"

AWS KMS Integration

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

Basic KMS Encryption

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)

AWS Credentials

The SDK uses ExAws for AWS integration. Configure credentials via:

Environment variables: AWS_ACCESS_KEY_ID and AWS_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.

Documentation

Getting Started Guide - Quick introduction to encryption basics
Choosing Components - Guide to selecting keyrings and CMMs
Security Best Practices - Production security guidelines
API Stability Policy - Versioning and compatibility guarantees
Examples - Working code examples for all features
API Reference - Complete API documentation

Requirements

Elixir 1.16 or later
Erlang/OTP 26 or later

Related Projects

Official AWS Encryption SDKs

Specification

Contributing

See CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.