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

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

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) <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 (External Key) 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 <mc 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 <UsingServerSideEncryption.html> while expanding support to include the following KMS providers:

• AWS SecretsManager <minio-sse-aws>
• Google Cloud SecretManager <minio-sse-gcp>
• Azure Key Vault <minio-sse-azure>
• Hashicorp KeyVault <minio-sse-vault>
• Thales CipherTrust (formerly Gemalto KeySecure)

Quickstart

The following procedure uses the play MinIO KES (Key Encryption Service) sandbox for supporting SSE (Server-Side Encryption) 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):

• AWS SecretsManager <minio-sse-aws>
• Google Cloud SecretManager <minio-sse-gcp>
• Azure Key Vault <minio-sse-azure>
• Hashicorp KeyVault <minio-sse-vault>
• Thales CipherTrust (formerly Gemalto KeySecure)

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) <kes> on a machine with internet access. See the kes Getting Started <kes/wiki/Getting-Started> guide for instructions on downloading, installing, and configuring KES.

1) Create an Encryption Key for SSE-S3 Encryption

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

Issue the following command to retrieve the root identity <kes/wiki/Configuration#policy-configuration> for the 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 <kes/wiki/Configuration#policy-configuration> on the KES server. The identity must grant access to at minimum the /v1/create, /v1/generate, and /v1/list API endpoints <kes/wiki/Server-API#api-overview>. 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 <kes/wiki/Configuration#policy-configuration> 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.

Issue the following command to create a new EK (External Key) through KES:

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_KEY_FILE=root.key
export MINIO_KMS_KES_CERT_FILE=root.cert
export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key

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 <kes/wiki/Configuration#policy-configuration> 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 <kes/wiki/Configuration#policy-configuration> 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 (External Key) 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 <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 <mc encrypt set ALIAS> with the alias <mc alias> of the MinIO deployment on which you enabled SSE-S3.
• Replace BUCKET <mc encrypt set ALIAS> 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 (External Key) specified at server startup using the MINIO_KMS_KES_KEY_NAME environment variable. MinIO therefore requires access to that EK (External Key) for decrypting that object.

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

The scope of the EK (External Key) 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)
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 a 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.