This is the multi-page printable view of this section. .
Server-Side Encryption of Objects
- 1: Server-Side Encryption with Per-Bucket Keys (SSE-KMS)
- 2: Server-Side Encryption Per-Deployment Key (SSE-S3)
- 3: Server-Side Encryption with Client-Managed Keys (SSE-C)
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 is feature and API compatible with AWS Server-Side Encryption and supports the following encryption strategies:
MinIO supports enabling automatic SSE-KMS encryption of all objects written to a bucket using a specific External Key (EK) stored on the external KMS. Clients can override the bucket-default EK by specifying an explicit key as part of the write operation.
For buckets without automatic SSE-KMS encryption, clients can specify an EK as part of the write operation instead.
MinIO encrypts backend data as part of enabling server-side encryption. You cannot disable SSE-KMS encryption once enabled.
SSE-KMS provides more granular and customizable encryption compared to SSE-S3 and SSE-C and is recommended over the other supported encryption methods.
For a tutorial on enabling SSE-KMS in a local (non-production) MinIO Deployment, see Quickstart. For production MinIO deployments, use one of the following guides:
MinIO supports enabling automatic SSE-S3 encryption of all objects written to a bucket using an EK stored on the external KMS. MinIO SSE-S3 supports one EK for the entire deployment.
For buckets without automatic SSE-S3 encryption, clients can request SSE encryption as part of the write operation instead.
MinIO encrypts backend data as part of enabling server-side encryption. You cannot disable SSE-KMS encryption once enabled.
For a tutorial on enabling SSE-s3 in a local (non-production) MinIO Deployment, see Quickstart. For production MinIO deployments, use one of the following guides:
Clients specify an EK as part of the write operation for an object. MinIO uses the specified EK to perform SSE-S3.
SSE-C does not support bucket-default encryption settings and requires clients perform all key management operations.
MinIO SSE requires enabling Network Encryption (TLS).
Secure Erasure and Locking
MinIO requires access to the Encryption Key (EK) and external Key Management System (KMS) used as part of SSE operations to decrypt an object. You can use this dependency to securely erase and lock objects from access by disabling access to the EK or KMS used for encryption.
General strategies include, but are not limited to:
-
Seal the KMS such that it cannot be accessed by MinIO server anymore. This locks all SSE-KMS or SSE-S3 encrypted objects protected by any EK stored on the KMS. The encrypted objects remain unreadable as long as the KMS remains sealed.
-
Seal/Unmount an EK. This locks all SSE-KMS or SSE-S3 encrypted objects protected by that EK. The encrypted objects remain unreadable as long as the CMK(s) remains sealed.
-
Delete an EK. This renders all SSE-KMS or SSE-S3 encrypted objects protected by that EK as permanently unreadable. The combination of deleting an EK and deleting the data may fulfill regulatory requirements around secure deletion of data.
Deleting an EK is typically irreversible. Exercise extreme caution before intentionally deleting a master key.
For more information, see:
1 - Server-Side Encryption with Per-Bucket Keys (SSE-KMS)
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) 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, supporting more granular cryptographic operations in the deployment. MinIO can only decrypt an object if it can access both the KMS and the EK used to encrypt that object.
You can enable bucket-default SSE-KMS encryption using the mc encrypt set command:
- Replace
EXTERNALKEYwith the name of the EK to use for encrypting objects in the bucket. - Replace
play/mybucketwith thealiasand 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 while expanding support to include the following KMS providers:
- AWS Secrets Manager
- Azure Key Vault
- Entrust KeyControl
- Fortanix SDKMS
- Google Cloud Secret Manager
- HashiCorp Vault Keystore
- Thales CipherTrust Manager (formerly Gemalto KeySecure)
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-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
- Azure Key Vault
- Entrust KeyControl
- Fortanix SDKMS
- Google Cloud Secret Manager
- HashiCorp Vault Keystore
- Thales CipherTrust Manager (formerly Gemalto KeySecure)
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
Playsandbox 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
Playsandbox for production environments.
This procedure requires the following components:
- Install
mcon a machine with network access to the source deployment. See themcInstallation Quickstart for instructions on downloading and installingmc. - Install MinIO Key Encryption Service (KES) on a machine with internet access. See the
kesGetting Started guide for instructions on downloading, installing, and configuring KES.
1) Create an Encryption Key for SSE-KMS Encryption
Use the kes command line tool to create a new External Key (EK) for use with SSE-KMS Encryption.
The following command retrieves the root identity for the play KES server:
Set the following environment variables in the terminal or shell:
|
The private key for an identity on the KES server.
The identity must grant access to at minimum the |
|
The corresponding certificate for the identity on the KES server.
This step uses the |
The following command creates a new EK through KES.
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:
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_FILEandMINIO_KMS_KES_CERT_FILEinstead ofMINIO_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.
The endpoint for the MinIO |
|
The API key generated by KES 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 |
|
The name of the External Key (EK) to use for performing SSE encryption operations. KES retrieves the EK 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.
Replace ALIAS with the 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.
- Replace
ALIASwith thealiasof the MinIO deployment on which you enabled SSE-KMS. - Replace
BUCKETwith 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.
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 is limited to a subset of objects.
Secure Erasure and Locking
SSE-KMS protects objects using an EK specified either as part of the bucket automatic encryption settings or as part of the write operation. MinIO therefore requires access to that EK for decrypting that object.
- Disabling the EK temporarily locks objects encrypted with that EK by rendering them unreadable. You can later enable the EK to resume normal read operations on those objects.
- Deleting the EK renders all objects encrypted by that EK permanently unreadable. If the KMS does not have or support backups of the EK, this process is irreversible.
The scope of a single EK depends on:
- Which buckets specified that EK for automatic SSE-KMS encryption, and
- Which write operations specified that EK when requesting SSE-KMS encryption.
For example, consider a MinIO deployment using one EK per bucket. Disabling a single EK renders all objects in the associated bucket unreadable without affecting other buckets. If the deployment instead used one EK for all objects and buckets, disabling that EK 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.
|
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 the drive. MinIO then encrypts the OEK with the KEK. MinIO stores the encrypted representation of the OEK and DEK as part of the metadata. |
For read operations, MinIO decrypts the object by retrieving the EK to decrypt the DEK. MinIO then regenerates the KEK, decrypts the OEK, and decrypts the object.
2 - 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:
- Replace
play/mybucketwith thealiasand 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:
- AWS Secrets Manager
- Azure KeyVault
- Entrust KeyControl
- Fortanix SDKMS
- Google Cloud Secret Manager
- HashiCorp Vault
- Thales CipherTrust Manager (formerly Gemalto KeySecure)
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):
- AWS Secrets Manager
- Azure KeyVault
- Entrust KeyControl
- Fortanix SDKMS
- Google Cloud Secret Manager
- HashiCorp Vault
- Thales CipherTrust Manager (formerly Gemalto KeySecure)
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
Playsandbox 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
Playsandbox for production environments.
This procedure requires the following components:
- Install
mcon a machine with network access to the source deployment. See themcInstallation Quickstart for instructions on downloading and installingmc. - 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:
Set the following environment variables in the terminal or shell:
|
The private key for an identity on the KES server.
The identity must grant access to at minimum the |
|
The corresponding certificate for the identity on the KES server.
This step uses the |
The following command creates a new EK through the KES CLI:
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:
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_FILEandMINIO_KMS_KES_CERT_FILEinstead ofMINIO_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.
The endpoint for the MinIO |
|
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 |
|
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 |
|
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.
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.
- Replace
ALIASwith thealiasof the MinIO deployment on which you enabled SSE-S3. - Replace
BUCKETwith 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
|
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. |
3 - Server-Side Encryption with Client-Managed Keys (SSE-C)
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.
The procedure on this page configures and enables Server-Side Encryption with Client-Managed Keys (SSE-C). MinIO SSE-C supports client-driven encryption of objects before writing the object to the drive. Clients must specify the correct key to decrypt objects for read operations.
MinIO SSE-C is functionally compatible with Amazon Server-Side Encryption with Customer-Provided Keys.
Secure Erasure and Locking
SSE-C protects objects using an EK specified by the client as part of the write operation. Assuming the client-side key management supports disabling or deleting these keys:
-
Disabling the EK temporarily locks any objects encrypted using that
EK by rendering them unreadable. You can later enable the EK to resume normal read operations on those objects.
-
Deleting the EK renders all objects encrypted by that EK
permanently unreadable. If the client-side KMS does not support backups of the EK, this process is irreversible.
The scope of a single EK depends on the number of write operations which specified that EK when requesting SSE-C encryption.
Considerations
SSE-C with Replication
Changed: Server
RELEASE.2024-03-30T09-41-56Z
Objects encrypted with SSE-C can replicate through both site replication or bucket replication. Previous versions of MinIO Object Store did not replicate SSE-C encrypted objects.
SSE-C encrypted objects that are compressed are not compatible with MinIO bucket replication or site replication. Use SSE-KMS or SSE-S3 to ensure encrypted objects are compatible with replication.
SSE-C Overrides SSE-S3 and SSE-KMS
Encrypting an object using SSE-C prevents MinIO from applying SSE-KMS or SSE-S3 encryption to that object.
Quickstart
MinIO SSE-C requires the client to perform all key creation and storage operations.
This procedure uses mc for performing operations on the source MinIO deployment. Install mc on a machine with network access to the source deployment. See the mc Installation Quickstart for instructions on downloading and installing mc.
The SSE-C key must be a 256-bit raw encoded string or a hex encoded string. The client application is responsible for generation and storage of the encryption key. MinIO does not store SSE-C encryption keys and cannot decrypt SSE-C encrypted objects without the client-managed key.
Note
Support for hex encoded keys was added in MinIO Client RELEASE.2024-06-20T14-50-54Z.
1) Generate the Encryption Key
Generate the 256-bit base64 raw encoded string or a hex encoded string for use as the encryption key.
The following example generates a string that meets the encryption key requirements. The resulting string is appropriate for non-production environments:
Defer to your organizations requirements for generating cryptographically secure encryption keys.
Copy the encryption key for use in the next step.
2) Encrypt an Object using SSE-C
MinIO supports the following AWS S3 headers for specifying SSE-C encryption:
X-Amz-Server-Side-Encryption-Customer-Algorithmset toAES256.X-Amz-Server-Side-Encryption-Customer-Keyset to the encryption key value.X-Amz-Server-Side-Encryption-Customer-Key-MD5to the 128-bit MD5 digest of the encryption key.
The MinIO mc commandline tool S3-compatible SDKs include specific syntax for setting headers. Certain mc commands like mc cp include specific arguments for enabling SSE-S3 encryption:
- Replace
ALIASwith thealiasof the MinIO deployment on which you want to write the SSE-C encrypted object. - Replace
BUCKETwith the full path to the bucket or bucket prefix to which you want to write the SSE-C encrypted object.
3) Copy an SSE-C Encrypted Object
MinIO supports the following AWS S3 headers for copying an SSE-C encrypted object to another S3-compatible service:
X-Amz-Copy-Source-Server-Side-Encryption-Algorithmset toAES256X-Amz-Copy-Source-Server-Side-Encryption-Keyset to the encryption key value. The copy operation will fail if the specified key does not match the key used to SSE-C encrypt the object.X-Amz-Copy-Source-Server-Side-Encryption-Key-MD5set to the 128-bit MD5 digest of the encryption key.
The MinIO mc commandline tool S3-compatible SDKs include specific syntax for setting headers. Certain mc commands like mc cp include specific arguments for enabling SSE-S3 encryption:
- Replace
SOURCE/BUCKETwith thealiasof the MinIO deployment from which you are reading the encrypted object and the full path to the bucket or bucket prefix from which you want to read the SSE-C encrypted object. - Replace
TARGET/BUCKETwith thealiasof the MinIO deployment from which you are writing the encrypted object and the full path to the bucket or bucket prefix to which you want to write the SSE-C encrypted object.