Key Management

A master key is a named cryptographic key stored inside an enclave. MinIO Key Management Service (KMS) uses master keys to encrypt data directly and to generate data keys for envelope encryption. Master keys never leave the server in plaintext.

For the concepts behind keys, versions, and data keys, see Core Concepts. The full command syntax and options are in the key management CLI reference.

All key operations act on a specific enclave. Provide the enclave with the --enclave flag (or the MINIO_KMS_ENCLAVE environment variable) and authenticate with the --api-key of an identity that has the required access to that enclave.

Create a master key

Use the minkms add-key command to create a new master key. The following example creates a key named data-bucket-encryption-key in the aistor-object-store-primary enclave:

minkms add-key data-bucket-encryption-key --enclave aistor-object-store-primary --api-key k1:<ADMIN-API-KEY>

By default, the server generates the key material at random using AES-256-GCM. Specify --type ChaCha20 to create a ChaCha20-Poly1305 key, or --import to supply your own key material.

A key name must be unique within its enclave. Creating a key with an existing name fails unless you are adding a version, as described below.

Rotate a master key

A master key is a key ring that can hold multiple versions. Rotating a key adds a new version on top of the existing ring:

minkms add-key --version data-bucket-encryption-key --enclave aistor-object-store-primary --api-key k1:<ADMIN-API-KEY>

MinIO KMS uses the latest version for new encryption operations and automatically selects the correct earlier version when decrypting existing data, so applications do not track versions themselves. Retaining older versions keeps previously encrypted data readable.

Inspect and list keys

Use minkms ls-key to list the keys in an enclave, and minkms stat-key to show details about a specific key, including its versions:

minkms ls-key --enclave aistor-object-store-primary --api-key k1:<API-KEY>

minkms stat-key data-bucket-encryption-key --enclave aistor-object-store-primary --api-key k1:<API-KEY>

Data keys and envelope encryption

To protect large amounts of data, applications use envelope encryption rather than sending the data to the KMS. Use minkms keygen to generate a data key from a master key:

minkms keygen data-bucket-encryption-key --enclave aistor-object-store-primary --api-key k1:<API-KEY>

The command returns both a plaintext data key, which the application uses to encrypt data locally, and an encrypted (“wrapped”) copy to store alongside the data. To recover the plaintext data key later, send the wrapped copy back to the server with minkms decrypt.

Clients such as the AIStor object store perform these steps automatically as part of Server-Side Encryption.

Delete a key or version

Deleting a master key or version removes the ability to decrypt any data protected by it. You can restore a deleted key or version from a backup; without a usable backup, decryption becomes permanently impossible. Use extreme caution and confirm the key is no longer in use before deleting it.

Use minkms rm-key to delete a key or a specific key version:

minkms rm-key data-bucket-encryption-key --enclave aistor-object-store-primary --api-key k1:<ADMIN-API-KEY>

See also