Server-Side Encryption Per-Deployment Key (SSE-S3)

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 an external Key Management Service (KMS) 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-S3 en/decrypts objects using an External Key (EK) managed by a Key Management System (KMS). You must specify the EK using the MINIO_KMS_KES_KEY_NAME environment variable when starting up the MinIO server. MinIO uses the same EK for all SSE-S3 cryptographic operations.

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

mc encrypt set sse-s3 play/mybucket

Replace play/mybucket with the alias and bucket on which you want to enable automatic SSE-KMS encryption.

MinIO SSE-S3 is functionally compatible with AWS S3 Server-Side Encryption with Amazon S3-Managed Keys while expanding support to include the following KMS providers:

Quickstart

Important

Enabling SSE on a MinIO deployment automatically encrypts the backend data for that deployment using the default encryption key.

MinIO requires access to KES and the external KMS to decrypt the backend and start normally. The KMS must maintain and provide access to the MINIO_KMS_KES_KEY_NAME. You cannot disable KES later or “undo” the SSE configuration at a later point.

The following procedure uses the play MinIO KES sandbox for supporting SSE with SSE-S3 in evaluation and early development environments.

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

Important

The MinIO KES Play sandbox is public and grants root access to all created External Keys (EK). Any EK stored on the Play sandbox may be accessed or destroyed at any time, rendering protected data vulnerable or permanently unreadable.

Never use the Play sandbox to protect data you cannot afford to lose or reveal.
Never generate EK using names that reveal private, confidential, or internal naming conventions for your organization.
Never use the Play sandbox for production environments.

This procedure requires the following components:

Install mc on a machine with network access to the source deployment. See the mc Installation Quickstart for instructions on downloading and installing mc.
Install MinIO Key Encryption Service (KES) on a machine with internet access. See the KES Getting Started guide for instructions on downloading, installing, and configuring KES.

1) Create an Encryption Key for SSE-S3 Encryption

Use the kes command line tool to create a new External Key (EK) for use with SSE-S3 Encryption.

The following command retrieves the root identity for the KES server connected to the KES play sandbox:

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 on the KES server. The identity must grant access to at minimum the `/v1/create`, `/v1/generate`, and `/v1/list` API endpoints. 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 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 through the KES CLI:

kes key create my-minio-sse-s3-key

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

2) Configure MinIO for SSE-S3 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_KEY_FILE`	The private key file corresponding to an identity on the KES service. The identity must grant permission to create, generate, and decrypt keys. Specify the same identity key file as the `KES_KEY_FILE` environment variable in the previous step.
`MINIO_KMS_KES_CERT_FILE`	The public certificate file corresponding to an identity on the KES service. The identity must grant permission to create, generate, and decrypt keys. Specify the same identity certificate as the `KES_CERT_FILE` environment variable in the previous step.
`MINIO_KMS_KES_KEY_NAME`	The name of the External Key (EK) to use for performing SSE encryption operations. KES retrieves the EK from the configured Key Management System (KMS). Specify the name of the key created in the previous step.

3) Restart the MinIO Deployment to Enable SSE-S3

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 of the deployment to restart.

4) Configure Automatic Bucket Encryption

Optional

You can skip this step if you intend to use only client-driven SSE-S3.

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

mc encrypt set sse-s3 ALIAS/BUCKET

Replace ALIAS with the alias of the MinIO deployment on which you enabled SSE-S3.
Replace BUCKET with the full path to the bucket or bucket prefix on which you want to enable automatic SSE-S3.

Secure Erasure and Locking

SSE-S3 protects objects using an EK specified at server startup using the MINIO_KMS_KES_KEY_NAME environment variable. MinIO therefore requires access to that EK for decrypting that object.

Disabling the EK temporarily locks SSE-S3-encrypted objects in the deployment by rendering them unreadable. You can later enable the EK to resume normal read operations.
Deleting the EK renders all SSE-S3-encrypted objects in the deployment permanently unreadable. If the KMS does not have or support backups of the EK, this process is irreversible.

The scope of the EK depends on:

Which buckets specified automatic SSE-S3 encryption, and
Which write operations requested SSE-S3 encryption.

Encryption Process

Note

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

SSE-S3 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-S3 encryption. MinIO uses the key name specified to `MINIO_KMS_KES_KEY_NAME` as the External Key (EK).
Generate the Data Encryption Key (DEK)	MinIO generates a Data Encryption Key (DEK) using the EK. Specifically, MinIO Key Encryption Service (KES) requests a new cryptographic key from the KMS using the EK as the “root” key. KES returns both the plain-text and an EK-encrypted representation of the DEK. MinIO stores the encrypted representation as part of the object metadata.
Generate the Key Encryption Key (KEK)	MinIO uses a deterministic algorithm to generate a 256-bit unique Key Encryption Key (KEK). The key-derivation algorithm uses a pseudo-random function that takes the plain-text DEK, a randomly generated initialization vector, and a context consisting of values like the bucket and object name. MinIO generates the KEK at the time of each cryptographic encryption or decryption operation and never stores the KEK to a drive.
Generate the Object Encryption Key (OEK)	MinIO generates a random 256-bit unique Object Encryption Key (OEK) and uses that key to encrypt the object. MinIO never stores the plaintext representation of the OEK on a drive. The plaintext OEK resides in RAM during cryptographic operations.
Encrypt the Object	MinIO uses the OEK to encrypt the object prior to storing the object to a drive. MinIO then encrypts the OEK with the KEK. MinIO stores the encrypted representation of the OEK and DEK as part of the metadata.