ExCredstash.KMS (ExCredstash v0.1.1)

View Source

AWS KMS integration for key management.

Handles data key generation and decryption using AWS KMS. Uses the official :aws Erlang SDK with :aws_credentials for credential management.

Key Management

Credstash uses KMS to:

  1. Generate data keys for encrypting secrets (64 bytes: 32 for AES-256 + 32 for HMAC)
  2. Decrypt data keys when retrieving secrets
  3. Support encryption context for additional authenticated data (AAD)

Encryption Context

KMS encryption context is a set of key-value pairs that provide additional authenticated data (AAD) for encryption operations. This can be used to bind secrets to specific contexts (e.g., environment, application).

The same context MUST be used for both encryption and decryption.

Usage

# Generate a data key
{:ok, %{plaintext: key, ciphertext_blob: encrypted_key}} =
  ExCredstash.KMS.generate_data_key(region: "us-east-1")

# Decrypt a data key
{:ok, plaintext} =
  ExCredstash.KMS.decrypt(
    region: "us-east-1",
    ciphertext_blob: encrypted_key,
    context: %{"credential" => "my_secret"}
  )

Summary

Functions

client(opts)

Create an AWS client for KMS operations.

decrypt(opts)

Decrypt a KMS-encrypted data key.

generate_data_key(opts)

Generate a new data key using AWS KMS.

Functions

client(opts)

@spec client(keyword()) :: AWS.Client.t() | {:error, term()}

Create an AWS client for KMS operations.

Uses :aws_credentials to get credentials automatically from the credential chain (env vars, instance profile, etc.).

Options

  • :region - AWS region (required)
  • :access_key_id - Override access key (optional)
  • :secret_access_key - Override secret key (optional)
  • :session_token - Override session token (optional)

Examples

# Using default credentials
client = ExCredstash.KMS.client(region: "us-east-1")

# With explicit credentials
client = ExCredstash.KMS.client(
  region: "us-east-1",
  access_key_id: "AKIAIOSFODNN7EXAMPLE",
  secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

decrypt(opts)

@spec decrypt(keyword()) :: {:ok, binary()} | {:error, term()}

Decrypt a KMS-encrypted data key.

Options

  • :region - AWS region (required)
  • :ciphertext_blob - The encrypted key blob (binary, not base64)
  • :context - Encryption context map (must match what was used for encryption)

Returns

  • {:ok, plaintext_key :: binary()} - The decrypted 64-byte key
  • {:error, reason} - Error tuple with reason

Examples

# Decrypt a stored key
{:ok, plaintext} = ExCredstash.KMS.decrypt(
  region: "us-east-1",
  ciphertext_blob: encrypted_key_blob
)

# Decrypt with encryption context (must match what was used during encryption)
{:ok, plaintext} = ExCredstash.KMS.decrypt(
  region: "us-east-1",
  ciphertext_blob: encrypted_key_blob,
  context: %{"credential" => "db_password"}
)

generate_data_key(opts)

@spec generate_data_key(keyword()) ::
  {:ok, %{plaintext: binary(), ciphertext_blob: binary()}} | {:error, term()}

Generate a new data key using AWS KMS.

Returns a 64-byte plaintext key and its encrypted form. The encrypted key is what gets stored in DynamoDB.

Options

  • :region - AWS region (required)
  • :key_id - KMS key ID (default: "alias/credstash")
  • :context - Encryption context map (optional)

Returns

  • {:ok, %{plaintext: binary(), ciphertext_blob: binary()}} - The plaintext key (64 bytes) and its encrypted form (binary blob)
  • {:error, reason} - Error tuple with reason

Examples

# Generate with default key
{:ok, %{plaintext: key, ciphertext_blob: encrypted}} =
  ExCredstash.KMS.generate_data_key(region: "us-east-1")

# Generate with encryption context
{:ok, result} = ExCredstash.KMS.generate_data_key(
  region: "us-east-1",
  context: %{"credential" => "db_password"}
)