AWS KMS Discovery Keyring implementation.

A decrypt-only keyring that can decrypt data encrypted with ANY KMS key the caller has access to. Unlike the standard AwsKms keyring, this keyring does not require knowing the key ARN in advance.

Use Cases

• Decryption services: Services that decrypt data from multiple sources
• Migration: Decrypt data while transitioning between KMS keys
• Flexible decryption: When the encrypting key is not known at decrypt time

Security Warning

Discovery keyrings will attempt to decrypt using ANY KMS key ARN found in the encrypted data keys. Use a discovery filter to restrict which keys can be used:

{:ok, keyring} = AwsKmsDiscovery.new(client,
  discovery_filter: %{
    partition: "aws",
    accounts: ["123456789012"]  # Only allow keys from this account
  }
)

Operations

Encryption

Discovery keyrings cannot encrypt. wrap_key/2 always returns {:error, :discovery_keyring_cannot_encrypt}.

For encryption, use:

• AwsKms keyring if you know the key ARN
• Multi keyring with an AwsKms generator for encryption + discovery for decryption

Decryption (unwrap_key)

1. Filters EDKs by provider ID "aws-kms"
2. Validates each EDK's key ARN format
3. Applies discovery filter (if configured)
4. Attempts KMS Decrypt using the ARN from each EDK
5. Returns on first successful decryption

Discovery Filter

Restrict which KMS keys can be used for decryption:

IAM Permissions Required

The principal needs kms:Decrypt on ALL keys that might be encountered:

{
  "Effect": "Allow",
  "Action": "kms:Decrypt",
  "Resource": [
    "arn:aws:kms:*:123456789012:key/*",
    "arn:aws:kms:*:987654321098:key/*"
  ]
}

Or use a condition to limit to specific accounts:

{
  "Effect": "Allow",
  "Action": "kms:Decrypt",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:CallerAccount": ["123456789012", "987654321098"]
    }
  }
}

Examples

Basic Discovery Decryption

alias AwsEncryptionSdk.Keyring.AwsKmsDiscovery
alias AwsEncryptionSdk.Keyring.KmsClient.ExAws
alias AwsEncryptionSdk.Cmm.Default
alias AwsEncryptionSdk.Client

# Create discovery keyring
{:ok, kms_client} = ExAws.new(region: "us-west-2")
{:ok, keyring} = AwsKmsDiscovery.new(kms_client)

# Create client
cmm = Default.new(keyring)
client = Client.new(cmm)

# Decrypt data (encrypted with any accessible KMS key)
{:ok, {plaintext, context}} = Client.decrypt(client, ciphertext)

With Discovery Filter (Recommended)

{:ok, keyring} = AwsKmsDiscovery.new(kms_client,
  discovery_filter: %{
    partition: "aws",
    accounts: ["123456789012", "987654321098"]
  }
)

Encrypt with KMS, Decrypt with Discovery

alias AwsEncryptionSdk.Keyring.{AwsKms, AwsKmsDiscovery, Multi}

# Encryption keyring - knows the key
{:ok, encrypt_keyring} = AwsKms.new("arn:aws:kms:us-west-2:123:key/abc", kms_client)

# Decryption keyring - discovery mode
{:ok, decrypt_keyring} = AwsKmsDiscovery.new(kms_client,
  discovery_filter: %{partition: "aws", accounts: ["123456789012"]}
)

# Use different clients for encrypt vs decrypt
encrypt_client = Client.new(Default.new(encrypt_keyring))
decrypt_client = Client.new(Default.new(decrypt_keyring))

Spec Reference

https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/aws-kms/aws-kms-discovery-keyring.md