Core Concepts

MinIO Key Management Service (KMS) is a robust key management server designed to securely store cryptographic keys and other sensitive data. MinIO KMS provides similar functionality to third-party KMSes, such as an HTTP API for en/decrypting operations, scalable design, high availability, high performance, and low latency.

A MinIO KMS cluster consists of at least one server or host. Each node in the cluster consists of a full replica that can service read and write operations.

In production environments, a cluster has at least three hosts with no enforced upper limit on additional cluster nodes. Adding new nodes increases overall availability of cryptographic data while increasing the available hosts for servicing encryption-related requests.

Clusters enforce strictly consistent and linearizable behavior for all state changes. Any one node in the cluster can perform read operations such as en/decryption or derivation of cryptographic keys from existing data encryption keys. Write operations, such as the creation of new data encryption keys, require complete consensus from all nodes in the cluster. The availability of MinIO KMS is summarized as follows:

• Read Quorum - 1 of n nodes
• Write Quorum - n of n nodes

Each new MinIO KMS node provides a full copy of all data keys and configurations stored on the cluster. Adding a new node to the cluster requires joining the new host using the minkms add command. Only the root or superadmin user has the necessary permissions to add or remove nodes from the cluster.

Once expanded, update any load balancers, reverse proxies, or other network control components to include the new host as part of the configuration. Clients can then transparently benefit from the increased handling of cryptographic read/write operations.

MinIO KMS uses a software-defined Hardware Security Module (HSM) key to do the following:

• Establishing internode trust and access
• Sealing/unsealing data stored on disk

All MinIO KMS nodes in the cluster must use the same HSM configuration. Removing an HSM from the cluster configuration prevents using that key for unseal and access operations after the next process restart. If the HSM has no backup, that data is rendered permanently unreadable.

MinIO KMS supports using several HSM on multiple providers for provide additional availability in the event of key loss. Specifically, MinIO KMS supports storing the HSM:

• In an environment variable (on-disk)
• On an additional dedicated MinIO KMS
• With Hashicorp Vault

MinIO KMS uses a chain of cryptographic keys as part of encryption operations. The MinIO KMS administrator has control over the following portions of that chain in decreasing scope of impact:

Exercise extreme caution before disabling or removing any of these resources.