minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

DOCS-311: Complete cleanup of SSE docs

Browse Source 
Fixups per Andreas

More CR fixes

Apply suggestions from code review

Co-authored-by: Andreas Auernhammer <hi@aead.dev>

Final pass
This commit is contained in:
ravindk89
2021-09-21 20:35:16 -04:00
committed by Ravind Kumar
parent 3850b59644
commit 955cd1b03e
18 changed files with 3234 additions and 693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
source/conf.py
View File

@ -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
sphinx_tabs_disable_css_loading = True
rst_prolog = """
.. |podman| replace:: `Podman <https://podman.io/>`__
.. |kes-stable| replace:: 0.16.1
"""

464
source/includes/common-minio-kes.rst Normal file
View File

@ -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" <blob/main/docs/tutorials/rootless_tutorial.md>`.
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 <kes/releases/latest>`.
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
<http://man7.org/linux/man-pages/man2/mlock.2.html>`__ 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
<http://man7.org/linux/man-pages/man2/mlock.2.html>`__ 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 <minio-encryption-sse-kms>` if the request does not
include a specific |EK|.
- Performing :ref:`SSE-S3 <minio-encryption-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 <kes/wiki/Configuration#policy-configuration>` 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.<NAME>.identities`` array
to associate MinIO to the ``<NAME>`` 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

32
source/includes/common-minio-sse.rst Normal file
View File

@ -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) <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 <minio-encryption-sse-primitives>`) 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

21
source/reference/minio-cli/minio-mc/mc-encrypt.rst
View File

@ -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

15
source/reference/minio-server/minio-server.rst
View File

@ -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 <minio-authentication-and-identity-management>`,
server configuration).
- The default encryption key for Server-Side Encryption with
:ref:`SSE-KMS <minio-encryption-sse-kms>`.
- The encryption key for Server-Side Encryption with
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
.. _minio-server-envvar-storage-class:

257
source/security/encryption/encryption-key-management.rst
View File

@ -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) <minio-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 </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 <minio-policy>` for the bucket and object.
MinIO can only decrypt an object if it can retrieve the
:ref:`Customer Master Key (CMK) <minio-encryption-sse-encryption-process>`
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
<UsingServerSideEncryption.html>`. 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 <minio-policy>`
for the bucket and object.
SSE-C encrypted objects are not compatible with MinIO
:ref:`bucket replication <minio-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
<ServerSideEncryptionCustomerKeys.html>`.
.. _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 </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 </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 <minio-encryption-sse-primitives>`) 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 <minio-encryption-sse-primitives>`) 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 <minio-encryption-sse-primitives>`), 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 <minio-encryption-sse-content-encryption>`
- ``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) <minio-encryption-sse-encryption-process>` 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 <minio-encryption-sse-encryption-process>` used to encrypt
that object.
.. _minio-encryption-tls:
Transport Layer Security (TLS)
------------------------------
MinIO supports :ref:`Transport Layer Security (TLS) <minio-TLS>` encryption of
incoming and outgoing traffic.
TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
`deprecated <https://tools.ietf.org/html/rfc7568>`__ as of June 30th, 2018.
MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).
See :ref:`Transport Layer Security (TLS) <minio-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

357
source/security/encryption/server-side-encryption-sse-s3.rst
View File

@ -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 <kes>`. MinIO uses KES
for supporting specific cryptographic operations as part of the
:ref:`encryption process <minio-encryption-sse-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
<UsingServerSideEncryption.html>` 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 <mc-install>` for
instructions on downloading and installing ``mc``.
Install and Configure MinIO KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure uses the
:minio-git:`MinIO Key Encryption Service (KES) <kes>` server and client for
configuring and enabling SSE-S3. See the ``kes``
:minio-git:`Getting Started <kes/wiki/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) <kes/wiki#guides>`. The MinIO
deployment *must* have bidirectional network access to the KES service.
- KES has at least one :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` that grants permission to
at minimum the ``/v1/create``, ``/v1/generate``, and ``/v1/list``
:minio-git:`API endpoints <kes/wiki/Server-API#api-overview>` 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 <kes/blob/master/server-config.yaml#L133>`.
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 <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
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` 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
<kes/wiki/Configuration#policy-configuration>` 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
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`. This step uses the root
identity for the MinIO ``play`` KES sandbox, which provides access
to all operations on the KES server.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
This step uses the root identity for the MinIO ``play`` KES
sandbox, which provides access to all operations on the KES server.
Issue the following command to create a new 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 <kes/wiki/Configuration#policy-configuration>`
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 <kes/wiki/Configuration#policy-configuration>`
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 <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity key file as the ``KES_KEY_FILE`` environment variable
in the previous step.
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
- The public certificate file corresponding to an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity certificate as the ``KES_CERT_FILE`` environment
variable in the previous step.
* - :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 <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 <mc encrypt set TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-S3.
- Replace :mc-cmd:`BUCKET <mc encrypt set TARGET>` 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 <mc encrypt set TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-S3.
- Replace :mc-cmd:`BUCKET <mc encrypt set TARGET>` with the full path to the
bucket or bucket prefix in which you are interacting with the SSE-S3 encrypted
object.

35
source/security/encryption/transport-layer-security.rst
View File

@ -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
<minio/tree/master/docs/tls>`.

281
source/security/network-encryption/minio-tls.rst Normal file
View File

@ -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 <https://tools.ietf.org/html/rfc7568>`__ 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)
<https://en.wikipedia.org/wiki/Server_Name_Indication>`__ 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 <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 <https://cs.opensource.google/go/go/+/refs/tags/go1.17.1:src/crypto/tls/cipher_suites.go;l=52>`__
.. 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) <Elliptic-curve_cryptography>` have
lower computation requirements compared to
:wikI:`RSA <RSA_(cryptosystem)>`. Specifically, MinIO
recommends generating
ECDSA (e.g. `NIST P-256 curve
<https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>`__) 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

56
source/security/security-overview.rst
View File

@ -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) <minio-TLS>` encryption of
incoming and outgoing traffic.
MinIO supports :ref:`Transport Layer Security (TLS) <minio-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 <https://tools.ietf.org/html/rfc7568>`__ 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) <minio-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

382
source/security/server-side-encryption/configure-minio-kes-aws.rst Normal file
View File

@ -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>`
.. |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 <https://aws.amazon.com/secrets-manager/>`__ as the root
|KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-aws-prereq-aws:
AWS Key Management Service
~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`AWS Key Management Service <https://aws.amazon.com/kms/>`__ and
`AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`__.
The `Getting Started with AWS Key Management Service
<https://aws.amazon.com/kms/getting-started/>`__
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 <IAM/latest/UserGuide/id_users_create.html>`
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
<minio-sse-aws-prereq-aws>`.
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 <minio-sse-aws-prereq-aws>`.
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 <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 <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 <minio-sse-aws-prereq-aws>`

355
source/security/server-side-encryption/configure-minio-kes-azure.rst Normal file
View File

@ -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>`
.. |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
<https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__
as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-azure-prereq-azure:
Azure Key Vault
~~~~~~~~~~~~~~~
This procedure assumes familiarity with `Azure Key Vault
<https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__. The
`Key Vault Quickstart
<https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following Azure settings or
configurations:
- `Register an application <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>`__
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 <https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal>`__
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
<minio-sse-azure-prereq-azure>`.
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://<keyvaultinstance>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 <minio-sse-azure-prereq-azure>`.
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 <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 <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://<keyvaultinstance>.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 <minio-sse-azure-prereq-azure>`

353
source/security/server-side-encryption/configure-minio-kes-gcp.rst Normal file
View File

@ -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>`
.. |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
<https://cloud.google.com/secret-manager/>`__ as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-gcp-prereq-gcp:
GCP Secret Manager
~~~~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`GCP Secret Manager <https://cloud.google.com/secret-manager>`__.
The `Secret Manager Quickstart
<https://cloud.google.com/secret-manager/docs/quickstart>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following GCP settings or
configurations:
- `Enable Secret Manager <https://cloud.google.com/secret-manager/docs/configuring-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
<minio-sse-gcp-prereq-gcp>`.
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 <minio-sse-gcp-prereq-gcp>`
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 <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 <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 <minio-sse-gcp-prereq-gcp>`.

397
source/security/server-side-encryption/configure-minio-kes-hashicorp.rst Normal file
View File

@ -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>`
.. |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 <https://www.vaultproject.io/>`__ as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Hashicorp Vault
~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`Hashicorp Vault <https://www.vaultproject.io/>`__. The
Vault `Quick Start
<https://learn.hashicorp.com/tutorials/vault/getting-started-install>`__
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 <https://learn.hashicorp.com/vault>`__ 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 <minio-sse-vault-prereq-vault>`.
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 <minio-sse-vault-prereq-vault>`.
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 <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 <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
<https://www.vaultproject.io/docs/auth/approle>`__ used by
KES for performing authenticated operations against Vault.
The specified AppRole must have the
appropriate :ref:`permissions <minio-sse-vault-prereq-vault>`
- ``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).

198
source/security/server-side-encryption/minio-server-side-encryption.rst Normal file
View File

@ -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) <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 <server-side-encryption.html>` 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 <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
.. 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 <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
.. 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
<minio-encryption-sse-kms-erasure-locking>`
- :ref:`SSE-S3 Secure Erasure and Locking
<minio-encryption-sse-s3-erasure-locking>`
- :ref:`SSE-C Secure Erasure and Locking
<minio-encryption-sse-c-erasure-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 <minio-encryption-sse-primitives>`) 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 <minio-encryption-sse-primitives>`), 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 <minio-encryption-sse-content-encryption>`
- ``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

77
source/security/encryption/server-side-encryption-sse-c.rst → source/security/server-side-encryption/server-side-encryption-sse-c.rst
View File

@ -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
<ServerSideEncryptionCustomerKeys.html>`.
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 <mc-install>` 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 <minio-bucket-replication>`. Use
:ref:`SSE-S3 <minio-server-side-encryption-sse-s3>` to perform
replication-compatible object encryption.
:ref:`SSE-KMS <minio-encryption-sse-kms>` or
:ref:`SSE-S3 <minio-encryption-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 <minio-server-side-encryption-sse-s3>` encryption to that object.
:ref:`SSE-KMS <minio-encryption-sse-kms>` or
:ref:`SSE-S3 <minio-encryption-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 <mc-install>` 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.

332
source/security/server-side-encryption/server-side-encryption-sse-kms.rst Normal file
View File

@ -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) <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 <mc 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
<UsingKMSEncryption.html>` while expanding support to include the
following KMS providers:
- :ref:`AWS SecretsManager <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
- 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 <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
.. 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 <mc-install>` for
instructions on downloading and installing ``mc``.
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
with internet access. See the ``kes``
:minio-git:`Getting Started <kes/wiki/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 <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 <kes/wiki/Configuration#policy-configuration>` 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
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`. This step uses the root
identity for the MinIO ``play`` KES sandbox, which provides access
to all operations on the KES server.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
This step uses the root identity for the MinIO ``play`` KES
sandbox, which provides access to all operations on the KES server.
Issue the following command to create a new |EK| 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 <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity key file as the ``KES_KEY_FILE`` environment variable
in the previous step.
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
- The public certificate file corresponding to an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity certificate as the ``KES_CERT_FILE`` environment
variable in the previous step.
* - :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 <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 <mc encrypt set TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-KMS.
- Replace :mc-cmd:`BUCKET <mc encrypt set TARGET>` 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.

305
source/security/server-side-encryption/server-side-encryption-sse-s3.rst Normal file
View File

@ -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) <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 <mc 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
<UsingServerSideEncryption.html>` while expanding support to include the
following KMS providers:
- :ref:`AWS SecretsManager <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
- 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 <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
- 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 <mc-install>` for
instructions on downloading and installing ``mc``.
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
with internet access. See the ``kes``
:minio-git:`Getting Started <kes/wiki/Getting-Started>` guide for
instructions on downloading, installing, and configuring KES.
1) Create an Encryption Key for SSE-S3 Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :minio-git:`kes <kes>` commandline tool to create a new External Key
(EK) for use with SSE-S3 Encryption.
Issue the following command to retrieve the root
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>` 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
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`. This step uses the root
identity for the MinIO ``play`` KES sandbox, which provides access
to all operations on the KES server.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
This step uses the root identity for the MinIO ``play`` KES
sandbox, which provides access to all operations on the KES server.
Issue the following command to create a new |EK| 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 <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity key file as the ``KES_KEY_FILE`` environment variable
in the previous step.
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
- The public certificate file corresponding to an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity certificate as the ``KES_CERT_FILE`` environment
variable in the previous step.
* - :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 <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 <mc encrypt set TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-S3.
- Replace :mc-cmd:`BUCKET <mc encrypt set TARGET>` 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.