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).

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. Enclaves are how MinIO KMS supports multi-tenancy: assign each tenant, application, or object store its own enclave.

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.

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

• Rotating a key adds a new version. New encryption operations always use the latest version.
• 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 remains readable.

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

Learn more: Key Management · minkms help keys

To protect large amounts of data without sending it to the KMS, applications use envelope encryption. 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.

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; each API key has an associated identity (h1:-prefixed) that is safe to share.

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.

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. Add a node with the minkms add command; only a cluster administrator can change cluster membership.

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

Every MinIO KMS server uses a hardware security module (HSM) as its root of trust. MinIO KMS encrypts all data at rest under a single root encryption key that never leaves the server in plaintext — the HSM stores it sealed. On startup, a server asks the HSM 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.

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

All nodes in a cluster should share the same HSM configuration. 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

MinIO KMS uses a chain of keys for encryption operations. 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.