KMS.RMK behaviour (kms v0.1.0)

Root master key facade.

RMK providers protect KMS secret material before persistence, including KEK master keys, principal/session private-key payloads, factor secrets, and RMK PDK payloads.

Configure one provider:

config :kms, :rmk_provider, KMS.RMK.Local

Most application code should use higher-level APIs such as KMS.encrypt_alias/3. Direct RMK calls are useful for provider checks and application-owned secret wrapping.

Summary

Callbacks

decrypt(binary, keyword)

encrypt(binary, keyword)

ensure_ready(keyword)

Functions

decrypt(ciphertext, opts \\ [])

Decrypts ciphertext using the configured RMK provider.

encrypt(cleartext, opts \\ [])

Encrypts cleartext using the configured RMK provider.

ensure_ready(opts \\ [])

Checks whether the configured RMK provider is ready.

Callbacks

decrypt(binary, keyword)

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

encrypt(binary, keyword)

@callback encrypt(
  binary(),
  keyword()
) :: {:ok, binary()} | {:error, term()}

ensure_ready(keyword)

(optional)

@callback ensure_ready(keyword()) :: :ok | {:error, term()}

Functions

decrypt(ciphertext, opts \\ [])

Decrypts ciphertext using the configured RMK provider.

Provider/AAD context must match the values used for encryption. Provider mismatch fails closed for envelope ciphertexts.

encrypt(cleartext, opts \\ [])

Encrypts cleartext using the configured RMK provider.

Options are passed through to the provider. Providers that support additional authenticated data accept :aad.

ensure_ready(opts \\ [])

Checks whether the configured RMK provider is ready.

Providers use this to validate local key files or remote key access. Providers without an explicit readiness callback are treated as ready.

The check is bounded by config :kms, :rmk_readiness_timeout_ms (five seconds by default). Pass :readiness_timeout_ms to override that bound for one call. The bound is also passed to the provider as :timeout_ms unless already specified. Provider exceptions and timeouts return redacted error atoms.