diff --git a/source/conf.py b/source/conf.py
index 5f00effc..288c1852 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -68,6 +68,7 @@ extlinks = {
'docs-k8s' : ('https://docs.min.io/minio/k8s/%s',''),
'prometheus-docs' : ('https://prometheus.io/docs/%s',''),
'podman-docs' : ('https://docs.podman.io/en/latest/%s',''),
+ 'podman-git' : ('https://github.com/containers/podman/%s','')
}
@@ -129,4 +130,11 @@ html_title = 'MinIO Baremetal Documentation'
# -- Options for Sphinx Tabs -------------------------------------------------
-sphinx_tabs_disable_css_loading = True
\ No newline at end of file
+sphinx_tabs_disable_css_loading = True
+
+rst_prolog = """
+
+.. |podman| replace:: `Podman `__
+.. |kes-stable| replace:: 0.16.1
+
+"""
\ No newline at end of file
diff --git a/source/includes/common-minio-kes.rst b/source/includes/common-minio-kes.rst
new file mode 100644
index 00000000..9f12c137
--- /dev/null
+++ b/source/includes/common-minio-kes.rst
@@ -0,0 +1,464 @@
+
+.. The following sections are common installation instructions for the KES
+ server. These are used in the following pages:
+
+ - /source/security/server-side-encryption/configure-minio-kes-hashicorp.rst
+ - /source/security/server-side-encryption/configure-minio-kes-aws.rst
+ - /source/security/server-side-encryption/configure-minio-kes-azure.rst
+ - /source/security/server-side-encryption/configure-minio-kes-gcp.rst
+
+.. start-kes-network-encryption-desc
+
+MinIO |KES-git| relies on mutual TLS (mTLS) for authentication and
+authorization. Enabling |SSE| therefore *requires* that the MinIO server, |KES|,
+and the root |KMS| enforce TLS.
+
+The instructions on this page include creation of TLS certificates for
+supporting mTLS between MinIO and the KES instance. These certificates are
+appropriate for early development and evaluation environments **only**.
+
+For instructions on enabling TLS on the MinIO server, see :ref:`minio-tls`.
+
+.. admonition:: Use Caution in Production Environments
+ :class: important
+
+ **DO NOT** use the TLS certificates generated as part of this procedure for
+ any long-term development or production environments.
+
+ Defer to organization/industry best practices around TLS certificate
+ generation and management. A complete guide to creating valid certificates
+ (e.g. well-formed, current, and trusted) is beyond the scope of this
+ procedure.
+
+.. end-kes-network-encryption-desc
+
+.. start-kes-podman-desc
+
+The procedures on this page use the |podman| daemonless container engine for
+running OCI containers. Podman is a drop-in replacement for Docker.
+
+This procedure assues running Podman in
+:podman-git:`"rootless" `.
+Defer to the Podman documentation for installing and configuring Podman to
+run in rootless mode.
+
+
+.. end-kes-podman-desc
+
+.. start-kes-download-desc
+
+You can download the KES binary for running in baremetal environments,
+*or* use the KES container image for running in an orchestrated environment:
+
+.. tab-set::
+
+ .. tab-item:: CLI
+ :sync: cli
+
+ Download the latest stable release (|kes-stable|) of KES from
+ :minio-git:`github.com/minio/kes `.
+
+ Select the binary appropriate for the host OS architecture. For example,
+ hosts running X86-64 (Intel/AMD64) should download the ``kes-linux-amd64``
+ package.
+
+ The following example code downloads the latest Linux AMD64-compatible
+ binary and moves it to the system ``PATH``:
+
+ .. code-block:: shell
+ :class: copyable
+ :substitutions:
+
+ wget https://github.com/minio/kes/releases/download/v|kes-stable|/kes-linux-amd64 -O /tmp/kes && \
+ chmod +x /tmp/kes && \
+ sudo mv /tmp/kes /usr/local/bin
+
+ kes --version
+
+
+ .. tab-item:: Container
+ :sync: container
+
+ The following command uses |podman| to download the latest stable KES
+ (|kes-stable|) as a container image:
+
+ .. code-block:: shell
+ :class: copyable
+ :substitutions:
+
+ podman pull quay.io/minio/kes/v|kes-stable|
+
+ You can validate the container downloaded correctly by running the
+ following command:
+
+ .. code-block:: shell
+ :class: copyable
+
+ podman run kes --version
+
+ The output should reflect |kes-stable|.
+
+.. end-kes-download-desc
+
+.. start-kes-generate-kes-certs-desc
+
+This step creates a self-signed TLS certificate for use with KES in evaluation
+or early development environments. The certificate expires within 30 days of
+creation.
+
+For production environments, use certificates signed by a trusted Certificate
+Authority (CA). **DO NOT** use certificates generated using these instructions
+in production environments.
+
+.. tab-set::
+
+ .. tab-item:: CLI
+ :sync: cli
+
+ The following command creates the self-signed private and public key files
+ using the ``kes tool identity new`` command:
+
+ .. code-block:: shell
+ :class: copyable
+
+ kes tool identity new --server \
+ --key ~/kes/certs/server.key \
+ --cert ~/kes/certs/server.cert \
+ --ip "127.0.0.1" \
+ --dns localhost
+
+ .. tab-item:: Container
+ :sync: container
+
+ The following command creates the self-signed private and public key files
+ using the ``kes tool identity new`` command. ``podman run --rm``
+ automatically removes the container when the command exists
+
+ .. code-block:: shell
+ :class: copyable
+
+ podman run --rm -v ~/kes/certs:/data/certs \
+ kes tool identity new --server \
+ --key /data/certs/server.key \
+ --cert /data/certs/server.cert \
+ --ip "127.0.0.1" \
+ --dns localhost
+
+ This command outputs the keys to the ``~/kes/certs`` directory on the host
+ operating system.
+
+.. end-kes-generate-kes-certs-desc
+
+.. start-kes-generate-minio-certs-desc
+
+KES uses mTLS for authorizing a connecting client to perform a requested
+cryptographic operation. This step creates a new TLS identity for the MinIO
+deployment to use in performing secure cryptographic operations on KES. The
+certificate expires within 30 days of creation.
+
+For production environments, use certificates signed by a trusted Certificate
+Authority (CA). **DO NOT** use certificates generated using these instructions
+in production environments.
+
+.. tab-set::
+
+ .. tab-item:: CLI
+ :sync: cli
+
+ The following command creates the self-signed private and public key files
+ using the ``kes tool identity new`` command:
+
+ .. code-block:: shell
+ :class: copyable
+
+ kes tool identity new --server \
+ --key ~/kes/certs/minio-kes.key \
+ --cert ~/kes/certs/minio-kes.cert \
+ --ip "127.0.0.1" \
+ --dns localhost
+
+ The command outputs the keys to the ``~/kes/certs`` directory.
+
+ Use the ``kes tool identity of`` command to compute the identity hash for
+ the certificate. This hash is required for configuring access to the KES
+ server in a later step:
+
+ .. code-block:: shell
+ :class: copyable
+
+ kes tool identify of ~/kes/certs/minio-kes.cert
+
+ .. tab-item:: Container
+ :sync: container
+
+ The following command creates the self-signed private and public key files
+ using the ``kes tool identity new`` command. ``podman run --rm``
+ automatically removes the container when the command exists
+
+ .. code-block:: shell
+ :class: copyable
+
+ podman run --rm -v ~/kes/certs:/data/certs \
+ kes tool identity new --key /data/certs/minio-kes.key \
+ --cert /data/certs/minio-kes.cert
+
+ This command outputs the keys to the ``~/kes/certs`` directory on the host
+ operating system.
+
+ Use the ``kes tool identity of`` command to compute the identity hash for
+ the certificate. This hash is required for configuring access to the KES
+ server in a later step:
+
+ .. code-block:: shell
+ :class: copyable
+
+ sudo podman run --rm --v ~/kes/certs:/data/certs \
+ kes tool identity of /data/certs/minio-kes.cert
+
+.. end-kes-generate-minio-certs-desc
+
+.. start-kes-run-server-desc
+
+.. tab-set::
+
+ .. tab-item:: CLI
+ :sync: cli
+
+ The first command allows |KES| to use the `mlock
+ `__ system call without
+ running as root. ``mlock`` ensures the OS does not write in-memory data to
+ disk (swap memory) and mitigates the risk of cryptographic operations
+ being written to unsecured disk at any time.
+
+ The second command starts the KES server in the foreground using the
+ configuration file created in the last step. The ``--auth=off`` disables
+ strict validation of client TLS certificates and is required if either the
+ MinIO client or the root KMS server uses self-signed certificates.
+
+ .. code-block:: shell
+ :class: copyable
+
+ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
+
+ kes server --mlock \
+ --config=~/kes/config/server-config.yaml \
+ --auth=off
+
+ |KES| listens on port ``7373`` by default. You can monitor the server
+ logs from the terminal session. If you run |KES| without tying it to
+ the current shell session (e.g. with ``nohup``), use that methods
+ associated logging system (e.g. ``nohup.txt``).
+
+ .. tab-item:: Container
+ :sync: container
+
+ The following command starts the KES server using the configuration file
+ created in the last step. The command includes the necessary extensions
+ that allow |KES| to use the `mlock
+ `__ system call without
+ running as root. ``mlock`` ensures the OS does not write in-memory data to
+ disk (swap memory) and mitigates the risk of cryptographic operations
+ being written to unsecured disk at any time.
+
+ .. code-block:: shell
+ :class: copyable
+
+ podman run --rm -idt --cap-add=IPC_LOCK \
+ --name kes-server \
+ -v ~/kes/certs:/data/certs \
+ -v ~/kes/config:/data/config \
+ -p 7373:7373 \
+ kes server --mlock \
+ --config=/data/config/server-config.yaml \
+ --auth=off
+
+ The container starts using the specified configuration file and begins
+ listening for client connections at por ``7373``. The server attempts to
+ connect to the root KMS deployment specified in the server configuration
+ file.
+
+.. end-kes-run-server-desc
+
+.. start-kes-generate-key-desc
+
+.. tab-set::
+
+ .. tab-item:: CLI
+ :sync: cli
+
+ MinIO requires that the |EK| exist on the root KMS *before* performing
+ |SSE| operations using that key. Use ``kes key create`` *or*
+ :mc:`mc admin kms key create` to create a new |EK| for use with |SSE|.
+
+ The following command uses the ``kes key create`` command to create a new
+ External Key (EK) stored on the root KMS server for use with encrypting
+ the MinIO backend.
+
+ .. code-block:: shell
+ :class: copyable
+
+ export KES_SERVER=https://127.0.0.1:7373
+ export KES_CLIENT_KEY=~/kes/minio-kes.key
+ export KES_CLIENT_CERT=~/kes/minio-kes.cert
+
+ kes key create -k minio-backend-default-key
+
+ .. tab-item:: Container
+ :sync: container
+
+ MinIO requires that the |EK| exist on the root KMS *before* performing
+ |SSE| operations using that key. Use ``kes key create`` *or*
+ :mc:`mc admin kms key create` to create a new |EK| for use with |SSE|.
+
+ The following command uses the ``kes key create`` command to create a new
+ External Key (EK) stored on the root KMS server for use with encrypting
+ the MinIO backend.
+
+ .. code-block:: shell
+ :class: copyable
+
+ sudo podman exec -it kes-server /bin/bash
+
+ [root@ID /]# /kes key create -k \
+ -e KES_SERVER=https://127.0.0.1:7373 \
+ -e KES_CLIENT_KEY=/data/minio-kes.key \
+ -e KES_CLIENT_CERT=/data/minio-kes.cert \
+ minio-backend-default-key
+
+.. end-kes-generate-key-desc
+
+.. start-kes-configure-minio-desc
+
+Set the following environment variables to configure MinIO to connect to the
+KES server. Set these variables on *all* hosts running MinIO servers in the
+deployment. This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and
+``server.cert`` certificates are accessible at the specified location:
+
+.. code-block:: shell
+ :class: copyable
+
+ export MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
+ export MINIO_KMS_KES_CLIENT_CERT=~/minio-kes.cert
+ export MINIO_KMS_KES_CLIENT_KEY=~/minio-kes.key
+ export MINIO_KMS_KES_CAPATH=~/server.cert
+ export MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
+
+ minio server [ARGUMENTS]
+
+- Replace ``HOSTNAME`` with the IP address or the hostname for the host machine
+ running the KES server or pod started in the previous step.
+
+- Replace the ``minio server [ARGUMENTS]`` to match the command used to
+ start the MinIO server on that host.
+
+- Add all other environment variables as required by the deployment.
+
+MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following
+cryptographic operations:
+
+- Encrypting the MinIO backend (IAM, configuration, etc.)
+- Performing :ref:`SSE-KMS ` if the request does not
+ include a specific |EK|.
+- Performing :ref:`SSE-S3 `.
+
+.. end-kes-configure-minio-desc
+
+.. -----------------------------------------------------------------------------
+
+.. The following sections are common descriptors associated to the KES
+ configuration. These are used in the following pages:
+
+ - /source/security/server-side-encryption/configure-minio-kes-hashicorp.rst
+ - /source/security/server-side-encryption/configure-minio-kes-aws.rst
+ - /source/security/server-side-encryption/configure-minio-kes-azure.rst
+ - /source/security/server-side-encryption/configure-minio-kes-gcp.rst
+
+.. start-kes-conf-address-desc
+
+The network address and port on which the KES server listens to on startup.
+Defaults to port ``7373`` on all host network interfaces.
+
+.. end-kes-conf-address-desc
+
+
+.. start-kes-conf-root-desc
+
+The identity for the KES superuser (root) identity. Clients connecting
+with a TLS certificate whose hash (``kes tool identity of client.cert``)
+matches this value have access to all KES API operations.
+
+You can specify ``'disabled'`` to disable this identity and limit access
+based on the ``policy`` configuration.
+
+.. end-kes-conf-root-desc
+
+
+.. start-kes-conf-tls-desc
+
+The TLS private key and certificate used by KES for establishing
+TLS-secured communications. Specify the full path to both the private ``.key``
+and public ``.cert`` to the ``key`` and ``cert`` fields respectively.
+
+.. end-kes-conf-tls-desc
+
+.. start-kes-conf-policy-desc
+
+Specify one or more
+:minio-git:`policies ` to
+control access to the KES server.
+
+MinIO |SSE| requires access to only the following KES cryptographic APIs:
+
+- ``/v1/key/create/*``
+- ``/v1/key/generate/*``
+- ``/v1/key/decrypt/*``
+
+You can restrict the range of key names MinIO can create as part of performing
+|SSE| by specifying a prefix to replace the ``*``. For example,
+``minio-sse-*`` only grants access to create, generate, or decrypt keys using
+that prefix.
+
+|KES| uses mTLS to authorize connecting clients by comparing the
+hash of the TLS certificate against the ``identities`` of each configured
+policy. Use the ``kes tool identity of`` command to compute the identity of the
+MinIO mTLS certificate and add it to the ``policy..identities`` array
+to associate MinIO to the ```` policy.
+
+.. end-kes-conf-policy-desc
+
+.. start-kes-conf-keys-desc
+
+Specify an array of keys which *must* exist on the root KMS for |KES| to
+successfully start. KES attempts to create the keys if they do not exist and
+exits with an error if it fails to create any key. KES does not accept any
+client requests until it completes validation of all specified keys.
+
+.. end-kes-conf-keys-desc
+
+.. -----------------------------------------------------------------------------
+
+.. The following sections include common admonitions/notes across all KES
+ properties. These are used in the following pages:
+
+ - /source/security/server-side-encryption/server-side-encryption-sse-kms.rst
+ - /source/security/server-side-encryption/server-side-encryption-sse-s3.rst
+ - /source/security/server-side-encryption/server-side-encryption-sse-c.rst
+
+.. start-kes-play-sandbox-warning
+
+.. 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.
+
+.. end-kes-play-sandbox-warning
\ No newline at end of file
diff --git a/source/includes/common-minio-sse.rst b/source/includes/common-minio-sse.rst
new file mode 100644
index 00000000..194812e2
--- /dev/null
+++ b/source/includes/common-minio-sse.rst
@@ -0,0 +1,32 @@
+.. start-sse-dek
+
+MinIO generates a Data Encryption Key (DEK) using the |EK|. Specifically,
+:minio-git:`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.
+
+.. end-sse-dek
+
+.. start-sse-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
+(:ref:`PRF `) 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 disk.
+
+.. end-sse-kek
+
+.. start-sse-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 disk. The plaintext OEK resides in RAM during cryptographic
+operations.
+
+.. end-sse-oek
\ No newline at end of file
diff --git a/source/reference/minio-cli/minio-mc/mc-encrypt.rst b/source/reference/minio-cli/minio-mc/mc-encrypt.rst
index bb0cba4b..7b0abba9 100644
--- a/source/reference/minio-cli/minio-mc/mc-encrypt.rst
+++ b/source/reference/minio-cli/minio-mc/mc-encrypt.rst
@@ -15,15 +15,15 @@ Description
.. start-mc-encrypt-desc
-The :mc:`mc encrypt` mc sets, updates, or disables the default
-bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts
-objects using the specified SSE mode.
+The :mc:`mc encrypt` mc sets, updates, or disables the default bucket
+Server-Side Encryption (SSE) mode. MinIO automatically encrypts objects using
+the specified SSE mode.
+
+.. end-mc-encrypt-desc
For more information on configuring SSE, see
:ref:`minio-sse`
-.. end-mc-encrypt-desc
-
Behavior
~~~~~~~~
@@ -60,8 +60,15 @@ Syntax
Specify the server-side encryption type to use as the default SSE mode.
Supports the following values:
- - ``sse-kms`` - SSE using a Key Management System (KMS).
- - ``sse-s3`` - SSE using client-provided keys (SSE-C).
+ - ``sse-kms`` - Encrypt objects using the key specified in
+ :mc-cmd:`~mc encrypt set KMSKEY`. MinIO
+ must have access to the specified key on the external KMS to
+ successfully encrypt or decrypt objects protected using SSE-KMS.
+
+ - ``sse-s3`` - Encrypt objects using the key specified to
+ :envvar:`MINIO_KMS_KES_KEY_NAME`. MinIO must have access to the
+ specified key on the external KMS to successfully encrypt or decrypt
+ objects protected using SSE-S3.
.. mc-cmd:: KMSKEY
diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst
index d966cb3e..e25f080f 100644
--- a/source/reference/minio-server/minio-server.rst
+++ b/source/reference/minio-server/minio-server.rst
@@ -415,9 +415,18 @@ Key Management Service and Encryption
.. envvar:: MINIO_KMS_KES_KEY_NAME
The name of an external key on the Key Management system (KMS) configured on
- the KES server and used for performing en/decryption operations. MinIO uses
- this key for supporting server-side encryption of objects (SSE-S3) and MinIO
- backend encryption.
+ the KES server and used for performing en/decryption operations. MinIO
+ uses this key for the following:
+
+ - Encrypting backend data (
+ :ref:`IAM `,
+ server configuration).
+
+ - The default encryption key for Server-Side Encryption with
+ :ref:`SSE-KMS `.
+
+ - The encryption key for Server-Side Encryption with
+ :ref:`SSE-S3 `.
.. _minio-server-envvar-storage-class:
diff --git a/source/security/encryption/encryption-key-management.rst b/source/security/encryption/encryption-key-management.rst
deleted file mode 100644
index f1582955..00000000
--- a/source/security/encryption/encryption-key-management.rst
+++ /dev/null
@@ -1,257 +0,0 @@
-.. _minio-sse:
-
-=============================
-Encryption and Key Management
-=============================
-
-.. default-domain:: minio
-
-.. contents:: Table of Contents
- :local:
- :depth: 1
-
-MinIO supports key security features around object-level and network-level
-encryption:
-
-Server-Side Object Encryption
------------------------------
-
-MinIO supports :ref:`Server-Side Object Encryption (SSE) ` of
-objects, where MinIO uses a secret key to encrypt and store objects on disk
-(encryption at-rest). MinIO SSE requires :ref:`minio-encryption-tls`.
-
-MinIO supports the following SSE encryption types:
-
-.. _minio-encryption-sse-s3:
-
-SSE-S3
- The MinIO server en/decrypts an object using a secret key managed by
- an external Key Management System (KMS). MinIO SSE-S3 requires using
- :minio-git:`MinIO KES ` for supporting scalable distributed
- cryptographic operations using the KMS.
-
- MinIO supports both automatic and client-driven encryption of objects
- *before* storing the data to disk. MinIO automatically decrypts
- objects using the required keys on read for any client with
- :ref:`read permission ` for the bucket and object.
-
- MinIO can only decrypt an object if it can retrieve the
- :ref:`Customer Master Key (CMK) `
- used to encrypt an object from the configured KES service.
-
- MinIO SSE-S3 provides similar functionality to
- Amazon :s3-docs:`Server-Side Encryption with Amazon-Managed Keys
- `. MinIO SSE-S3 supports multiple
- KMS providers in addition to AWS KMS, including Thales CipherTrust
- (formerly Gemalto KeySecure) and Hashicorp KeyVault.
-
-.. _minio-encryption-sse-c:
-
-SSE-C
- The MinIO server en/decrypts an object using a secret encryption key
- provided by the application as part of the HTTP request. SSE-C
- requires the application to manage key creation and storage. MinIO
- never stores encryption keys specified as part of SSE-C.
-
- MinIO supports client-driven encryption of objects *before* storing
- the data to disk. MinIO automatically decrypts objects using a
- client-specified key on read. Only clients which specify the correct
- encryption key can successfully retrieve the protected object.
- Clients must additionally have :ref:`read permission `
- for the bucket and object.
-
- SSE-C encrypted objects are not compatible with MinIO
- :ref:`bucket replication `. For MinIO
- deployments configured for SSE-S3 automatic encryption,
- writing an object with SSE-C encryption headers prevents SSE-S3
- encryption of that object.
-
- MinIO SSE-C provides similar functionality to
- Amazon :s3-docs:`Server-Side Encryption with Customer Keys
- `.
-
-.. _minio-encryption-sse-encryption-process:
-
-Encryption Process Overview
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-MinIO uses three distinct keys when performing server-side encryption or
-decryption:
-
-.. list-table::
- :header-rows: 1
- :widths: 30 70
-
- * - Key
- - Description
-
- * - External Key (EK)
- - An external secret key used to generate and encrypt additional encryption
- keys.
-
- - For SSE-C, the EK is the client-provided encryption key. MinIO
- never stores this key to disk and requires the application to perform
- all key management operations.
-
- - For SSE-S3, the EK is generated by :minio-git:`MinIO KES ` using
- a Customer Master Key (CMK) stored in the configured external KMS.
- KES returns a plain-text representation of the EK for performing
- cryptographic operations, and a CMK-encrypted representation of the
- EK for storage alongside the object metadata.
-
- See the :minio-git:`KES Wiki ` for more information on
- configuring KES.
-
- MinIO cannot decrypt objects encrypted using SSE-C or SSE-S3 without the
- associated EK or CMK respectively. Disabling or deleting these keys
- results in associated encrypted objects being rendered unreadable. See
- :ref:`minio-encryption-sse-secure-erasure-locking` for more information.
-
- * - Key Encryption Key (KEK)
- - A 256-bit unique random secret key deterministically generated by MinIO
- at the time of each cryptographic operation. MinIO never stores the KEK
- on disk.
-
- The key-derivation algorithm uses a pseudo-random function
- (:ref:`PRF `) that
- takes the EK, a randomly generated initialization vector, and
- a context consisting of values like the bucket and object name.
-
- * - Object Encryption Key (OEK)
- - A 256-bit unique random secret key used to encrypt or decrypt an object.
- MinIO generates an OEK when first encrypting an object. MinIO encrypts
- the OEK using the KEK and stores the encrypted OEK as metadata with the
- object.
-
- MinIO decrypts the OEK into RAM as part of cryptographic operations.
- MinIO never stores the OEK on disk in an unecrypted format.
-
-All secret keys generated by MinIO are 256-bits long. MinIO uses a
-cryptographically secure pseudo-random generator (CSPRNG) as part of key
-generation. In the context of SSE, the MinIO CSPRNG only enforces that the
-generated values are unique rather than truly random.
-
-The following diagrams describe the key hierarchy built by MinIO
-for each object. Each tab corresponds to the specific hierarchy for
-SSE-S3 and SSE-C respectively:
-
-.. tab-set::
-
- .. tab-item:: SSE-S3
-
- .. image:: /images/minio-encryption-sse-s3-key-hierarchy.svg
- :width: 600px
- :alt: Key Hierarchy for MinIO SSE-S protected objects. Customer Master Key to Encryption Key to Key Encryption Key to Object Encryption Key. Only encrypted key metadata is kept on disk.
- :align: center
-
- .. tab-item:: SSE-C
-
- .. image:: /images/minio-encryption-sse-c-key-hierarchy.svg
- :width: 600px
- :alt: Key Hierarchy for MinIO SSE-S protected objects. Customer Master Key to Encryption Key to Key Encryption Key to Object Encryption Key. Only encrypted key metadata is kept on disk.
- :align: center
-
-.. _minio-encryption-sse-content-encryption:
-
-Content Encryption
-~~~~~~~~~~~~~~~~~~
-
-The MinIO server uses an authenticated encryption scheme
-(:ref:`AEAD `) to en/decrypt and authenticate
-the object content. The AEAD is combined with some state to build a
-**Secure Channel**. A Secure Channel is a cryptographic construction that
-ensures confidentiality and integrity of the processed data. In particular, the
-Secure Channel splits the plaintext content into fixed size chunks and
-en/decrypts each chunk separately using an unique key-nonce combination.
-
-The following text diagram illustrates Secure Channel Construction of an
-encrypted object:
-
-The Secure Channel splits the object content into chunks of a fixed size of
-``65536`` bytes. The last chunk may be smaller to avoid adding additional
-overhead and is treated specially to prevent truncation attacks. The nonce
-value is ``96`` bits long and generated randomly per object / multi-part part.
-The Secure Channel supports plaintexts up to ``65536 * 2^32 = 256 TiB``.
-
-For S3 multi-part operations, each object part is en/decrypted with the Secure
-Channel Construction scheme shown above. For each part, MinIO generates a secret
-key derived from the Object Encryption Key (OEK) and the part number using a
-pseudo-random function (:ref:`PRF `), such that
-``key = PRF(OEK, part_id)``.
-
-.. _minio-encryption-sse-primitives:
-
-Cryptographic Primitives
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The MinIO server uses the following cryptographic primitive implementations:
-
-.. list-table::
- :stub-columns: 1
- :widths: 40 60
- :width: 100%
-
- * - Pseudo-Random Functions (PRF)
- - HMAC-SHA-256
-
- * - :ref:`AEAD `
- - ``ChaCha20Poly-1305`` by default.
-
- ``AES-256-GCM`` for x86-64 CPUs with the AES-NI extension.
-
-.. _minio-encryption-sse-secure-erasure-locking:
-
-Secure Erasure and Locking
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For SSE-S3 encrypted objects, MinIO requires access to both the KMS *and* the
-:ref:`Customer Master Key (CMK) ` used
-to encrypt the object(s). You can leverage this functionality to erase or lock
-some or all encrypted objects by disabling access to the EK or CMK used for
-SSE-S3 encryption. For example:
-
-- Seal the KMS such that it cannot be accessed by MinIO server anymore. This
- locks all SSE-S3 encrypted objects protected by any CMK stored on the KMS. The
- encrypted objects remain unreadable as long as the KMS remains sealed.
-
-- Seal/Unmount one/some CMK(s). This locks all SSE-S3 encrypted objects
- protected by the CMK(s). The encrypted objects remain unreadable as long
- as the CMK(s) remains sealed.
-
-- Delete one/some CMK(s). This renders all SSE-S3 encrypted objects protected
- by the CMK(s) as permanently unreadable. This is equivalent to securely
- erasing all SSE-S3 encrypted objects protected by the CMK(s). The combination
- of deleting CMK(s) and deleting the data may fulfill regulatory requirements
- around secure deletion of data.
-
- Deleting a master key is typically irreversible. Exercise extreme caution
- before intentionally deleting a master key.
-
-For SSE-C encrypted objects, MinIO requires access to the encryption key
-used to secure those objects. You can render an encrypted object as temporarily
-or permanently unreadable by disabling or deleting the
-:ref:`secret key ` used to encrypt
-that object.
-
-.. _minio-encryption-tls:
-
-Transport Layer Security (TLS)
-------------------------------
-
-MinIO supports :ref:`Transport Layer Security (TLS) ` encryption of
-incoming and outgoing traffic.
-
-TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
-`deprecated `__ as of June 30th, 2018.
-MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).
-
-See :ref:`Transport Layer Security (TLS) `
-for more complete instructions on configuring MinIO for TLS.
-
-.. toctree::
- :titlesonly:
- :hidden:
-
- /security/encryption/server-side-encryption-sse-s3
- /security/encryption/server-side-encryption-sse-c
- /security/encryption/transport-layer-security
diff --git a/source/security/encryption/server-side-encryption-sse-s3.rst b/source/security/encryption/server-side-encryption-sse-s3.rst
deleted file mode 100644
index 90e2f4c2..00000000
--- a/source/security/encryption/server-side-encryption-sse-s3.rst
+++ /dev/null
@@ -1,357 +0,0 @@
-.. _minio-server-side-encryption-sse-s3:
-
-===========================================================
-Server-Side Encryption using a Customer Master Key (SSE-S3)
-===========================================================
-
-.. default-domain:: minio
-
-.. contents:: Table of Contents
- :local:
- :depth: 2
-
-The procedure on this page configures and enables automatic and bucket-level
-Server-Side Encryption with a Customer Master Key (SSE-S3). MinIO SSE-S3
-supports automatic and client-driven encryption of objects *before* writing
-them to disk. MinIO automatically decrypts SSE-S3-encrypted objects as part
-of authorized read operations.
-
-The Customer Master Key (CMK) is managed by an external Key Management System
-(KMS). KMS configuration and :abbr:`CMK (Customer Master Key)` generation are
-managed by the MinIO :minio-git:`Key Encryption Service `. MinIO uses KES
-for supporting specific cryptographic operations as part of the
-:ref:`encryption process `, such as
-the retrieval of the CMK and subsequent generation of object encryption keys.
-
-MinIO SSE-S3 is functionally compatible with AWS S3
-:s3-docs:`Server-Side Encryption with Amazon S3-Managed Keys
-` while expanding support to include the
-following KMS providers:
-
-- AWS SecretsManager
-- Google Cloud SecretManager
-- Thales CipherTrust (formerly Gemalto KeySecure)
-- Hashicorp KeyVault
-
-Requirements
-------------
-
-Install and Configure ``mc`` with Access to the MinIO Cluster
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This procedure uses :mc:`mc` for performing operations on the source MinIO
-deployment. Install :mc:`mc` on a machine with network access to the source
-deployment. See the ``mc`` :ref:`Installation Quickstart ` for
-instructions on downloading and installing ``mc``.
-
-Install and Configure MinIO KES
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This procedure uses the
-:minio-git:`MinIO Key Encryption Service (KES) ` server and client for
-configuring and enabling SSE-S3. See the ``kes``
-:minio-git:`Getting Started ` guide for
-instructions on downloading, installing, and configuring KES.
-
-This procedure makes the following assumptions regarding the KES service:
-
-- The KES service exists and is configured for a supported
- :minio-git:`Key Management Service (KMS) `. The MinIO
- deployment *must* have bidirectional network access to the KES service.
-
-- KES has at least one :minio-git:`identity
- ` that grants permission to
- at minimum the ``/v1/create``, ``/v1/generate``, and ``/v1/list``
- :minio-git:`API endpoints ` Defer to the KES
- documentation for creating policies and identities for supporting
- cryptographic operations.
-
-- KES has at least one Customer Master Key (CMK) for supporting SSE-S3
- cryptographic operations. KES supports creating default keys as part
- of it's :minio-git:`configuration `.
- You can also use the ``kes key create`` command to create a CMK on the
- KES server.
-
-Procedure
----------
-
-1) Create a Customer Master Key for SSE-S3 Encryption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use the :minio-git:`kes ` commandline tool to create a new Customer Master
-Key (CMK) for use with SSE-S3 Encryption.
-
-The following tabs provide instructions for a self-managed MinIO KES service
-*or* the MinIO-managed KES ``play`` sandbox. The sandbox environment is
-appropriate for evaluation environments *only* and should *never* be used
-for Production or any other environment which requires strict data security:
-
-.. tab-set::
-
- .. tab-item:: Self-Managed KES
- :sync: self-kes
-
- Set the following environment variables in the terminal or shell:
-
- .. code-block:: shell
- :class: copyable
-
- export KES_CLIENT_KEY=identity.key
- export KES_CLIENT_CERT=identity.cert
-
- .. list-table::
- :stub-columns: 1
- :widths: 40 60
- :width: 100%
-
- * - ``KES_CLIENT_KEY``
- - The private key for an :minio-git:`identity
- ` on the KES server.
- The identity must grant access to at minimum the ``/v1/create``,
- ``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
- `.
-
- * - ``KES_CLIENT_CERT``
- - The corresponding certificate for the :minio-git:`identity
- ` on the KES server.
-
- .. tab-item:: MinIO ``Play`` Sandbox
- :sync: play-kes
-
- .. important::
-
- The MinIO KES ``Play`` sandbox is public and grants root access to
- all created CMKs. Generated CMKs 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.
-
- Issue the following command to retrieve the root :minio-git:`identity
- ` for the KES server:
-
- .. code-block:: shell
- :class: copyable
-
- 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:
-
- .. code-block:: shell
- :class: copyable
-
- export KES_CLIENT_KEY=root.key
- export KES_CLIENT_CERT=root.cert
-
- .. list-table::
- :stub-columns: 1
- :widths: 40 60
- :width: 100%
-
- * - ``KES_CLIENT_KEY``
- - The private key for an :minio-git:`identity
- ` on the KES server.
- The identity must grant access to at minimum the ``/v1/create``,
- ``/v1/generate``, and ``/v1/list`` :minio-git:`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 :minio-git:`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.
-
-Issue the following command to create a new Customer Master Key (CMK) through
-KES:
-
-.. code-block:: shell
- :class: copyable
-
- kes key create my-minio-sse-s3-key
-
-This tutorial uses the example ``my-minio-sse-s3-key`` name for ease of
-reference. MinIO recommends specifying a key name that meets your organization's
-requirements for naming secure encryption keys.
-
-KES creates the new CMK on the configured Key Management System (KMS). MinIO
-uses the CMK to generate additional encryption keys for use with SSE-S3.
-See :ref:`minio-encryption-sse-encryption-process` for more information on the
-SSE encryption process.
-
-2) Configure MinIO for SSE-S3 Object Encryption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following tabs provide instructions for a self-managed MinIO KES service
-*or* the MinIO-managed KES ``play`` sandbox. The sandbox environment is
-appropriate for evaluation environments *only* and should *never* be used
-for Production or any other environment which requires strict data security.
-Select the same tab used for the previous step:
-
-.. tab-set::
-
- .. tab-item:: Self-Managed KES
- :sync: self-kes
-
- Specify the following environment variables in the shell or terminal:
-
- .. code-block:: shell
- :class: copyable
-
- export MINIO_KMS_KES_ENDPOINT=https://kes.example.net:7373
- export MINIO_KMS_KES_KEY_FILE=identity.key
- export MINIO_KMS_KES_CERT_FILE=identity.cert
- export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key
-
- .. list-table::
- :stub-columns: 1
- :widths: 30 80
-
- * - :envvar:`MINIO_KMS_KES_ENDPOINT`
- - The endpoint for the KES service to use for supporting SSE-S3
- operations.
-
- * - :envvar:`MINIO_KMS_KES_KEY_FILE`
- - The private key file corresponding to an
- :minio-git:`identity `
- on the KES service. The identity must grant permission to
- create, generate, and decrypt keys. You can specify the same
- identity key file as the ``KES_KEY_FILE`` environment variable
- in the previous step.
-
- * - :envvar:`MINIO_KMS_KES_CERT_FILE`
- - The public certificate file corresponding to an
- :minio-git:`identity `
- on the KES service. The identity must grant permission to
- create, generate, and decrypt keys. You can specify the same
- identity certificate as the ``KES_CERT_FILE`` environment
- variable in the previous step.
-
- * - :envvar:`MINIO_KMS_KES_KEY_NAME`
- - The name of the Customer Master Key (CMK) to use for
- performing SSE encryption operations. KES retrieves the CMK from
- the configured Key Management System (KMS). Specify the name of the
- key created in the previous step.
-
- .. tab-item:: MinIO ``Play`` Sandbox
- :sync: play-kes
-
- .. important::
-
- The MinIO KES ``Play`` sandbox is public and grants root access to
- all created CMKs. Generated CMKs 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.
-
- Specify the following environment variables in the shell or terminal:
-
- .. code-block:: shell
- :class: copyable
-
- 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
-
- .. list-table::
- :stub-columns: 1
- :widths: 30 80
-
- * - :envvar:`MINIO_KMS_KES_ENDPOINT`
- - The endpoint for the MinIO ``Play`` KES service.
-
- * - :envvar:`MINIO_KMS_KES_KEY_FILE`
- - The private key file corresponding to an
- :minio-git:`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.
-
- * - :envvar:`MINIO_KMS_KES_CERT_FILE`
- - The public certificate file corresponding to an
- :minio-git:`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.
-
- * - :envvar:`MINIO_KMS_KES_KEY_NAME`
- - The name of the Customer Master Key (CMK) to use for
- performing SSE encryption operations. KES retrieves the CMK 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-cmd:`mc admin service restart` command to restart the deployment.
-
-.. important::
-
- MinIO restarts *all* :mc:`minio server` processes associated to the
- deployment at the same time. Applications may experience a brief period of
- downtime during the restart process.
-
- Consider scheduling the restart during a maintenance period to minimize
- interruption of services.
-
-.. code-block:: shell
- :class: copyable
-
- mc admin service restart ALIAS
-
-Replace ``ALIAS`` with the :mc:`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-cmd:`mc encrypt set` command to enable automatic SSE-S3 protection
-of all objects written to a specific bucket.
-
-.. code-block:: shell
- :class: copyable
-
- mc encrypt set sse-s3 ALIAS/BUCKET
-
-- Replace :mc-cmd:`ALIAS ` with the
- :mc:`alias ` of the MinIO deployment on which you enabled SSE-S3.
-
-- Replace :mc-cmd:`BUCKET ` with the full path to the
- bucket or bucket prefix on which you want to enable automatic SSE-S3.
-
-5) Manually Encrypt Objects using SSE-S3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Optional*
-
-You can skip this step for buckets configured with automatic SSE-S3 encryption.
-
-Specify the ``X-Amz-Server-Side-Encryption`` header with value
-``AES256`` to direct the MinIO server to apply SSE-S3 protection to the object.
-
-The MinIO :mc:`mc` commandline tool S3-compatible SDKs include specific syntax
-for setting headers. Certain :mc:`mc` commands like :mc:`mc cp` include specific
-arguments for enabling SSE-S3 encryption:
-
-.. code-block:: shell
- :class: copyable
-
- mc cp ~/data/mydata.json ALIAS/BUCKET/mydata.json --encrypt ALIAS/BUCKET
-
-- Replace :mc-cmd:`ALIAS ` with the
- :mc:`alias ` of the MinIO deployment on which you enabled SSE-S3.
-
-- Replace :mc-cmd:`BUCKET ` with the full path to the
- bucket or bucket prefix in which you are interacting with the SSE-S3 encrypted
- object.
\ No newline at end of file
diff --git a/source/security/encryption/transport-layer-security.rst b/source/security/encryption/transport-layer-security.rst
deleted file mode 100644
index 3c909336..00000000
--- a/source/security/encryption/transport-layer-security.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-.. _minio-TLS:
-
-==============================
-MinIO Transport Layer Security
-==============================
-
-.. default-domain:: minio
-
-.. contents:: Table of Contents
- :local:
- :depth: 1
-
-Overview
---------
-
-The MinIO server supports enabling TLS encryption of incoming and outgoing
-traffic. MinIO recommends all MinIO servers run with TLS enabled to ensure
-end-to-end security of client-server or server-server transmissions.
-
-The MinIO server looks for a private key ``private.key`` and public certificate
-``public.crt`` in the following directories:
-
-- **Linux/OSX** : ``${HOME}/.minio/certs``
-
-- **Windows** : ``%%USERPROFILE%%\.minio\certs``
-
-MinIO only supports keys and certificates in the PEM format.
-
-You can customize the certificate directory by passing the ``--certs-dir``
-option to ``minio server``. The ``certs`` directory must also include any
-intermediate certificates required to establish a chain of trust to the root CA.
-
-For more information, see
-:minio-git:`How to secure access to MinIO server with TLS
-`.
\ No newline at end of file
diff --git a/source/security/network-encryption/minio-tls.rst b/source/security/network-encryption/minio-tls.rst
new file mode 100644
index 00000000..a1b0907c
--- /dev/null
+++ b/source/security/network-encryption/minio-tls.rst
@@ -0,0 +1,281 @@
+.. _minio-tls:
+
+========================
+Network Encryption (TLS)
+========================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+The MinIO server supports Transport Layer Security (TLS) encryption of incoming
+and outgoing traffic. MinIO recommends all MinIO servers run with TLS enabled to
+ensure end-to-end security of client-server or server-server transmissions.
+
+TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
+`deprecated `__ as of June 30th, 2018.
+MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).
+
+MinIO supports multiple TLS certificates, where the server uses
+`Server Name Indication (SNI)
+`__ to identify which
+certificate to use when responding to a client request.
+
+For example, consider a MinIO deployment reachable through the following
+hostnames:
+
+- ``https://minio.example.net``
+- ``https://s3.example.net``
+- ``https://minio.internal-example.net``
+
+MinIO can have a single TLS certificate that covers all hostnames with multiple
+Subject Alternative Names (SAN). However, this would reveal the
+``internal-example.net`` hostname to all clients. Instead, you can specify
+multiple TLS certificates to MinIO for the public and private portions of your
+infrastructure to mitigate the risk of leaking internal topologies via TLS SAN.
+When a client connects using a specific hostname, MinIO uses SNI to select the
+appropriate TLS certificate for that hostname.
+
+MinIO by default searches an OS-specific directory for TLS keys and
+certificates. For deployments started with a custom TLS directory
+:mc-cmd-option:`minio server certs-dir`, use that directory instead of the
+defaults.
+
+.. tab-set::
+
+ .. tab-item:: Linux
+ :sync: linux
+
+ MinIO looks for TLS keys in the following directory:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs
+
+ Place the TLS certificates for the default domain (e.g.
+ ``minio.example.net``) in the ``/certs`` directory, with the private key
+ as ``private.key`` and public certificate as ``public.crt``.
+
+ Create a subfolder in ``/certs`` for each additional domain for which
+ MinIO should present TLS certificates. While MinIO has no requirements for
+ folder names, consider creating subfolders whose name matches the domain
+ to improve human readability. Place the TLS private and public key for
+ that domain in the subfolder.
+
+ For example:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs
+ private.key
+ public.cert
+ s3-example.net/
+ private.key
+ public.cert
+ internal-example.net/
+ private.key
+ public.cert
+
+ .. tab-item:: OSX
+ :sync: osx
+
+ MinIO looks for TLS keys in the following directory:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs
+
+ Place the TLS certificates for the default domain (e.g.
+ ``minio.example.net``) in the ``/certs`` directory, with the private key
+ as ``private.key`` and public certificate as ``public.crt``.
+
+ Create a subfolder in ``/certs`` for each additional domain for which
+ MinIO should present TLS certificates. While MinIO has no requirements for
+ folder names, consider creating subfolders whose name matches the domain
+ to improve human readability. Place the TLS private and public key for
+ that domain in the subfolder.
+
+ For example:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs
+ private.key
+ public.cert
+ s3-example.net/
+ private.key
+ public.cert
+ internal-example.net/
+ private.key
+ public.cert
+
+ .. tab-item:: Windows
+ :sync: windows
+
+ MinIO looks for TLS keys in the following directory:
+
+ .. code-block:: shell
+
+ %%USERPROFILE%%\.minio\certs
+
+ Place the TLS certificates for the default domain (e.g.
+ ``minio.example.net``) in the ``\certs`` directory, with the private key
+ as ``private.key`` and public certificate as ``public.crt``.
+
+ Create a subfolder in ``\certs`` for each additional domain for which
+ MinIO should present TLS certificates. While MinIO has no requirements for
+ folder names, consider creating subfolders whose name matches the domain
+ to improve human readability. Place the TLS private and public key for
+ that domain in the subfolder.
+
+ For example:
+
+ .. code-block:: shell
+
+ %%USERPROFILE%%\.minio\certs
+ private.key
+ public.cert
+ s3-example.net\
+ private.key
+ public.cert
+ internal-example.net\
+ private.key
+ public.cert
+
+.. admonition:: MinIO Console TLS Connectivity
+ :class: important
+
+ The :ref:`MinIO Console ` automatically connects via
+ TLS if the MinIO server supports it. However, the Console *by default*
+ attempts to connect using the IP address of the MinIO Server.
+
+ The MinIO Console may fail to connect and throw login errors if this IP
+ address is not included as a
+ :rfc:`Subject Alternative Name <5280#section-4.2.1.6>` in any configured
+ TLS certificate.
+
+ Set the :envvar:`MINIO_SERVER_URL` environment variable to a resolvable
+ DNS hostname covered by one of the configured TLS SANs. This allows
+ the Console to properly validate the certificate and connect to MinIO.
+
+Supported TLS Cipher Suites
+---------------------------
+
+MinIO supports the following TLS 1.2 and 1.3 cipher suites as
+supported by
+`Go `__
+
+.. list-table::
+ :header-rows: 1
+ :widths: 60 20 20
+ :width: 100%
+
+ * - Cipher
+ - TLS 1.2
+ - TLS 1.3
+
+ * - ``TLS_CHACHA20_POLY1305_SHA256``
+ -
+ - :octicon:`check`
+
+ * - ``TLS_AES_128_GCM_SHA256``
+ -
+ - :octicon:`check`
+
+ * - ``TLS_AES_256_GCM_SHA384``
+ -
+ - :octicon:`check`
+
+ * - ``TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305``
+ - :octicon:`check`
+ -
+
+ * - ``TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305``
+ - :octicon:`check`
+ -
+
+ * - ``TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256``
+ - :octicon:`check`
+ -
+
+ * - ``TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256``
+ - :octicon:`check`
+ -
+
+ * - ``TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384``
+ - :octicon:`check`
+ -
+
+ * - ``TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384``
+ - :octicon:`check`
+ -
+
+.. admonition:: Use ECDSA/EdDSA over RSA when when generating certificates
+ :class: note
+
+<<<<<<< HEAD
+ TLS certificates created using Elliptic Curve Cryptography (ECC)
+ cipher suites have lower computation requirements compared to RSA cipher
+ suites. Specifically, MinIO recommends using certificates created with any of
+ the following supported TLS 1.2 cipher suites wherever possible:
+
+ - ``TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305``
+ - ``TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256``
+ - ``TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384``
+
+ All TLS 1.3 cipher suites use ECC by default.
+=======
+ TLS certificates created using
+ :wiki:`Elliptic Curve Cryptography (ECC) ` have
+ lower computation requirements compared to
+ :wikI:`RSA `. Specifically, MinIO
+ recommends generating
+ ECDSA (e.g. `NIST P-256 curve
+ `__) or
+ EdDSA (e.g. :rfc:`Curve25519 <7748>`) TLS private keys/certificates wherever
+ possible.
+>>>>>>> 3cb1c9e (Final pass)
+
+Third-Party Certificate Authorities
+-----------------------------------
+
+MinIO by default uses the Operating System's trusted certificate store for
+validating TLS certificates presented by a connecting client.
+
+For clients connecting with certificates signed by an untrusted Certificate
+Authority (CA) (e.g. self-signed, private/internal, etc.), you can provide the
+necessary CA key for MinIO to explicitly trust:
+
+MinIO by default searches an OS-specific directory for Certificate Authority
+certificates. For deployments started with a custom TLS directory
+:mc-cmd-option:`minio server certs-dir`, use that directory instead of the
+defaults.
+
+.. tab-set::
+
+ .. tab-item:: Linux
+ :sync: linux
+
+ MinIO looks for Certificate Authority keys in the following directory:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs/CAs
+
+ .. tab-item:: OSX
+
+ MinIO looks for Certificate Authority keys in the following directory:
+
+ .. code-block:: shell
+
+ ${HOME}/.minio/certs/CAs
+
+ .. tab-item:: Windows
+
+ MinIO looks for Certificate Authority keys in the following directory:
+
+ .. code-block:: shell
+
+ %%USERPROFILE%%\.minio\certs\CAs
\ No newline at end of file
diff --git a/source/security/security-overview.rst b/source/security/security-overview.rst
index b510a580..0aeacf96 100644
--- a/source/security/security-overview.rst
+++ b/source/security/security-overview.rst
@@ -8,6 +8,10 @@ Security
:local:
:depth: 2
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+
.. _minio-authentication-and-identity-management:
Identity and Access Management
@@ -71,22 +75,61 @@ encryption) and on read/write (at-rest).
Network Encryption
~~~~~~~~~~~~~~~~~~
-MinIO supports :ref:`Transport Layer Security (TLS) ` encryption of
-incoming and outgoing traffic.
+MinIO supports :ref:`Transport Layer Security (TLS) ` encryption of
+incoming and outgoing traffic. MinIO recommends all
+MinIO servers run with TLS enabled to ensure end-to-end security of
+client-server or server-server transmissions.
TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
`deprecated `__ as of June 30th, 2018.
MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).
-See :ref:`minio-encryption-tls` for more complete documentation.
+See :ref:`minio-tls` for more complete documentation.
Server-Side Object Encryption (SSE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports :ref:`Server-Side Object Encryption (SSE) ` of
objects, where MinIO uses a secret key to encrypt and store objects on disk
-(encryption at-rest). MinIO SSE requires :ref:`minio-encryption-tls`.
-See :ref:`minio-sse` for more complete documentation.
+(encryption at-rest).
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS (*Recommended*)
+ :sync: sse-kms
+
+ 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.
+
+ SSE-KMS provides more granular and customizable encryption compared to
+ SSE-S3 and SSE-C and is recommended over the other supported encryption
+ methods.
+
+ .. tab-item:: SSE-S3
+ :sync: sse-s3
+
+ 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.
+
+ .. tab-item:: SSE-C
+ :sync: sse-c
+
+ 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 :ref:`minio-tls`.
.. toctree::
:titlesonly:
@@ -95,5 +138,6 @@ See :ref:`minio-sse` for more complete documentation.
/security/minio-identity-management/basic-authentication-with-minio-identity-provider
/security/openid-external-identity-management/external-authentication-with-openid-identity-provider
/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider
- /security/encryption/encryption-key-management
+ /security/server-side-encryption/minio-server-side-encryption.rst
+ /security/network-encryption/minio-tls.rst
diff --git a/source/security/server-side-encryption/configure-minio-kes-aws.rst b/source/security/server-side-encryption/configure-minio-kes-aws.rst
new file mode 100644
index 00000000..2fdd3e69
--- /dev/null
+++ b/source/security/server-side-encryption/configure-minio-kes-aws.rst
@@ -0,0 +1,382 @@
+.. _minio-sse-aws:
+
+===============================================
+Server-Side Object Encryption with AWS Root KMS
+===============================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) `
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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 |KES-git| and an
+external root Key Management Service (KMS) for performing secured cryptographic
+operations at scale. The root KMS provides stateful and secured storage of
+External Keys (EK) while |KES| is stateless and derives additional cryptographic
+keys from the root-managed |EK|.
+
+This procedure does the following:
+
+- Configure |KES| to use
+ `AWS Secrets Manager `__ as the root
+ |KMS|.
+
+- Configure MinIO to use the |KES| instance for supporting |SSE|.
+
+- Configure automatic bucket-default
+ :ref:`SSE-KMS ` and
+ :ref:`SSE-S3 `.
+
+Prerequisites
+-------------
+
+.. _minio-sse-aws-prereq-aws:
+
+AWS Key Management Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This procedure assumes familiarity with
+`AWS Key Management Service `__ and
+`AWS Secrets Manager `__.
+The `Getting Started with AWS Key Management Service
+`__
+provides a sufficient foundation for the purposes of this procedure.
+
+MinIO specifically requires the following AWS settings or
+configurations:
+
+- A new AWS
+ :aws-docs:`Programmatic Access `
+ user with corresponding access key and secret key.
+
+- A policy that grants the created user access to AWS Secrets Manager and
+ AWS KMS. The following policy grants the minimum necessary permissions:
+
+ .. code-block:: json
+ :class: copyable
+
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Sid": "minioSecretsManagerAccess",
+ "Action": [
+ "secretsmanager:CreateSecret",
+ "secretsmanager:DeleteSecret",
+ "secretsmanager:GetSecretValue",
+ "secretsmanager:ListSecrets"
+ ],
+ "Effect": "Allow",
+ "Resource": "*"
+ },
+ {
+ "Sid": "minioKmsAccess",
+ "Action": [
+ "kms:Decrypt",
+ "kms:DescribeKey",
+ "kms:Encrypt"
+ ],
+ "Effect": "Allow",
+ "Resource": "*"
+ }
+ ]
+ }
+
+
+ AWS provides the ``SecretsManagerReadWrite`` and
+ ``AWSKeyManagementServicePowerUser`` canned roles that meet and exceed the
+ minimum required permissions.
+
+Network Encryption (TLS)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-network-encryption-desc
+ :end-before: end-kes-network-encryption-desc
+
+Podman Container Manager
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-podman-desc
+ :end-before: end-kes-podman-desc
+
+Enable MinIO Server-Side Encryption with AWS Root KMS
+-----------------------------------------------------
+
+The following steps deploy |KES-git| configured to use an existing AWS KMS and
+Secrets Manager deployment as the root KMS for supporting |SSE|. These steps
+assume the AWS components meet the :ref:`prerequisites
+`.
+
+Prior to starting these steps, create the following folders:
+
+.. code-block:: shell
+ :class: copyable
+
+ mkdir -P ~/kes/certs ~/kes/config
+
+1) Download the MinIO Key Encryption Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-download-desc
+ :end-before: end-kes-download-desc
+
+2) Generate the TLS Private and Public Key for KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-kes-certs-desc
+ :end-before: end-kes-generate-kes-certs-desc
+
+3) Generate the TLS Private and Public Key for MinIO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-minio-certs-desc
+ :end-before: end-kes-generate-minio-certs-desc
+
+4) Create the KES Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|KES| uses a YAML-formatted configuration file. The following example YAML
+specifies the minimum required fields for enabling |SSE| using AWS Secrets
+Manager:
+
+.. code-block:: shell
+ :class: copyable
+
+ address: 0.0.0.0:7373
+
+ # Disable the root identity, as we do not need that level of access for
+ # supporting SSE operations.
+ root: disabled
+
+ # Specify the TLS keys generated in the previous step here
+ # For production environments, use keys signed by a known and trusted
+ # Certificate Authority (CA).
+ tls:
+ key: /data/certs/server.key
+ cert: /data/certs/server.cert
+
+ # Create a policy named 'minio' that grants access to the
+ # /create, /generate, and /decrypt KES APIs for any key name
+ # KES uses mTLS to grant access to this policy, where only the client
+ # whose TLS certificate hash matches one of the "identities" can
+ # use this policy. Specify the hash of the MinIO server TLS certificate
+ # hash here.
+ policy:
+ minio:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
+
+ # Specify the connection information for the KMS and Secrets Manager endpoint.
+ # The endpoint should be resolvable from the host.
+ # This example assumes that the associated AWS account has the necessary
+ # access key and secret key
+ keystore:
+ secretsmanager:
+ endpoint: secretsmanager.REGION.amazonaws # use the Secrets Manager endpoint for your region
+ region: REGION # e.g. us-east-1
+ kmskey: "" # Optional. The root AWS KMS key to use for cryptographic operations. Formerly described as the "Customer Master Key".
+ credentials:
+ accesskey: "${AWSACCESSKEY}" # AWS Access Key
+ secretkey: "${AWSSECRETKEY}" # AWS Secret Key
+
+
+Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
+value ``${VARIABLE}`` uses the environment variable with matching name as the
+value. You can use this functionality to set credentials without writing them to
+the configuration file.
+
+- Set ``MINIO_IDENTITY_HASH`` to the output of
+ ``kes tool identity of minio-kes.cert``.
+
+- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
+ The value **must** match for both ``endpoint`` and ``region``.
+
+- Set ``AWSACCESSKEY`` and ``AWSSECRETKEY`` to the appropriate
+ :ref:`AWS Credentials `.
+
+5) Start KES
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-run-server-desc
+ :end-before: end-kes-run-server-desc
+
+6) Generate a Cryptographic Key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-key-desc
+ :end-before: end-kes-generate-key-desc
+
+7) Configure MinIO to connect to KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-configure-minio-desc
+ :end-before: end-kes-configure-minio-desc
+
+8) Enable Automatic Server-Side Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS
+
+ The following command enables SSE-KMS on all objects written to the
+ specified bucket:
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+ .. tab-item:: SSE-S3
+
+ The following command enables SSE-S3 on all objects written to the
+ specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
+ key for performing |SSE|.
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-S3 ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+Configuration Reference for AWS Root KMS
+----------------------------------------
+
+The following section describes each of the |KES-git| configuration settings for
+using AWS Secrets Manager and AWS KMS as the root Key Management Service
+(KMS) for |SSE|:
+
+.. tab-set::
+
+ .. tab-item:: YAML Overview
+
+ The following YAML describes the minimum required fields for configuring
+ AWS Secrets Manager as an external KMS for supporting |SSE|.
+
+ Any field with value ``${VARIABLE}`` uses the environment variable
+ with matching name as the value. You can use this functionality to set
+ credentials without writing them to the configuration file.
+
+ .. code-block:: yaml
+
+ address: 0.0.0.0:7373
+ root: ${ROOT_IDENTITY}
+
+ tls:
+ key: kes-server.key
+ cert: kes-server.cert
+
+ policy:
+ minio-server:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY}
+
+ keys:
+ - name: "minio-encryption-key-alpha"
+ - name: "minio-encryption-key-baker"
+ - name: "minio-encryption-key-charlie"
+
+ keystore:
+ secretsmanager:
+ endpoint: secretsmanager.REGION.amazonaws
+ region: REGION
+ kmskey: ""
+ credentials:
+ accesskey: "${AWS_ACCESS_KEY}"
+ secretkey: "${AWS_SECRET_KEY}"
+
+ .. tab-item:: Reference
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 30 70
+ :width: 100%
+
+ * - Key
+ - Description
+
+ * - ``address``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-address-desc
+ :end-before: end-kes-conf-address-desc
+
+ * - ``root``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-root-desc
+ :end-before: end-kes-conf-root-desc
+
+ * - ``tls``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-tls-desc
+ :end-before: end-kes-conf-tls-desc
+
+ * - ``policy``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-policy-desc
+ :end-before: end-kes-conf-policy-desc
+
+ * - ``keys``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-keys-desc
+ :end-before: end-kes-conf-keys-desc
+
+ * - ``keystore.secretsmanager``
+ - The configuration for the AWS Secrets Manager and AWS KMS.
+
+ - ``endpoint`` - The endpoint for the Secrets Manager service,
+ including the region.
+
+ - ``approle`` - The AWS region to use for other AWS services.
+
+ - ``kmskey`` - The root KMS Key to use for cryptographic
+ operations. Formerly known as the Customer Master Key.
+
+ - ``credentials`` - The AWS Credentials to use for performing
+ authenticated operations against Secrets Manager and KMS.
+
+ The specified credentials *must* have the appropriate
+ :ref:`permissions `
diff --git a/source/security/server-side-encryption/configure-minio-kes-azure.rst b/source/security/server-side-encryption/configure-minio-kes-azure.rst
new file mode 100644
index 00000000..ef3a2254
--- /dev/null
+++ b/source/security/server-side-encryption/configure-minio-kes-azure.rst
@@ -0,0 +1,355 @@
+.. _minio-sse-azure:
+
+===========================================================
+Server-Side Object Encryption with Azure Key Vault Root KMS
+===========================================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) `
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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 |KES-git| and an
+external root Key Management Service (KMS) for performing secured cryptographic
+operations at scale. The root KMS provides stateful and secured storage of
+External Keys (EK) while |KES| is stateless and derives additional cryptographic
+keys from the root-managed |EK|.
+
+This procedure does the following:
+
+- Configure |KES| to use
+ `Azure Key Vault
+ `__
+ as the root |KMS|.
+
+- Configure MinIO to use the |KES| instance for supporting |SSE|.
+
+- Configure automatic bucket-default
+ :ref:`SSE-KMS ` and
+ :ref:`SSE-S3 `.
+
+
+Prerequisites
+-------------
+
+.. _minio-sse-azure-prereq-azure:
+
+Azure Key Vault
+~~~~~~~~~~~~~~~
+
+This procedure assumes familiarity with `Azure Key Vault
+`__. The
+`Key Vault Quickstart
+`__
+provides a sufficient foundation for the purposes of this procedure.
+
+MinIO specifically requires the following Azure settings or
+configurations:
+
+- `Register an application `__
+ for |KES| (e.g. ``minio-kes``). Note the :guilabel:`Application (client) ID`,
+ :guilabel:`Directory (tenant) ID`, and :guilabel:`Client credentials`.
+ You may need to create the client credentials secret and copy the
+ :guilabel:`Secret Value` for use in this procedure.
+
+- Create an `Access Policy `__
+ for use by KES. The policy **must** have the following
+ :guilabel:`Secret Permissions`:
+
+ - ``Get``
+ - ``List``
+ - ``Set``
+ - ``Delete``
+ - ``Purge``
+
+ Set the :guilabel:`Principal` for the new policy to the KES Application ID.
+
+Network Encryption (TLS)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-network-encryption-desc
+ :end-before: end-kes-network-encryption-desc
+
+Podman Container Manager
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-podman-desc
+ :end-before: end-kes-podman-desc
+
+Enable MinIO Server-Side Encryption with Azure Key Vault Root KMS
+-----------------------------------------------------------------
+
+The following steps deploy |KES-git| configured to use an existing AWS KMS and
+Key Vault deployment as the root KMS for supporting |SSE|. These steps
+assume the AWS components meet the :ref:`prerequisites
+`.
+
+Prior to starting these steps, create the following folders:
+
+.. code-block:: shell
+ :class: copyable
+
+ mkdir -P ~/kes/certs ~/kes/config
+
+1) Download the MinIO Key Encryption Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-download-desc
+ :end-before: end-kes-download-desc
+
+2) Generate the TLS Private and Public Key for KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-kes-certs-desc
+ :end-before: end-kes-generate-kes-certs-desc
+
+3) Generate the TLS Private and Public Key for MinIO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-minio-certs-desc
+ :end-before: end-kes-generate-minio-certs-desc
+
+4) Create the KES Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|KES| uses a YAML-formatted configuration file. The following example YAML
+specifies the minimum required fields for enabling |SSE| using AWS Secrets
+Manager:
+
+.. code-block:: shell
+ :class: copyable
+
+ address: 0.0.0.0:7373
+
+ # Disable the root identity, as we do not need that level of access for
+ # supporting SSE operations.
+ root: disabled
+
+ # Specify the TLS keys generated in the previous step here
+ # For production environments, use keys signed by a known and trusted
+ # Certificate Authority (CA).
+ tls:
+ key: /data/certs/server.key
+ cert: /data/certs/server.cert
+
+ # Create a policy named 'minio' that grants access to the
+ # /create, /generate, and /decrypt KES APIs for any key name
+ # KES uses mTLS to grant access to this policy, where only the client
+ # whose TLS certificate hash matches one of the "identities" can
+ # use this policy. Specify the hash of the MinIO server TLS certificate
+ # hash here.
+ policy:
+ minio:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
+
+ # Specify the connection information for the Key Vualt endpoint.
+ # The endpoint should be resolvable from the host.
+ # This example assumes that the specified Key Vault and Azure tenant/client
+ # have the necessary permissions set.
+
+ keystore:
+ azure:
+ keyvault:
+ endpoint: "https://vault.azure.net" # The Azure Keyvault Instance Endpoint
+ credentials:
+ tenant_id: "${TENANTID}" # The directory/tenant UUID
+ client_id: "${CLIENTID}" # The application/client UUID
+ client_secret: "${CLIENTSECRET}" # The Active Directory secret for the application
+
+Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
+value ``${VARIABLE}`` uses the environment variable with matching name as the
+value. You can use this functionality to set credentials without writing them to
+the configuration file.
+
+- Set ``MINIO_IDENTITY_HASH`` to the output of
+ ``kes tool identity of minio-kes.cert``.
+
+- Replace the ``endpoint`` with the URL for the Keyvault instance.
+
+- Set ``TENANTID``, ``CLIENTID``, and ``CLIENTSECRET`` to match the credentials
+ for a project user with
+ the :ref:`required permissions `.
+
+5) Start KES
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-run-server-desc
+ :end-before: end-kes-run-server-desc
+
+6) Generate a Cryptographic Key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-key-desc
+ :end-before: end-kes-generate-key-desc
+
+7) Configure MinIO to connect to KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-configure-minio-desc
+ :end-before: end-kes-configure-minio-desc
+
+8) Enable Automatic Server-Side Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS
+
+ The following command enables SSE-KMS on all objects written to the
+ specified bucket:
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+ .. tab-item:: SSE-S3
+
+ The following command enables SSE-S3 on all objects written to the
+ specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
+ key for performing |SSE|.
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-S3 ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+Configuration Reference for Azure Key Vault Root KMS
+----------------------------------------------------
+
+The following section describes each of the |KES-git| configuration settings for
+using Azure Key Vault as the root Key Management Service
+(KMS) for |SSE|:
+
+.. tab-set::
+
+ .. tab-item:: YAML Overview
+
+ The following YAML describes the minimum required fields for configuring
+ Azure Key Vault as an external KMS for supporting |SSE|.
+
+ Any field with value ``${VARIABLE}`` uses the environment variable
+ with matching name as the value. You can use this functionality to set
+ credentials without writing them to the configuration file.
+
+ .. code-block:: yaml
+
+ address: 0.0.0.0:7373
+ root: ${ROOT_IDENTITY}
+
+ tls:
+ key: kes-server.key
+ cert: kes-server.cert
+
+ policy:
+ minio-server:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY}
+
+ keys:
+ - name: "minio-encryption-key-alpha"
+ - name: "minio-encryption-key-baker"
+ - name: "minio-encryption-key-charlie"
+
+ keystore:
+ azure:
+ keyvault:
+ endpoint: "https://.vault.azure.net"
+ credentials:
+ tenant_id: "${TENANTID}" # The directory/tenant UUID
+ client_id: "${CLIENTID}" # The application/client UUID
+ client_secret: "${CLIENTSECRET}" # The Active Directory secret for the application
+
+
+ .. tab-item:: Reference
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 30 70
+ :width: 100%
+
+ * - Key
+ - Description
+
+ * - ``address``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-address-desc
+ :end-before: end-kes-conf-address-desc
+
+ * - ``root``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-root-desc
+ :end-before: end-kes-conf-root-desc
+
+ * - ``tls``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-tls-desc
+ :end-before: end-kes-conf-tls-desc
+
+ * - ``policy``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-policy-desc
+ :end-before: end-kes-conf-policy-desc
+
+ * - ``keys``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-keys-desc
+ :end-before: end-kes-conf-keys-desc
+
+ * - ``keystore.azure.keyvault``
+ - The configuration for the Azure Key Vault
+
+ - ``endpoint`` - The hostname for the Key Vault service.
+
+ - ``credentials`` - Replace the ``credentials`` with the
+ credentials for the Active Directory application as which KES
+ authenticates.
+
+ The specified credentials must have the appropriate
+ :ref:`permissions `
diff --git a/source/security/server-side-encryption/configure-minio-kes-gcp.rst b/source/security/server-side-encryption/configure-minio-kes-gcp.rst
new file mode 100644
index 00000000..09518868
--- /dev/null
+++ b/source/security/server-side-encryption/configure-minio-kes-gcp.rst
@@ -0,0 +1,353 @@
+.. _minio-sse-gcp:
+
+==============================================================
+Server-Side Object Encryption with GCP Secret Manager Root KMS
+==============================================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) `
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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 |KES-git| and an
+external root Key Management Service (KMS) for performing secured cryptographic
+operations at scale. The root KMS provides stateful and secured storage of
+External Keys (EK) while |KES| is stateless and derives additional cryptographic
+keys from the root-managed |EK|.
+
+This procedure does the following:
+
+- Configure |KES| to use
+ `Google Cloud Platform Secret Manager
+ `__ as the root |KMS|.
+
+- Configure MinIO to use the |KES| instance for supporting |SSE|.
+
+- Configure automatic bucket-default
+ :ref:`SSE-KMS ` and
+ :ref:`SSE-S3 `.
+
+Prerequisites
+-------------
+
+.. _minio-sse-gcp-prereq-gcp:
+
+GCP Secret Manager
+~~~~~~~~~~~~~~~~~~
+
+This procedure assumes familiarity with
+`GCP Secret Manager `__.
+The `Secret Manager Quickstart
+`__
+provides a sufficient foundation for the purposes of this procedure.
+
+MinIO specifically requires the following GCP settings or
+configurations:
+
+- `Enable Secret Manager `__
+ in the project.
+
+- Create a new GCP Service Account for supporting |KES|. Ensure the user has
+ a role with *at minimum* the following permissions:
+
+ .. code-block:: text
+ :class: copyable
+
+ secretmanager.secrets.create
+ secretmanager.secrets.delete
+ secretmanager.secrets.get
+
+ The ``Secret manager Admin`` role meets the minimum required permissions.
+
+ GCP should return a set of credentials associated to the new service account,
+ including private keys. Copy these credentials to a safe and secure location
+ for use with this procedure.
+
+Network Encryption (TLS)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-network-encryption-desc
+ :end-before: end-kes-network-encryption-desc
+
+Podman Container Manager
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-podman-desc
+ :end-before: end-kes-podman-desc
+
+Enable MinIO Server-Side Encryption with GCP Secret Manager Root KMS
+--------------------------------------------------------------------
+
+The following steps deploy |KES-git| configured to use an existing AWS KMS and
+Secrets Manager deployment as the root KMS for supporting |SSE|. These steps
+assume the AWS components meet the :ref:`prerequisites
+`.
+
+Prior to starting these steps, create the following folders:
+
+.. code-block:: shell
+ :class: copyable
+
+ mkdir -P ~/kes/certs ~/kes/config
+
+1) Download the MinIO Key Encryption Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-download-desc
+ :end-before: end-kes-download-desc
+
+2) Generate the TLS Private and Public Key for KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-kes-certs-desc
+ :end-before: end-kes-generate-kes-certs-desc
+
+3) Generate the TLS Private and Public Key for MinIO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-minio-certs-desc
+ :end-before: end-kes-generate-minio-certs-desc
+
+4) Create the KES Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|KES| uses a YAML-formatted configuration file. The following example YAML
+specifies the minimum required fields for enabling |SSE| using AWS Secrets
+Manager:
+
+.. code-block:: shell
+ :class: copyable
+
+ address: 0.0.0.0:7373
+
+ # Disable the root identity, as we do not need that level of access for
+ # supporting SSE operations.
+ root: disabled
+
+ # Specify the TLS keys generated in the previous step here
+ # For production environments, use keys signed by a known and trusted
+ # Certificate Authority (CA).
+ tls:
+ key: /data/certs/server.key
+ cert: /data/certs/server.cert
+
+ # Create a policy named 'minio' that grants access to the
+ # /create, /generate, and /decrypt KES APIs for any key name
+ # KES uses mTLS to grant access to this policy, where only the client
+ # whose TLS certificate hash matches one of the "identities" can
+ # use this policy. Specify the hash of the MinIO server TLS certificate
+ # hash here.
+ policy:
+ minio:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
+
+ # Specify the connection information for the Secrets Manager endpoint.
+ # The endpoint should be resolvable from the host.
+ # This example assumes that the associated GCP account has the necessary
+ # access key and secret key
+ keystore:
+ gcp:
+ secretmanager:
+ project_id: "${GCPPROJECTID}" # The GCP Project to use
+ credentials:
+ client_email: "${GCPCLIENTEMAIL}" # The client email for your GCP Credentials
+ client_id: "${GCPCLIENTID}" # The Client ID for your GCP Credentials
+ private_key_id: "${GCPPRIVATEKEYID}" # the private key ID for your GCP credentials
+ private_key: "${GCPPRIVATEKEY}" # The content of your GCP Private Key
+
+Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
+value ``${VARIABLE}`` uses the environment variable with matching name as the
+value. You can use this functionality to set credentials without writing them to
+the configuration file.
+
+- Set ``MINIO_IDENTITY_HASH`` to the output of
+ ``kes tool identity of minio-kes.cert``.
+
+- Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance
+ KES should use.
+
+- Set ``GCPCLIENTEMAIL``, ``GCPCLIENTID``, ``GCPPRIVATEKEYID``, and
+ ``GCPPRIVATEKEY`` to the credentials associated to the
+ :ref:`GCP Service Account `
+ KES should use when accessing the Secrets Manager service.
+
+1) Start KES
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-run-server-desc
+ :end-before: end-kes-run-server-desc
+
+6) Generate a Cryptographic Key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-key-desc
+ :end-before: end-kes-generate-key-desc
+
+7) Configure MinIO to connect to KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-configure-minio-desc
+ :end-before: end-kes-configure-minio-desc
+
+8) Enable Automatic Server-Side Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS
+
+ The following command enables SSE-KMS on all objects written to the
+ specified bucket:
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+ .. tab-item:: SSE-S3
+
+ The following command enables SSE-S3 on all objects written to the
+ specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
+ key for performing |SSE|.
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-S3 ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+Configuration Reference for GCP Secret Manager Root KMS
+-------------------------------------------------------
+
+The following section describes each of the |KES-git| configuration settings for
+using GCP Secrets Manager as the root Key Management Service
+(KMS) for |SSE|:
+
+.. tab-set::
+
+ .. tab-item:: YAML Overview
+
+ The following YAML describes the minimum required fields for configuring
+ GCP Secret Manager as an external KMS for supporting |SSE|.
+
+ Any field with value ``${VARIABLE}`` uses the environment variable
+ with matching name as the value. You can use this functionality to set
+ credentials without writing them to the configuration file.
+
+ .. code-block:: yaml
+
+ address: 0.0.0.0:7373
+ root: ${ROOT_IDENTITY}
+
+ tls:
+ key: kes-server.key
+ cert: kes-server.cert
+
+ policy:
+ minio-server:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY}
+
+ keys:
+ - name: "minio-encryption-key-alpha"
+ - name: "minio-encryption-key-baker"
+ - name: "minio-encryption-key-charlie"
+
+ keystore:
+ gcp:
+ secretmanager:
+ project_id: "${GCPPROJECTID}"
+ credentials:
+ client_email: "${GCPCLIENTEMAIL}"
+ client_id: "${GCPCLIENTID}"
+ private_key_id: "${GCPPRIVATEKEYID}"
+ private_key: "${GCPPRIVATEKEY}"
+
+ .. tab-item:: Reference
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 30 70
+ :width: 100%
+
+ * - Key
+ - Description
+
+ * - ``address``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-address-desc
+ :end-before: end-kes-conf-address-desc
+
+ * - ``root``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-root-desc
+ :end-before: end-kes-conf-root-desc
+
+ * - ``tls``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-tls-desc
+ :end-before: end-kes-conf-tls-desc
+
+ * - ``policy``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-policy-desc
+ :end-before: end-kes-conf-policy-desc
+
+ * - ``keys``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-keys-desc
+ :end-before: end-kes-conf-keys-desc
+
+ * - ``keystore.gcp.secretmanager``
+ - The configuration for the GCP Secret Manager
+
+ - ``project_id`` - The GCP Project of the Secret Manager instance.
+
+ - ``credentials`` - Replace the ``credentials`` with the
+ credentials for a project user with the
+ :ref:`required permissions `.
diff --git a/source/security/server-side-encryption/configure-minio-kes-hashicorp.rst b/source/security/server-side-encryption/configure-minio-kes-hashicorp.rst
new file mode 100644
index 00000000..774794e5
--- /dev/null
+++ b/source/security/server-side-encryption/configure-minio-kes-hashicorp.rst
@@ -0,0 +1,397 @@
+.. _minio-sse-vault:
+
+===========================================================
+Server-Side Object Encryption with Hashicorp Vault Root KMS
+===========================================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) `
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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 |KES-git| and an
+external root Key Management Service (KMS) for performing secured cryptographic
+operations at scale. The root KMS provides stateful and secured storage of
+External Keys (EK) while |KES| is stateless and derives additional cryptographic
+keys from the root-managed |EK|.
+
+This procedure does the following:
+
+- Configure |KES| to use
+ `Hashicorp Vault `__ as the root |KMS|.
+
+- Configure MinIO to use the |KES| instance for supporting |SSE|.
+
+- Configure automatic bucket-default
+ :ref:`SSE-KMS ` and
+ :ref:`SSE-S3 `.
+
+Prerequisites
+-------------
+
+.. _minio-sse-vault-prereq-vault:
+
+Hashicorp Vault
+~~~~~~~~~~~~~~~
+
+This procedure assumes familiarity with
+`Hashicorp Vault `__. The
+Vault `Quick Start
+`__
+provides a sufficient foundation for the purposes of this procedure.
+
+MinIO specifically requires the following Vault settings or configurations:
+
+- Enable the Vault K/V engine. KES version 0.15.0 and later support both the
+ v1 and v2 engines. This procedure uses the v1 engine.
+
+- For K/V v1, create an access policy ``kes-policy.hcl`` with a configuration
+ similar to the following:
+
+ .. code-block:: shell
+ :class: copyable
+
+ path "kv/*" {
+ capabilities = [ "create", "read", "delete" ]
+ }
+
+ Write the policy to Vault using
+ ``vault policy write kes-policy kes-policy.hcl``.
+
+- For K/V v2, create an access policy ``kes-policy.hcl`` with a configuration
+ similar to the following:
+
+ .. code-block:: shell
+ :class: copyable
+
+ path "kv/data/*" {
+ capabilities = [ "create", "read"]
+
+ path "kv/metadata/*" {
+ capabilities = [ "list", "delete"]
+
+ Write the policy to Vault using
+ ``vault policy write kes-policy kes-policy.hcl``
+
+- Enable Vault AppRole authentication, create an AppRole ID, bind it to
+ the necessary policy, and request both roleID and secret ID.
+
+ .. code-block:: shell
+ :class: copyable
+
+ vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m
+ vault write auth/approle/role/kes-role policies=kes-policy
+ vault read auth/approle/role/kes-role/role-id
+ vault write -f auth/approle/role/kes-role/secret-id
+
+The instructions on this page include configuring and starting Vault for
+supporting development/evaluation of MinIO |SSE|. **DO NOT** use these
+instructions for deploying Vault for any long-term development or production
+environments. Extended development and production environments should defer to
+the `Vault Documentation `__ for specific
+guidance on deployment and configuration.
+
+Network Encryption (TLS)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-network-encryption-desc
+ :end-before: end-kes-network-encryption-desc
+
+Podman Container Manager
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-podman-desc
+ :end-before: end-kes-podman-desc
+
+Enable MinIO Server-Side Encryption with Hashicorp Vault
+--------------------------------------------------------
+
+The following steps deploy |KES-git| configured to use an existing Hashicorp
+Vault deployment as the root KMS for supporting |SSE|. These steps assume the
+Vault deployment meets the :ref:`prerequisites `.
+
+Prior to starting these steps, create the following folders:
+
+.. code-block:: shell
+ :class: copyable
+
+ mkdir -P ~/kes/certs ~/kes/config
+
+1) Download the MinIO Key Encryption Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-download-desc
+ :end-before: end-kes-download-desc
+
+
+2) Generate the TLS Private and Public Key for KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-kes-certs-desc
+ :end-before: end-kes-generate-kes-certs-desc
+
+3) Generate the TLS Private and Public Key for MinIO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-minio-certs-desc
+ :end-before: end-kes-generate-minio-certs-desc
+
+4) Create the KES Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|KES| uses a YAML-formatted configuration file. The following example YAML
+specifies the minimum required fields for enabling |SSE| using Hashicorp Vault:
+
+.. code-block:: shell
+ :class: copyable
+
+ address: 0.0.0.0:7373
+
+ # Disable the root identity, as we do not need that level of access for
+ # supporting SSE operations.
+ root: disabled
+
+ # Specify the TLS keys generated in the previous step here
+ # For production environments, use keys signed by a known and trusted
+ # Certificate Authority (CA).
+ tls:
+ key: /data/certs/server.key
+ cert: /data/certs/server.cert
+
+ # Create a policy named 'minio' that grants access to the
+ # /create, /generate, and /decrypt KES APIs for any key name
+ # KES uses mTLS to grant access to this policy, where only the client
+ # whose TLS certificate hash matches one of the "identities" can
+ # use this policy. Specify the hash of the MinIO server TLS certificate
+ # hash here.
+ policy:
+ minio:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
+
+ # Specify the connection information for the Vault server.
+ # The endpoint should be resolvable from the host.
+ # This example assumes that Vault is configured with an AppRole ID and
+ # Secret for use with KES.
+ keystore:
+ vault:
+ endpoint: https://HOSTNAME:8200
+ approle:
+ id: "${VAULTAPPID}" # Hashicorp Vault AppRole ID
+ secret: "${VAULTAPPSECRET}" # Hashicorp Vault AppRole Secret ID
+ retry: 15s
+ status:
+ ping: 10s
+ # Required if Vault uses certificates signed by an unknown CA,
+ # e.g. self-signed or internal (non-globally trusted).
+ tls:
+ ca: vault-tls.cert
+
+Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
+value ``${VARIABLE}`` uses the environment variable with matching name as the
+value. You can use this functionality to set credentials without writing them to
+the configuration file.
+
+- Set ``MINIO_IDENTITY_HASH`` to the output of
+ ``kes tool identity of minio-kes.cert``.
+
+- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
+
+- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate
+ :ref:`Vault AppRole credentials `.
+
+5) Start KES
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-run-server-desc
+ :end-before: end-kes-run-server-desc
+
+6) Generate a Cryptographic Key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-generate-key-desc
+ :end-before: end-kes-generate-key-desc
+
+You can check the newly created key on the Vault server by running the
+``vault kv list kv/`` command, where ``kv/`` is the path to the vault storing
+|KES|-generated keys.
+
+7) Configure MinIO to connect to KES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-configure-minio-desc
+ :end-before: end-kes-configure-minio-desc
+
+8) Enable Automatic Server-Side Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS
+
+ The following command enables SSE-KMS on all objects written to the
+ specified bucket:
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+ .. tab-item:: SSE-S3
+
+ The following command enables SSE-S3 on all objects written to the
+ specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
+ key for performing |SSE|.
+
+ .. code-block:: shell
+ :class: copyable
+
+ mc mb ALIAS/encryptedbucket
+ mc encrypt set SSE-S3 ALIAS/encryptedbucket
+
+ Replace ``ALIAS`` with the :mc:`alias ` of the MinIO
+ deployment configured in the previous step.
+
+ Write a file to the bucket using :mc:`mc cp` or any S3-compatible
+ SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
+ on the file to confirm the associated encryption metadata.
+
+Configuration Reference for Hashicorp Vault
+-------------------------------------------
+
+The following section describes each of the |KES-git| configuration settings for
+using Hashicorp Vault as the root Key Management Service (KMS) for |SSE|:
+
+.. tab-set::
+
+ .. tab-item:: YAML Overview
+
+ The following YAML describes the minimum required fields for configuring
+ Hashicorp Vault as an external KMS for supporting |SSE|.
+
+ Any field with value ``${VARIABLE}`` uses the environment variable
+ with matching name as the value. You can use this functionality to set
+ credentials without writing them to the configuration file.
+
+ .. code-block:: yaml
+
+ address: 0.0.0.0:7373
+ root: ${ROOT_IDENTITY}
+
+ tls:
+ key: kes-server.key
+ cert: kes-server.cert
+
+ policy:
+ minio-server:
+ allow:
+ - /v1/key/create/*
+ - /v1/key/generate/*
+ - /v1/key/decrypt/*
+ identities:
+ - ${MINIO_IDENTITY}
+
+ keys:
+ - name: "minio-encryption-key-alpha"
+ - name: "minio-encryption-key-baker"
+ - name: "minio-encryption-key-charlie"
+
+ keystore:
+ vault:
+ endpoint: https://vault.example.net:8200
+ approle:
+ id: ${KES_APPROLE_ID}
+ secret: ${KES_APPROLE_SECRET}
+ retry: 15s
+ status:
+ ping: 10s
+ tls:
+ ca: vault-tls.cert
+
+ .. tab-item:: Reference
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 30 70
+ :width: 100%
+
+ * - Key
+ - Description
+
+ * - ``address``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-address-desc
+ :end-before: end-kes-conf-address-desc
+
+ * - ``root``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-root-desc
+ :end-before: end-kes-conf-root-desc
+
+ * - ``tls``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-tls-desc
+ :end-before: end-kes-conf-tls-desc
+
+ * - ``policy``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-policy-desc
+ :end-before: end-kes-conf-policy-desc
+
+ * - ``keys``
+ - .. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-conf-keys-desc
+ :end-before: end-kes-conf-keys-desc
+
+ * - ``keystore.vault``
+ - The configuration for the Hashicorp Vault keystore. The following
+ fields are *required*:
+
+ - ``endpoint`` - The hostname for the vault server(s). The
+ hostname *must* be resolvable by the KES server host.
+
+ - ``approle`` - The `AppRole
+ `__ used by
+ KES for performing authenticated operations against Vault.
+
+ The specified AppRole must have the
+ appropriate :ref:`permissions `
+
+ - ``tls.ca`` - The Certificate Authority used to sign the
+ Vault TLS certificates. Typically required if the Vault
+ server uses self-signed certificates *or* is signed by an unknown
+ CA (internal or non-global).
diff --git a/source/security/server-side-encryption/minio-server-side-encryption.rst b/source/security/server-side-encryption/minio-server-side-encryption.rst
new file mode 100644
index 00000000..e2ab7975
--- /dev/null
+++ b/source/security/server-side-encryption/minio-server-side-encryption.rst
@@ -0,0 +1,198 @@
+.. _minio-sse:
+
+=================================
+Server-Side Encryption of Objects
+=================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management System)`
+
+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-git:`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
+:s3-docs:`AWS Server-Side Encryption ` and
+supports the following encryption strategies:
+
+.. tab-set::
+
+ .. tab-item:: SSE-KMS *Recommended*
+ :sync: sse-kms
+
+ 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.
+
+ 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 :ref:`minio-encryption-sse-kms-quickstart`. For
+ production MinIO deployments, use one of the following guides:
+
+ - :ref:`AWS SecretsManager `
+ - :ref:`Google Cloud SecretManager `
+ - :ref:`Azure Key Vault `
+ - :ref:`Hashicorp KeyVault `
+
+ .. tab-item:: SSE-S3
+ :sync: sse-s3
+
+ 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.
+
+ For a tutorial on enabling SSE-s3 in a local (non-production) MinIO
+ Deployment, see :ref:`minio-encryption-sse-s3-quickstart`. For
+ production MinIO deployments, use one of the following guides:
+
+ - :ref:`AWS SecretsManager `
+ - :ref:`Google Cloud SecretManager `
+ - :ref:`Azure Key Vault `
+ - :ref:`Hashicorp KeyVault `
+
+ .. tab-item:: SSE-C
+ :sync: sse-c
+
+ 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 :ref:`minio-tls`.
+
+.. _minio-encryption-sse-secure-erasure-locking:
+
+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:
+
+- :ref:`SSE-KMS Secure Erasure and Locking
+ `
+
+- :ref:`SSE-S3 Secure Erasure and Locking
+ `
+
+- :ref:`SSE-C Secure Erasure and Locking
+ `
+
+Encryption Internals
+--------------------
+
+.. 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.
+
+.. _minio-encryption-sse-content-encryption:
+
+Content Encryption
+~~~~~~~~~~~~~~~~~~
+
+The MinIO server uses an authenticated encryption scheme
+(:ref:`AEAD `) to en/decrypt and authenticate
+the object content. The AEAD is combined with some state to build a
+**Secure Channel**. A Secure Channel is a cryptographic construction that
+ensures confidentiality and integrity of the processed data. In particular, the
+Secure Channel splits the plaintext content into fixed size chunks and
+en/decrypts each chunk separately using an unique key-nonce combination.
+
+The following text diagram illustrates Secure Channel Construction of an
+encrypted object:
+
+The Secure Channel splits the object content into chunks of a fixed size of
+``65536`` bytes. The last chunk may be smaller to avoid adding additional
+overhead and is treated specially to prevent truncation attacks. The nonce
+value is ``96`` bits long and generated randomly per object / multi-part part.
+The Secure Channel supports plaintexts up to ``65536 * 2^32 = 256 TiB``.
+
+For S3 multi-part operations, each object part is en/decrypted with the Secure
+Channel Construction scheme shown above. For each part, MinIO generates a secret
+key derived from the Object Encryption Key (OEK) and the part number using a
+pseudo-random function (:ref:`PRF `), such that
+``key = PRF(OEK, part_id)``.
+
+.. _minio-encryption-sse-primitives:
+
+Cryptographic Primitives
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The MinIO server uses the following cryptographic primitive implementations:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+ :width: 100%
+
+ * -
+ - Primitives
+
+ * - Pseudo-Random Functions (PRF)
+ - HMAC-SHA-256
+
+ * - :ref:`AEAD `
+ - ``ChaCha20Poly-1305`` by default.
+
+ ``AES-256-GCM`` for x86-64 CPUs with the AES-NI extension.
+
+.. toctree::
+ :titlesonly:
+ :hidden:
+
+ /security/server-side-encryption/configure-minio-kes-hashicorp
+ /security/server-side-encryption/configure-minio-kes-aws
+ /security/server-side-encryption/configure-minio-kes-gcp
+ /security/server-side-encryption/configure-minio-kes-azure
+ /security/server-side-encryption/server-side-encryption-sse-kms
+ /security/server-side-encryption/server-side-encryption-sse-s3
+ /security/server-side-encryption/server-side-encryption-sse-c
diff --git a/source/security/encryption/server-side-encryption-sse-c.rst b/source/security/server-side-encryption/server-side-encryption-sse-c.rst
similarity index 72%
rename from source/security/encryption/server-side-encryption-sse-c.rst
rename to source/security/server-side-encryption/server-side-encryption-sse-c.rst
index 286c4daf..6e9fa8f6 100644
--- a/source/security/encryption/server-side-encryption-sse-c.rst
+++ b/source/security/server-side-encryption/server-side-encryption-sse-c.rst
@@ -1,4 +1,4 @@
-.. _minio-server-side-encryption-sse-c:
+.. _minio-encryption-sse-c:
=======================================================
Server-Side Encryption with Client-Managed Keys (SSE-C)
@@ -10,6 +10,19 @@ Server-Side Encryption with Client-Managed Keys (SSE-C)
:local:
:depth: 2
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
+.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
+.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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 disk. Clients must
@@ -19,27 +32,25 @@ MinIO SSE-C is functionally compatible with Amazon
:s3-docs:`Server-Side Encryption with Customer-Provided Keys
`.
-Requirements
-------------
+.. _minio-encryption-sse-c-erasure-locking:
-MinIO SSE-C requires the client to perform all key creation and storage
-operations.
+Secure Erasure and Locking
+--------------------------
-Install and Configure ``mc`` with Access to the MinIO Cluster
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
-This procedure uses :mc:`mc` for performing operations on the source MinIO
-deployment. Install :mc:`mc` on a machine with network access to the source
-deployment. See the ``mc`` :ref:`Installation Quickstart ` for
-instructions on downloading and installing ``mc``.
+- 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.
-SSE-C Key Requirements
-~~~~~~~~~~~~~~~~~~~~~~
+- 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 SSE-C key *must* be a 256-bit base64-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.
+The scope of a single |EK| depends on the number of write operations
+which specified that |EK| when requesting SSE-C encryption.
Considerations
--------------
@@ -49,17 +60,32 @@ SSE-C is Incompatible with Bucket Replication
SSE-C encrypted objects are not compatible with MinIO
:ref:`bucket replication `. Use
-:ref:`SSE-S3 ` to perform
-replication-compatible object encryption.
+:ref:`SSE-KMS ` or
+:ref:`SSE-S3 ` to ensure encrypted
+objects are compatible with bucket replication.
-SSE-C Overrides SSE-S3
-~~~~~~~~~~~~~~~~~~~~~~
+SSE-C Overrides SSE-S3 and SSE-KMS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Encrypting an object using SSE-C prevents MinIO from applying
-:ref:`SSE-S3 ` encryption to that object.
+:ref:`SSE-KMS ` or
+:ref:`SSE-S3 ` encryption to that object.
-Procedure
----------
+Quickstart
+----------
+
+MinIO SSE-C requires the client to perform all key creation and storage
+operations.
+
+This procedure uses :mc:`mc` for performing operations on the source MinIO
+deployment. Install :mc:`mc` on a machine with network access to the source
+deployment. See the ``mc`` :ref:`Installation Quickstart ` for
+instructions on downloading and installing ``mc``.
+
+The SSE-C key *must* be a 256-bit base64-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.
1) Generate the Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,6 +172,3 @@ arguments for enabling SSE-S3 encryption:
encrypted object and the full path to the
bucket or bucket prefix to which you want to write the SSE-C encrypted
object.
-
-
-
diff --git a/source/security/server-side-encryption/server-side-encryption-sse-kms.rst b/source/security/server-side-encryption/server-side-encryption-sse-kms.rst
new file mode 100644
index 00000000..9c9d69fe
--- /dev/null
+++ b/source/security/server-side-encryption/server-side-encryption-sse-kms.rst
@@ -0,0 +1,332 @@
+.. _minio-encryption-sse-kms:
+
+=====================================================
+Server-Side Encryption with Per-Bucket Keys (SSE-KMS)
+=====================================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
+.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
+.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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-git:`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-KMS en/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-cmd:`mc encrypt set` command:
+
+.. code-block:: shell
+ :class: copyable
+
+ mc encrypt set sse-kms EXTERNALKEY play/mybucket
+
+- Replace ``EXTERNALKEY`` with the name of the |EK| to use for encrypting
+ objects in the bucket.
+
+- Replace ``play/mybucket`` with the :mc-cmd:`alias ` and bucket
+ on which you want to enable automatic SSE-KMS encryption.
+
+MinIO SSE-KMS is functionally compatible with AWS S3
+:s3-docs:`Server-Side Encryption with KMS keys stored in AWS
+` while expanding support to include the
+following KMS providers:
+
+- :ref:`AWS SecretsManager `
+- :ref:`Google Cloud SecretManager `
+- :ref:`Azure Key Vault `
+- :ref:`Hashicorp KeyVault `
+- Thales CipherTrust (formerly Gemalto KeySecure)
+
+.. _minio-encryption-sse-kms-quickstart:
+
+Quickstart
+----------
+
+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):
+
+- :ref:`AWS SecretsManager `
+- :ref:`Google Cloud SecretManager `
+- :ref:`Azure Key Vault `
+- :ref:`Hashicorp KeyVault `
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-play-sandbox-warning
+ :end-before: end-kes-play-sandbox-warning
+
+This procedure requires the following components:
+
+- Install :mc:`mc` on a machine with network access to the source
+ deployment. See the ``mc`` :ref:`Installation Quickstart ` for
+ instructions on downloading and installing ``mc``.
+
+
+- Install :minio-git:`MinIO Key Encryption Service (KES) ` on a machine
+ with internet access. See the ``kes``
+ :minio-git:`Getting Started ` guide for
+ instructions on downloading, installing, and configuring KES.
+
+1) Create an Encryption Key for SSE-KMS Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :minio-git:`kes ` commandline tool to create a new External Key
+(EK) for use with SSE-KMS Encryption.
+
+Issue the following command to retrieve the root
+:minio-git:`identity ` for the KES
+server:
+
+.. code-block:: shell
+ :class: copyable
+
+ 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:
+
+.. code-block:: shell
+ :class: copyable
+
+ export KES_CLIENT_KEY=root.key
+ export KES_CLIENT_CERT=root.cert
+
+.. list-table::
+ :stub-columns: 1
+ :widths: 40 60
+ :width: 100%
+
+ * - ``KES_CLIENT_KEY``
+ - The private key for an :minio-git:`identity
+ ` on the KES server.
+ The identity must grant access to at minimum the ``/v1/create``,
+ ``/v1/generate``, and ``/v1/list`` :minio-git:`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 :minio-git:`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.
+
+Issue the following command to create a new |EK| through
+KES.
+
+.. code-block:: shell
+ :class: copyable
+
+ 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:
+
+.. code-block:: shell
+ :class: copyable
+
+ 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-kms-key
+
+.. list-table::
+ :stub-columns: 1
+ :widths: 30 80
+
+ * - :envvar:`MINIO_KMS_KES_ENDPOINT`
+ - The endpoint for the MinIO ``Play`` KES service.
+
+ * - :envvar:`MINIO_KMS_KES_KEY_FILE`
+ - The private key file corresponding to an
+ :minio-git:`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.
+
+ * - :envvar:`MINIO_KMS_KES_CERT_FILE`
+ - The public certificate file corresponding to an
+ :minio-git:`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.
+
+ * - :envvar:`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 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-cmd:`mc admin service restart` command to restart the deployment.
+
+.. important::
+
+ MinIO restarts *all* :mc:`minio server` processes associated to the
+ deployment at the same time. Applications may experience a brief period of
+ downtime during the restart process.
+
+ Consider scheduling the restart during a maintenance period to minimize
+ interruption of services.
+
+.. code-block:: shell
+ :class: copyable
+
+ mc admin service restart ALIAS
+
+Replace ``ALIAS`` with the :mc:`alias ` of the deployment to
+restart.
+
+4) Configure Automatic Bucket Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :mc-cmd:`mc encrypt set` command to enable automatic SSE-KMS protection
+of all objects written to a specific bucket.
+
+.. code-block:: shell
+ :class: copyable
+
+ mc encrypt set sse-kms my-minio-sse-kms-key ALIAS/BUCKET
+
+- Replace :mc-cmd:`ALIAS ` with the
+ :mc:`alias ` of the MinIO deployment on which you enabled SSE-KMS.
+
+- Replace :mc-cmd:`BUCKET ` 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|
+
+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.
+
+
+.. _minio-encryption-sse-kms-erasure-locking:
+
+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.
+
+.. _minio-encryption-sse-kms-encryption-process:
+
+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:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - 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|. 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| specified to the write operation.
+
+ * - Generate the Data Encryption Key (DEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-dek
+ :end-before: end-sse-dek
+
+ * - Generate the Key Encryption Key (KEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-kek
+ :end-before: end-sse-kek
+
+ * - Generate the Object Encryption Key (OEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-oek
+ :end-before: end-sse-oek
+
+ * - Encrypt the Object
+ - MinIO uses the |OEK| to encrypt the object *prior* to storing the
+ object to disk. 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.
diff --git a/source/security/server-side-encryption/server-side-encryption-sse-s3.rst b/source/security/server-side-encryption/server-side-encryption-sse-s3.rst
new file mode 100644
index 00000000..ab56cd40
--- /dev/null
+++ b/source/security/server-side-encryption/server-side-encryption-sse-s3.rst
@@ -0,0 +1,305 @@
+.. _minio-encryption-sse-s3:
+
+==================================================
+Server-Side Encryption Per-Deployment Key (SSE-S3)
+==================================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+.. |EK| replace:: :abbr:`EK (External Key)`
+.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
+.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
+.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
+.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
+.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
+.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
+
+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-git:`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
+:envvar:`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-cmd:`mc encrypt set` command:
+
+.. code-block:: shell
+ :class: copyable
+
+ mc encrypt set sse-s3 play/mybucket
+
+- Replace ``play/mybucket`` with the :mc-cmd:`alias ` and bucket
+ on which you want to enable automatic SSE-KMS encryption.
+
+MinIO SSE-S3 is functionally compatible with AWS S3
+:s3-docs:`Server-Side Encryption with Amazon S3-Managed Keys
+` while expanding support to include the
+following KMS providers:
+
+- :ref:`AWS SecretsManager `
+- :ref:`Google Cloud SecretManager `
+- :ref:`Azure Key Vault `
+- :ref:`Hashicorp KeyVault `
+- Thales CipherTrust (formerly Gemalto KeySecure)
+
+.. _minio-encryption-sse-s3-quickstart:
+
+Quickstart
+----------
+
+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):
+
+- :ref:`AWS SecretsManager `
+- :ref:`Google Cloud SecretManager `
+- :ref:`Azure Key Vault `
+- :ref:`Hashicorp KeyVault `
+- Thales CipherTrust (formerly Gemalto KeySecure)
+
+.. include:: /includes/common-minio-kes.rst
+ :start-after: start-kes-play-sandbox-warning
+ :end-before: end-kes-play-sandbox-warning
+
+This procedure requires the following components:
+
+- Install :mc:`mc` on a machine with network access to the source
+ deployment. See the ``mc`` :ref:`Installation Quickstart ` for
+ instructions on downloading and installing ``mc``.
+
+
+- Install :minio-git:`MinIO Key Encryption Service (KES) ` on a machine
+ with internet access. See the ``kes``
+ :minio-git:`Getting Started ` guide for
+ instructions on downloading, installing, and configuring KES.
+
+
+1) Create an Encryption Key for SSE-S3 Encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :minio-git:`kes ` commandline tool to create a new External Key
+(EK) for use with SSE-S3 Encryption.
+
+Issue the following command to retrieve the root
+:minio-git:`identity ` for the KES
+server:
+
+.. code-block:: shell
+ :class: copyable
+
+ 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:
+
+.. code-block:: shell
+ :class: copyable
+
+ export KES_CLIENT_KEY=root.key
+ export KES_CLIENT_CERT=root.cert
+
+.. list-table::
+ :stub-columns: 1
+ :widths: 40 60
+ :width: 100%
+
+ * - ``KES_CLIENT_KEY``
+ - The private key for an :minio-git:`identity
+ ` on the KES server.
+ The identity must grant access to at minimum the ``/v1/create``,
+ ``/v1/generate``, and ``/v1/list`` :minio-git:`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 :minio-git:`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.
+
+Issue the following command to create a new |EK| through
+KES:
+
+.. code-block:: shell
+ :class: copyable
+
+ 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:
+
+.. code-block:: shell
+ :class: copyable
+
+ 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
+
+.. list-table::
+ :stub-columns: 1
+ :widths: 30 80
+
+ * - :envvar:`MINIO_KMS_KES_ENDPOINT`
+ - The endpoint for the MinIO ``Play`` KES service.
+
+ * - :envvar:`MINIO_KMS_KES_KEY_FILE`
+ - The private key file corresponding to an
+ :minio-git:`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.
+
+ * - :envvar:`MINIO_KMS_KES_CERT_FILE`
+ - The public certificate file corresponding to an
+ :minio-git:`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.
+
+ * - :envvar:`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.
+
+1) Restart the MinIO Deployment to Enable SSE-S3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You must restart the MinIO deployment to apply the configuration changes.
+Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
+
+.. important::
+
+ MinIO restarts *all* :mc:`minio server` processes associated to the
+ deployment at the same time. Applications may experience a brief period of
+ downtime during the restart process.
+
+ Consider scheduling the restart during a maintenance period to minimize
+ interruption of services.
+
+.. code-block:: shell
+ :class: copyable
+
+ mc admin service restart ALIAS
+
+Replace ``ALIAS`` with the :mc:`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-cmd:`mc encrypt set` command to enable automatic SSE-S3 protection
+of all objects written to a specific bucket.
+
+.. code-block:: shell
+ :class: copyable
+
+ mc encrypt set sse-s3 ALIAS/BUCKET
+
+- Replace :mc-cmd:`ALIAS ` with the
+ :mc:`alias ` of the MinIO deployment on which you enabled SSE-S3.
+
+- Replace :mc-cmd:`BUCKET ` with the full path to the
+ bucket or bucket prefix on which you want to enable automatic SSE-S3.
+
+.. _minio-encryption-sse-s3-erasure-locking:
+
+Secure Erasure and Locking
+--------------------------
+
+SSE-S3 protects objects using an |EK| specified at server startup
+using the :envvar:`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.
+
+.. _minio-encryption-sse-s3-encryption-process:
+
+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:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Stage
+ - Description
+
+ * - SSE-Enabled Write Operation
+ - MinIO receives a write operation requesting SSE-S3 encryption.
+ MinIO uses the key name specified to
+ :envvar:`MINIO_KMS_KES_KEY_NAME` as the External Key (EK).
+
+ * - Generate the Data Encryption Key (DEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-dek
+ :end-before: end-sse-dek
+
+ * - Generate the Key Encryption Key (KEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-kek
+ :end-before: end-sse-kek
+
+ * - Generate the Object Encryption Key (OEK)
+ - .. include:: /includes/common-minio-sse.rst
+ :start-after: start-sse-oek
+ :end-before: end-sse-oek
+
+ * - Encrypt the Object
+ - MinIO uses the |OEK| to encrypt the object *prior* to storing the
+ object to disk. MinIO then encrypts the |OEK| with the |KEK|.
+
+ MinIO stores the encrypted representation of the |OEK| and |DEK| as part
+ of the metadata.