Public facade for KMS encryption, identity, authorization, recovery, and WebAuthn APIs.
Encryption, identity, authorization, recovery, and WebAuthn calls route through KMS.Client, which delegates to the configured backend:
KMS.Client.Localfor embedded/in-process KMS. This is the default.KMS.Client.Remotefor HTTP calls to a dedicated KMS authority service.
Embedded signing-key functions use KMS.Signing directly and are intentionally absent from the remote HTTP API. Most functions return {:ok, value} or {:error, reason}.
Basic alias encryption
{:ok, _kek} = KMS.create_alias("owner:alice")
{:ok, encrypted} =
KMS.encrypt_alias("secret", "owner:alice", aad: "document:123/body")
{:ok, "secret"} =
KMS.decrypt_alias(encrypted, "owner:alice", aad: "document:123/body"):aad is additional authenticated data. It is not secret, but decrypt must use the
exact same value supplied to encrypt.
Authorization
Local calls without :session are trusted/admin calls for RMK-only aliases.
Session-protected aliases require a recipient secret even for trusted callers.
Pass a session secret when KMS should enforce principal bindings:
KMS.decrypt_alias(ciphertext, "tenant/acme/docs",
session: session.secret,
aad: "document:123/body"
)See docs/authz-bindings.md and docs/elixir-api.md for task-oriented guides.
Summary
Functions
Adds tags to a KEK alias and returns the updated tag list.
Advances a pending MFA session with factor input.
Begins WebAuthn/passkey authentication for a principal.
Begins WebAuthn/passkey registration for a principal.
Creates or returns the active KEK for alias_name.
Creates a binding granting a permission on a scope to a principal.
Registers a fallback public key for break-glass recovery envelopes.
Creates a session from a high-entropy caller passphrase.
Creates a principal with password/private-key material protected by KMS.
Creates a principal, enforcing principal.create when :session is supplied.
Creates a principal factor such as TOTP or WebAuthn.
Creates a password-authenticated session for a principal.
Creates a password-authenticated session with options.
Decrypts ciphertext with the active KEK for alias_name.
Bang variant of decrypt_alias/3.
Decrypts data produced by encrypt_rmk_pdk/3 with the same high-entropy secret.
Deletes a binding.
Deletes a fallback public key.
Deletes a principal.
Deletes a principal factor.
Deletes a session by bearer secret.
Deletes all sessions for a principal.
Encrypts cleartext with the active KEK for alias_name.
Bang variant of encrypt_alias/3.
Encrypts cleartext with a caller-supplied high-entropy secret and RMK wrapping.
Fetches an authenticated, non-expired session by bearer secret.
Fetches the active signing key with the requested version.
Fetches a binding by id.
Fetches a fallback public key by id.
Fetches a fallback public key by name.
Fetches a principal by {kind, ref}.
Fetches a principal factor by id.
Fetches a session by bearer secret.
Finishes WebAuthn/passkey authentication and returns a KMS session.
Finishes WebAuthn/passkey registration with a browser response.
Returns a binding, nil when absent, or {:error, reason} when the backend fails.
Returns a principal, nil when absent, or {:error, reason} when the backend fails.
Returns a principal factor, nil when absent, or {:error, reason} when the backend fails.
Returns a session, nil when absent, or {:error, reason} when the backend fails.
Installs one active RMK-wrapped P-256 signing key.
Idempotently installs an exact RMK-wrapped P-256 signing key.
Lists bindings for a principal id.
Lists registered fallback public keys.
Returns active KEK aliases containing tag.
Lists fallback envelopes for a KEK.
Returns tags attached to a KEK alias.
Lists factors for a principal.
Lists fallback envelopes for a principal.
Lists principals visible to the caller.
Lists sessions for a principal.
Extends an active session idle expiry without rotating the bearer secret.
Refreshes a session and rotates the bearer secret.
Removes tags from a KEK alias and returns the updated tag list.
Revokes one passphrase wrapping, including access through sessions already created from it.
Wraps a session-protected alias for a high-entropy passphrase; returns its wrapping id.
Shares an alias with a target principal.
Rotates fallback public-key envelopes using the old private key.
Signs one caller-supplied 32-byte SHA-256 digest with the active P-256 key.
Returns the default AAD for an RMK-wrapped signing-key version.
Returns the DER-encoded public key for an active signing-key version.
Unwraps a KEK through a fallback private key from trusted local code.
Unwraps principal private-key material through a fallback private key.
Updates a binding.
Updates a principal.
Updates a principal factor.
Loads and validates an active signing key, warming its private cache entry.
Verifies a DER P-256 signature over one caller-supplied 32-byte SHA-256 digest.
Functions
Adds tags to a KEK alias and returns the updated tag list.
Advances a pending MFA session with factor input.
Begins WebAuthn/passkey authentication for a principal.
Begins WebAuthn/passkey registration for a principal.
Creates or returns the active KEK for alias_name.
Options:
:tags- list of metadata tags.:session- session secret forkek.createauthorization and recipient wrapping.
New aliases with a session use protection: "session"; the KEK is sealed for
that recipient, with no RMK-only key copy. Principal creators receive encrypt,
decrypt, rewrap, and tag-management bindings. Without a session, new aliases use
the existing protection: "rmk" model. Existing aliases are never converted.
See docs/use_cases/factor_bound_aliases.md for a complete example.
Creates a binding granting a permission on a scope to a principal.
Registers a fallback public key for break-glass recovery envelopes.
Creates a session from a high-entropy caller passphrase.
Creates a principal with password/private-key material protected by KMS.
Creates a principal, enforcing principal.create when :session is supplied.
Creates a principal factor such as TOTP or WebAuthn.
Creates a password-authenticated session for a principal.
Creates a password-authenticated session with options.
Decrypts ciphertext with the active KEK for alias_name.
Accepts one ciphertext or a list of ciphertexts. The :aad option must match the
value used during encryption. Pass :session to enforce principal authorization.
Bang variant of decrypt_alias/3.
Returns plaintext on success and raises on {:error, reason}.
Decrypts data produced by encrypt_rmk_pdk/3 with the same high-entropy secret.
Deletes a binding.
Deletes a fallback public key.
Deletes a principal.
Deletes a principal factor.
Deletes a session by bearer secret.
Deletes all sessions for a principal.
Encrypts cleartext with the active KEK for alias_name.
Options:
:aad- additional authenticated data. Defaults to"".:session- session secret for principal authorization.:tags- optional KEK tags used when creating a missing alias.
Session-protected aliases also require a matching recipient envelope. Creating
a missing alias with a principal session requires kek.create permission.
Returns {:ok, ciphertext} or {:error, reason}.
Bang variant of encrypt_alias/3.
Returns ciphertext on success and raises on {:error, reason}.
Encrypts cleartext with a caller-supplied high-entropy secret and RMK wrapping.
Use this for shared-passphrase workflows where KMS should not decrypt without the
caller-supplied secret. Supports :aad.
Fetches an authenticated, non-expired session by bearer secret.
Fetches the active signing key with the requested version.
Fetches a binding by id.
Fetches a fallback public key by id.
Fetches a fallback public key by name.
Fetches a principal by {kind, ref}.
Fetches a principal factor by id.
Fetches a session by bearer secret.
Finishes WebAuthn/passkey authentication and returns a KMS session.
Finishes WebAuthn/passkey registration with a browser response.
Returns a binding, nil when absent, or {:error, reason} when the backend fails.
Returns a principal, nil when absent, or {:error, reason} when the backend fails.
Prefer fetch_principal/3 when the caller needs a uniform tagged result.
Returns a principal factor, nil when absent, or {:error, reason} when the backend fails.
Returns a session, nil when absent, or {:error, reason} when the backend fails.
Installs one active RMK-wrapped P-256 signing key.
Idempotently installs an exact RMK-wrapped P-256 signing key.
Lists bindings for a principal id.
Lists registered fallback public keys.
Returns active KEK aliases containing tag.
Lists fallback envelopes for a KEK.
Returns tags attached to a KEK alias.
Lists factors for a principal.
Lists fallback envelopes for a principal.
Lists principals visible to the caller.
Lists sessions for a principal.
Extends an active session idle expiry without rotating the bearer secret.
Refreshes a session and rotates the bearer secret.
Removes tags from a KEK alias and returns the updated tag list.
Revokes one passphrase wrapping, including access through sessions already created from it.
Wraps a session-protected alias for a high-entropy passphrase; returns its wrapping id.
Shares an alias with a target principal.
For session-protected aliases, seals a KEK copy to the target's public key and
grants a decrypt binding. The caller needs an active session, kek.rewrap, and
a usable recipient envelope. For existing RMK-only aliases, retains the legacy
binding-only behavior; it does not add cryptographic user-secret protection.
Rotates fallback public-key envelopes using the old private key.
This is a trusted local/break-glass operation. Do not route fallback private keys through ordinary HTTP clients or logs.
Signs one caller-supplied 32-byte SHA-256 digest with the active P-256 key.
Returns the default AAD for an RMK-wrapped signing-key version.
Returns the DER-encoded public key for an active signing-key version.
Unwraps a KEK through a fallback private key from trusted local code.
Unwraps principal private-key material through a fallback private key.
Updates a binding.
Updates a principal.
Updates a principal factor.
Loads and validates an active signing key, warming its private cache entry.
Verifies a DER P-256 signature over one caller-supplied 32-byte SHA-256 digest.