docs/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst

Server-Side Encryption with Per-Bucket Keys (SSE-KMS)

minio

Table of Contents

MinIO Server-Side Encryption (SSE) protects objects as part of write operations, allowing clients to take advantage of server processing power to secure objects at the storage layer (encryption-at-rest). SSE also provides key functionality to regulatory and compliance requirements around secure locking and erasure.

MinIO SSE uses the MinIO Key Encryption Service (KES) <> and a supported external Key Management Service (KMS) <#supported-kms-targets> for performing secured cryptographic operations at scale. MinIO also supports client-managed key management, where the application takes full responsibility for creating and managing encryption keys for use with MinIO SSE.

MinIO SSE-KMS encrypts or decrypts objects using an External Key (EK) managed by a Key Management System (KMS). Each bucket and object can have a separate EK (External Key), supporting more granular cryptographic operations in the deployment. MinIO can only decrypt an object if it can access both the KMS and the EK (External Key) used to encrypt that object.

You can enable bucket-default SSE-KMS encryption using the mc encrypt set command:

mc encrypt set sse-kms EXTERNALKEY play/mybucket

• Replace EXTERNALKEY with the name of the EK (External Key) to use for encrypting objects in the bucket.
• Replace play/mybucket with the alias <mc alias> and bucket on which you want to enable automatic SSE-KMS encryption.

MinIO SSE-KMS is functionally compatible with AWS S3 Server-Side Encryption with KMS keys stored in AWS <UsingKMSEncryption.html> while expanding support to include the following KMS providers:

• AWS Secrets Manager <integrations/aws-secrets-manager/>
• Azure Key Vault <integrations/azure-keyvault/>
• Entrust KeyControl <integrations/entrust-keycontrol/>
• Fortanix SDKMS <integrations/fortanix-sdkms/>
• Google Cloud Secret Manager <integrations/google-cloud-secret-manager/>
• HashiCorp Vault Keystore <integrations/hashicorp-vault-keystore/>
• Thales CipherTrust Manager (formerly Gemalto KeySecure) <integrations/thales-ciphertrust/>

Quickstart

Important

The following procedure uses the play MinIO KES (Key Encryption Service) sandbox for supporting SSE (Server-Side Encryption) with SSE-KMS in evaluation and early development environments.

For extended development or production environments, use one of the following supported external Key Management Services (KMS):

• AWS Secrets Manager <integrations/aws-secrets-manager/>
• Azure Key Vault <integrations/azure-keyvault/>
• Entrust KeyControl <integrations/entrust-keycontrol/>
• Fortanix SDKMS <integrations/fortanix-sdkms/>
• Google Cloud Secret Manager <integrations/google-cloud-secret-manager/>
• HashiCorp Vault Keystore <integrations/hashicorp-vault-keystore/>
• Thales CipherTrust Manager (formerly Gemalto KeySecure) <integrations/thales-ciphertrust/>

This procedure requires the following components:

• Install mc on a machine with network access to the source deployment. See the mc Installation Quickstart <mc-install> for instructions on downloading and installing mc.
• Install MinIO Key Encryption Service (KES) <> on a machine with internet access. See the kes Getting Started <tutorials/getting-started/> guide for instructions on downloading, installing, and configuring KES.

1) Create an Encryption Key for SSE-KMS Encryption

Use the kes <cli/> command line tool to create a new External Key (EK) for use with SSE-KMS Encryption.

The following command retrieves the root identity <concepts/#authorization> for the play KES server:

curl -sSL --tlsv1.2 \
  -O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
  -O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'

Set the following environment variables in the terminal or shell:

export KES_CLIENT_KEY=root.key
export KES_CLIENT_CERT=root.cert

KES_CLIENT_KEY	The private key for an identity <concepts/#authorization> on the KES server. The identity must grant access to at minimum the /v1/create, /v1/generate, and /v1/list API endpoints <concepts/server-api/>. This step uses the root identity for the MinIO play KES sandbox, which provides access to all operations on the KES server.
KES_CLIENT_CERT	The corresponding certificate for the identity <concepts/#authorization> on the KES server. This step uses the root identity for the MinIO play KES sandbox, which provides access to all operations on the KES server.

The following command creates a new EK (External Key) through KES.

kes key create my-minio-sse-kms-key

This tutorial uses the example my-minio-sse-kms-key name for ease of reference. Specify a unique key name to prevent collision with existing keys.

2) Configure MinIO for SSE-KMS Object Encryption

Specify the following environment variables in the shell or terminal on each MinIO server host in the deployment:

export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373
export MINIO_KMS_KES_API_KEY=<API-key-identity-string-from-KES> # Replace with the key string for your credentials
export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key

Note

• An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server.

• Alternatively, specify the MINIO_KMS_KES_KEY_FILE and MINIO_KMS_KES_CERT_FILE instead of MINIO_KMS_KES_API_KEY.

  API keys are mutually exclusive with certificate-based authentication. Specify either the API key variable or the Key File and Cert File variables.

• The documentation on this site uses API keys.

MINIO_KMS_KES_ENDPOINT	The endpoint for the MinIO Play KES service.
MINIO_KMS_KES_API_KEY	The API key generated by KES <tutorials/kes-for-minio/#kes-server-setup> for the MinIO deployment. The identity of the API key must grant permission to create, generate, and decrypt keys. The API key is the preferred way to authenticate with the KES server. If circumstances require it, specify the MINIO_KMS_KES_KEY_FILE and MINIO_KMS_KES_CERT_FILE instead. Specify either the API key or the Key File and Cert File. Do not populate all three environment variables.
MINIO_KMS_KES_KEY_NAME	The name of the External Key (EK) to use for performing SSE encryption operations. KES retrieves the EK (External Key) from the configured Key Management Service (KMS). Specify the name of the key created in the previous step.

3) Restart the MinIO Deployment to Enable SSE-KMS

You must restart the MinIO deployment to apply the configuration changes. Use the mc admin service restart command to restart the deployment.

mc admin service restart ALIAS

Replace ALIAS with the alias <alias> of the deployment to restart.

4) Configure Automatic Bucket Encryption

Use the mc encrypt set command to enable automatic SSE-KMS protection of all objects written to a specific bucket.

mc encrypt set sse-kms my-minio-sse-kms-key ALIAS/BUCKET

• Replace ALIAS <mc encrypt set ALIAS> with the alias <mc alias> of the MinIO deployment on which you enabled SSE-KMS.
• Replace BUCKET <mc encrypt set ALIAS> with the full path to the bucket or bucket prefix on which you want to enable automatic SSE-KMS.

Objects written to the specified bucket are automatically encrypted using the specified EK (External Key).

Repeat this step for each bucket on which you want to enable automatic SSE-KMS encryption. You can generate additional keys per bucket or bucket prefix, such that the scope of each EK (External Key) is limited to a subset of objects.

Secure Erasure and Locking

SSE-KMS protects objects using an EK (External Key) specified either as part of the bucket automatic encryption settings or as part of the write operation. MinIO therefore requires access to that EK (External Key) for decrypting that object.

• Disabling the EK (External Key) temporarily locks objects encrypted with that EK (External Key) by rendering them unreadable. You can later enable the EK (External Key) to resume normal read operations on those objects.
• Deleting the EK (External Key) renders all objects encrypted by that EK (External Key) permanently unreadable. If the KMS does not have or support backups of the EK (External Key), this process is irreversible.

The scope of a single EK (External Key) depends on:

• Which buckets specified that EK (External Key) for automatic SSE-KMS encryption, and
• Which write operations specified that EK (External Key) when requesting SSE-KMS encryption.

For example, consider a MinIO deployment using one EK (External Key) per bucket. Disabling a single EK (External Key) renders all objects in the associated bucket unreadable without affecting other buckets. If the deployment instead used one EK (External Key) for all objects and buckets, disabling that EK (External Key) renders all objects in the deployment unreadable.

Encryption Process

Note

This section describes MinIO internal logic and functionality. This information is purely educational and is not a prerequisite for configuring or implementing any MinIO feature.

SSE-KMS uses an External Key (EK) managed by the configured Key Management System (KMS) for performing cryptographic operations and protecting objects. The table below describes each stage of the encryption process:

Stage	Description
SSE-Enabled Write Operation	MinIO receives a write operation requesting SSE-KMS encryption. The write operation must have an associated External Key (EK) to use for encrypting the object. For write operations in buckets with automatic SSE-KMS enabled, MinIO uses the bucket EK (External Key). If the write operation includes an explicit EK, MinIO uses that instead of the bucket EK. For write operations in buckets without automatic SSE-KMS enabled, MinIO uses the EK (External Key) specified to the write operation.
Generate the Data Encryption Key (DEK)
Generate the Key Encryption Key (KEK)
Generate the Object Encryption Key (OEK)
Encrypt the Object	MinIO uses the OEK (Object Encryption Key) to encrypt the object prior to storing the object to the drive. MinIO then encrypts the OEK (Object Encryption Key) with the KEK (Key Encryption Key). MinIO stores the encrypted representation of the OEK (Object Encryption Key) and DEK (Data Encryption Key) as part of the metadata.

For read operations, MinIO decrypts the object by retrieving the EK (External Key) to decrypt the DEK (Data Encryption Key). MinIO then regenerates the KEK (Key Encryption Key), decrypts the OEK (Object Encryption Key), and decrypts the object.