Core Concepts

MinIO Key Management Service (KMS) is a key management server that securely stores cryptographic keys and performs encryption operations on behalf of clients such as the AIStor object store. It provides an HTTP API for encryption, decryption, and data key generation with high availability, high performance, and low latency.

This page introduces the concepts you need to operate MinIO KMS and links to the detailed guides and reference for each one. Every concept summarized here also has an in-terminal reference in the minkms binary, accessible with minkms help <topic> (for example, minkms help keys).

These concepts build on each other. An HSM backend anchors trust for the whole cluster; enclaves partition that cluster into isolated namespaces; master keys live inside an enclave and protect data, either directly or through short-lived data keys; and identities, governed by policies, decide who may use those keys. Cluster architecture then keeps all of this consistent and available across multiple nodes. The sections below start with the concepts you touch first as an application developer, then work down to the infrastructure underneath them.

An enclave is an isolated namespace within a KMS cluster. Each enclave holds its own keys, identities, and policies, and resources in one enclave are never accessible from another for non-root identities: enclave and policy scoping keep any identity below SysAdmin confined to the enclave it belongs to. Enclaves are how MinIO KMS supports multi-tenancy: assign each tenant, application, or object store its own enclave. Without this boundary, every identity and policy would share one flat namespace, and a single misconfigured policy could expose one tenant’s keys to another. The SysAdmin (root) identity is the intentional exception: it has access across all enclaves for cluster and enclave management (see Identities and access control).

Only a cluster administrator can create or delete enclaves. There is no limit on the number of enclaves beyond available storage.

Learn more: Enclave Management · minkms help enclave

A master key is a named key stored inside an enclave. Master keys never leave the server in plaintext and are used to encrypt data directly or to generate data keys. Because the master key itself is never exposed, who can decrypt your data comes down to who can authenticate to the KMS with the right identity and policy — the subject of Identities and access control below.

A master key is actually a key ring that holds one or more versions:

• Rotating a key adds a new version, for example on a compliance schedule. New encryption operations always use the latest version; rotation itself doesn’t invalidate or replace the protection an older version provides.
• When decrypting, MinIO KMS automatically selects the version that produced the ciphertext, so applications never track versions themselves.
• Older versions are retained so previously encrypted data stays readable, even after the key that protects it has since been rotated. To invalidate an older version, first re-encrypt any data still protected by it under the new key version. Only then delete the key: deletion removes every version, so afterward none of the key’s versions can decrypt data anymore, including any data you failed to re-encrypt first.

MinIO KMS supports AES-256-GCM (the default, and required in FIPS mode) and ChaCha20-Poly1305 keys.

Learn more: Key Management · minkms help keys

A master key can encrypt data directly, but only for small values: the ciphertext travels to and from the KMS intact, so direct encryption doesn’t scale to bulk data such as files or objects. To protect large amounts of data without sending it to the KMS, applications use envelope encryption instead. The client requests a data key (also called a data encryption key, or DEK) derived from a master key. MinIO KMS returns the data key in two forms: a plaintext key the client uses to encrypt data locally, and an encrypted (“wrapped”) copy the client stores alongside the data. To decrypt later, the client sends the wrapped data key back to MinIO KMS to unwrap it.

A client can also bind a data key to a context (arbitrary associated data, such as an object’s bucket and key name) when requesting it. MinIO KMS then rejects the unwrap request if a different context is supplied later. This only protects the data as intended if the application also binds that same context to the ciphertext or object it belongs to, and consistently supplies it again on decrypt — MinIO KMS enforces a context match, but doesn’t verify on its own that a context actually corresponds to the data it’s used with.

Because the master key never leaves the KMS, controlling access to the KMS controls access to all data protected by its keys.

Learn more: Key Management · minkms help keys

MinIO KMS uses public-key authentication over mutual TLS (mTLS), conceptually similar to SSH. A client holds a private key and presents its public key during the TLS handshake; the cluster derives the client’s identity from that public key and checks whether it may access the requested resources. API keys (k1:-prefixed) are the recommended credential format: the client library turns a k1: key into an mTLS client certificate on the fly for each connection, and the resulting identity (h1:-prefixed) is derived from the public key presented during that handshake, so an API key’s identity is safe to share.

MinIO KMS favors this over password-based authentication for three reasons: the private key never has to leave the client, the mTLS handshake means every connection is encrypted automatically, and a randomly generated key doesn’t depend on a human choosing something hard to guess.

MinIO KMS defines three privilege levels:

Users start with no permissions; you grant access by attaching a policy to the identity.

Learn more: Identity Management · Access Control · minkms help iam

A MinIO KMS cluster is a set of server nodes that hold the same replicated state. A single node forms a one-node cluster; adding nodes keeps the state consistent across all members. Nodes are numbered sequentially starting at 0.

MinIO KMS uses a single-leader replication protocol (similar to Raft, optimized for KMS workloads) that provides strict consistency and linearizability. All writes go through the leader, which replicates each change to every follower before acknowledging it. This produces an availability trade-off between the two classes of operation:

• Read operations — encryption, decryption, data key generation, status, and list — succeed as long as any one node is available.
• Write operations — creating or deleting keys, identities, policies, and enclaves — require all nodes to be available.

MinIO KMS accepts this trade-off because stale replicated state is a security problem in a KMS, not just an inconvenience: a lagging node that served reads before catching up could honor a permission that was already revoked, or a key version that was already rotated out. Requiring every node to confirm a write before it’s acknowledged rules that out.

Because almost all KMS requests are reads, a single surviving node can continue serving cryptographic operations while writes pause until the full cluster is healthy.

Learn more: Cluster Deployment · minkms help cluster

Each MinIO KMS node holds a full replica of all keys and configuration, so any node can service read requests. Scaling a MinIO KMS cluster therefore isn’t like scaling a database for more storage: since every node already holds everything, adding nodes buys read throughput and availability for cryptographic operations, not additional key storage capacity.

Add a node with the minkms add command; only a cluster administrator can change cluster membership. Only a fresh, single-node server — one not already part of a multi-node cluster — can join in this way, because a server that already belongs to another cluster already has its own replicated history to reconcile.

After expanding the cluster, update any load balancers or reverse proxies to include the new host. Clients then transparently benefit from the additional capacity for cryptographic operations.

Learn more: Scaling

The hardest security problem in a key-management system is protecting the one key that protects everything else. MinIO KMS solves it with a configured HSM backend that seals and unseals a single root encryption key: every server encrypts all data at rest under that root key, which never leaves the server in plaintext. For a hardware or remote HSM backend, the root key is additionally sealed behind a separate device or system that most attacks on the KMS server itself can’t reach; the software HSM backend, by contrast, runs in the same process and doesn’t provide that isolation. On startup, a server asks the configured HSM backend to unseal the root key; only then can it decrypt its enclave keys and communicate with its peers. Without access to a configured HSM, a server cannot start.

The HSM backend does double duty: besides sealing the root key, it also derives the private keys nodes use to authenticate each other over internode mTLS (see Architecture). All nodes in a cluster must use the same HSM key or configuration so each node’s HSM backend derives matching identities; this lets nodes trust each other without a shared certificate authority, which is why the HSM is the root of trust for cluster membership as well as for data.

MinIO KMS supports several HSM backends, and a cluster can configure more than one so it can still unseal if one becomes unavailable:

• A software HSM backed by a static key, for development, testing, and simple deployments
• A PKCS#11 token, such as a Thales Luna or network HSM
• A key managed by another MinIO KMS cluster
• A key managed by the transit engine of a HashiCorp Vault or OpenBao cluster
• A key within an Entrust KeyControl deployment
• A key within a Thales CipherTrust Manager deployment

Removing an HSM from the configuration prevents using that key for unseal and access after the next restart; if no other HSM or backup exists, the data becomes permanently unreadable.

MinIO KMS is also HTTPS-only and requires TLS for every connection.

Learn more: HSM Key Management · Certificate Management · minkms help hsm · minkms help tls

The layered design introduced above — HSM, enclave, master key — doubles as a set of deliberate control points for locking or erasing data. An administrator can lock or permanently erase data by controlling links in that chain, in decreasing order of impact:

Deleting any of these is typically irreversible. Exercise extreme caution before disabling or removing an HSM, enclave, or key.