minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-06-04 08:42:23 +03:00
Code

Completion of SSE-KMS doc rewrite (#539)

Browse Source
This commit is contained in:
Ravind Kumar 2022-09-06 17:38:08 -04:00 committed by GitHub
parent fc85a37c70
commit 40cd778e5b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
44 changed files with 3325 additions and 1568 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
source/administration/server-side-encryption/server-side-encryption-sse-kms.rst
View File

@ -76,7 +76,7 @@ supported external Key Management Services (KMS):
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
.. include:: /includes/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-play-sandbox-warning
:end-before: end-kes-play-sandbox-warning

2
source/administration/server-side-encryption/server-side-encryption-sse-s3.rst
View File

@ -73,7 +73,7 @@ supported external Key Management Services (KMS):
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
- Thales CipherTrust (formerly Gemalto KeySecure)
.. include:: /includes/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-play-sandbox-warning
:end-before: end-kes-play-sandbox-warning

5
source/default-conf.py
View File

@ -47,7 +47,6 @@ extensions = [
'minio',
'cond',
'sphinx_copybutton',
'sphinx_markdown_tables',
'sphinx-prompt',
'sphinx_substitution_extensions',
'sphinx_togglebutton',
@ -247,7 +246,7 @@ html_theme_options = {
'show_relbars': 'false'
}
html_short_title = "MinIO Object Storage for " + platform.capitalize()
html_short_title = "MinIO Object Storage for " + ("MacOS" if platform == "macos" else platform.capitalize())
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
@ -260,7 +259,7 @@ html_js_files = ['js/main.js']
html_extra_path = [ 'extra']
html_title = 'MinIO Object Storage for ' + platform.capitalize()
html_title = 'MinIO Object Storage for ' + ("MacOS" if platform == "macos" else platform.capitalize())
html_context = {
'doc_platform': platform.lower()

451
source/includes/common-minio-kes.rst
View File

@ -1,451 +0,0 @@
.. 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-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_CERT_FILE=~/minio-kes.cert
export MINIO_KMS_KES_KEY_FILE=~/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

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

@ -0,0 +1,127 @@
.. start-kes-configuration-aws-desc
|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
:substitutions:
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: |kesconfigcertpath|kes-server.key
cert: |kesconfigcertpath|kes-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'
# In production environments, each client connecting to KES must
# Have their TLS hash listed under at least one `policy`.
# 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:
aws:
secretsmanager:
endpoint: secretsmanager.REGION.amazonaws.com # 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
.. end-kes-configuration-aws-desc
.. start-kes-configuration-aws-container-desc
|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
:substitutions:
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: /certs/server.key
cert: /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:
aws:
secretsmanager:
endpoint: secretsmanager.REGION.amazonaws.com # 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 ``|path|/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>`.
.. end-kes-configuration-aws-container-desc

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

@ -0,0 +1,54 @@
.. start-kes-configuration-azure-desc
|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
:substitutions:
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: |kesconfigcertpath|kes-server.key
cert: |kesconfigcertpath|kes-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
.. end-kes-configuration-azure-desc

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

@ -0,0 +1,54 @@
.. start-kes-configuration-gcp-desc
|KES| uses a YAML-formatted configuration file. The following example YAML
specifies the minimum required fields for enabling |SSE| using GCP Secrets
Manager:
.. code-block:: shell
:class: copyable
:substitutions:
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: |kesconfigcertpath|kes-server.key
cert: |kesconfigcertpath|kes-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
.. end-kes-configuration-gcp-desc

56
source/includes/common/common-minio-kes-hashicorp.rst
View File

@ -5,6 +5,7 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
.. code-block:: shell
:class: copyable
:substitutions:
address: 0.0.0.0:7373
@ -16,8 +17,8 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
# For production environments, use keys signed by a known and trusted
# Certificate Authority (CA).
tls:
key: ~/minio-kes-vault/certs/kes-server.key
cert: ~/minio-kes-vault/certs/kes-server.cert
key: |kesconfigcertpath|kes-server.key
cert: |kesconfigcertpath|kes-server.cert
# Sets access policies for KES
# The `minio` policy grants access to the listed APIs.
@ -53,61 +54,12 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
.. end-kes-configuration-hashicorp-vault-desc
.. start-kes-prereq-hashicorp-vault-desc
This procedure assumes an existing `Hashicorp Vault <https://www.vaultproject.io/>`__ installation accessible from the local host.
The Vault `Quick Start <https://learn.hashicorp.com/tutorials/vault/getting-started-install>`__ provides a sufficient foundation for the purposes of this procedure.
Defer to the `Vault Documentation <https://learn.hashicorp.com/vault>`__ for guidance on deployment and configuration.
MinIO |KES| supports both the V1 and V2 Vault engines.
Select the corresponding tab to the engine used by your Vault deployment for instructions on configuring the necessary permissions:
.. tab-set::
.. tab-item:: Vault Engine 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``.
.. tab-item:: Vault Engine 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``
MinIO requires using AppRole authentication for secure communication with the Vault server.
The following commands:
- Create an App Role ID for |KES|
- Binds that role to the created KES policy
- Requests a RoleID and SecretID
.. 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
You must specify both RoleID and SecretID as part of this procedure.
.. end-kes-prereq-hashicorp-vault-desc

80
source/includes/common/common-minio-kes.rst
View File

@ -1,10 +1,5 @@
.. 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
.. The following sections are common among all KES-related tutorials
.. Use the /includes/<platform>/common-minio-kes.rst file for platform-specific overrides.
.. start-kes-encrypted-backend-desc
@ -48,53 +43,68 @@ The following commands create two TLS certificates that expire within 30 days of
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity new \
--key ~/minio-kes-vault/certs/kes-server.key \
--cert ~/minio-kes-vault/certs/kes-server.cert \
--ip "127.0.0.1" \
# These commands output keys to |kescertpath|
# and |miniocertpath| respectively
kes tool identity new \
--key |kescertpath|/kes-server.key \
--cert |kescertpath|/kes-server.cert \
--ip "127.0.0.1" \
--dns localhost
kes tool identity new \
--key ~/minio-kes-vault/certs/minio-kes.key \
--cert ~/minio-kes-vault/certs/minio-kes.cert \
--ip "127.0.0.1" \
kes tool identity new \
--key |miniocertpath|/minio-kes.key \
--cert |miniocertpath|/minio-kes.cert \
--ip "127.0.0.1" \
--dns localhost
These commands output the keys to the ``~/minio-kes-vault/certs`` directory on the host operating system.
The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate.
The above example assumes that all components (Vault, MinIO, and KES) deploy on the same local host machine accessible via ``localhost`` or ``127.0.0.1``.
You can specify additional IP or Hostnames based on the network configuration of your local host.
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` certificate as a trusted Certificate Authority. See the `Hashicorp Server Configuration Documentation <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
.. end-kes-generate-kes-certs-desc
.. start-kes-run-server-desc
.. start-kes-minio-start-server-desc
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.
Run the following command in a terminal or shell to start the MinIO server as a foreground process.
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.
Using self-signed certificates for either the MinIO client or the root KMS server requires specifing this option.
.. code-block:: shell
:class: copyable
:substitutions:
export MINIO_CONFIG_ENV_FILE=|minioconfigpath|/minio
minio server --console-address :9090
.. end-kes-minio-start-server-desc
.. start-kes-start-server-desc
Run the following commands in a terminal or shell to start the KES server as a foreground process:
.. code-block:: shell
:class: copyable
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
kes server --mlock \
--config=~/minio-kes-vault/config/server-config.yaml \
kes server --mlock \
--config=|kesconfigpath|kes-config.yaml \
--auth=off
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.
Using self-signed certificates for either the MinIO client or the root KMS server requires specifying this option.
|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 method's associated logging system (e.g. ``nohup.txt``).
.. end-kes-run-server-desc
.. end-kes-start-server-desc
.. start-kes-generate-key-desc
@ -105,10 +115,11 @@ The following command uses the ``kes key create`` command to add a new External
.. code-block:: shell
:class: copyable
:substitutions:
export KES_SERVER=https://127.0.0.1:7373
export KES_CLIENT_KEY=~/minio-kes-vault/minio-kes.key
export KES_CLIENT_CERT=~/minio-kes-vault/minio-kes.cert
export KES_CLIENT_KEY=|miniocertpath|/minio-kes.key
export KES_CLIENT_CERT=|miniocertpath|/minio-kes.cert
kes key create -k encrypted-bucket-key
@ -123,13 +134,14 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server
.. code-block:: shell
:class: copyable
:substitutions:
# Add these environment variables to the existing environment file
MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
MINIO_KMS_KES_CERT_FILE=~/minio-kes-vault/certs/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=~/minio-kes-vault/certs/minio-kes.key
MINIO_KMS_KES_CAPATH=~/minio-kes-vault/certs/kes-server.cert
MINIO_KMS_KES_CERT_FILE=|miniocertpath|/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=|miniocertpath|/minio-kes.key
MINIO_KMS_KES_CAPATH=|miniocertpath|/kes-server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
minio server [ARGUMENTS]

153
source/includes/container/common-minio-kes.rst
View File

@ -3,36 +3,36 @@
The commands in this section create the following resources:
- A Podman :podman-docs:`Pod <markdown/podman-pod.1.html>` to facilitate container communications
- A Container for the KES Server configured to use Hashicorp Vault as the Root |KMS|.
- A Container for the KES Server configured to use |rootkms| as the Root |KMS|.
- A Container for a MinIO Server running in :ref:`Single-Node Single-Drive Mode <minio-snsd>`.
.. code-block:: shell
:class: copyable
:substitutions:
sudo podman pod create \
-p 9000:9000 -p 9090:9090 -p 7373:7373 \
-v ~/minio-kes-vault/certs:/certs \
-v ~/minio-kes-vault/minio:/mnt/minio \
-v ~/minio-kes-vault/config:/etc/default/ \
-n minio-kes-vault
sudo podman pod create \
-p 9000:9000 -p 9090:9090 -p 7373:7373 \
-v |kescertpath|:/certs \
-v |miniodatapath|:/mnt/minio \
-v |kesconfigpath|:/etc/default/ \
-n |namespace|
sudo podman run -dt \
--cap-add IPC_LOCK \
--name kes-server \
--pod "minio-kes-vault" \
-e KES_SERVER=https://127.0.0.1:7373 \
-e KES_CLIENT_KEY=/certs/kes-server.key \
-e KES_CLIENT_CERT=/certs/kes-server.cert \
quay.io/minio/kes:|kes-stable| server \
--mlock --auth \
--config=/etc/default/kes-server-config.yaml \
sudo podman run -dt \
--cap-add IPC_LOCK \
--name kes-server \
--pod "|namespace|" \
-e KES_SERVER=https://127.0.0.1:7373 \
-e KES_CLIENT_KEY=/certs/kes-server.key \
-e KES_CLIENT_CERT=/certs/kes-server.cert \
quay.io/minio/kes:|kes-stable| server \
--mlock --auth \
--config=/etc/default/kes-config.yaml \
sudo podman run -dt \
--name minio-server \
--pod "minio-kes-vault" \
sudo podman run -dt \
--name minio-server \
--pod "|namespace|" \
-e "MINIO_CONFIG_ENV_FILE=/etc/default/minio" \
quay.io/minio/minio:|minio-latest| server \
quay.io/minio/minio:|minio-latest| server \
--console-address ":9090"
You can verify the status of the containers using the following commands:
@ -51,7 +51,7 @@ If all pods are operational, you can connect to the MinIO deployment by opening
The following commands create two TLS certificates that expire within 30 days of creation:
- A TLS certificate for KES to secure communications between it and the Vault deployment
- A TLS certificate for KES to secure communications between it and the |rootkms| service.
- A TLS certificate for MinIO to perform mTLS authentication to KES.
.. admonition:: Use Caution in Production Environments
@ -69,33 +69,27 @@ The following commands create two TLS certificates that expire within 30 days of
:class: copyable
:substitutions:
podman run --rm \
-v ~/minio-kes-vault/certs:/certs \
quay.io/minio/kes:|kes-stable| identity new \
--key /certs/kes-server.key \
--cert /certs/kes-server.cert \
# These commands output keys to |kescertpath| and |miniocertpath| on the host operating system
podman run --rm \
-v |kescertpath|:/certs \
quay.io/minio/kes:|kes-stable| identity new \
--key /certs/kes-server.key \
--cert /certs/kes-server.cert \
kes-server
podman run --rm \
-v ~/minio-kes-vault/certs:/certs \
quay.io/minio/kes:|kes-stable| identity new \
--key /certs/minio-kes.key \
--cert /certs/minio-kes.cert \
podman run --rm \
-v |miniocertpath|:/certs \
quay.io/minio/kes:|kes-stable| identity new \
--key /certs/minio-kes.key \
--cert /certs/minio-kes.cert \
minio-server
These commands output the keys to the ``~/minio-kes-vault/certs`` directory on the host operating system.
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
.. end-kes-generate-kes-certs-desc
.. start-kes-configuration-minio-desc
Create the MinIO Environment file at ``~/minio-kes-vault/config/minio``.
See the tutorial for :ref:`minio-snsd` for more detailed descriptions of a base MinIO environment file.
This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server.cert`` certificates are accessible at the specified location:
.. code-block:: shell
@ -108,9 +102,9 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server
# KES Configurations
MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
MINIO_KMS_KES_CERT_FILE=~/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=~/minio-kes.key
MINIO_KMS_KES_CAPATH=~/server.cert
MINIO_KMS_KES_CERT_FILE=/certs/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=/certs/minio-kes.key
MINIO_KMS_KES_CAPATH=/certs/server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations:
@ -127,70 +121,6 @@ KES automatically creates this key if it does not already exist on the root KMS.
.. end-kes-configuration-minio-desc
.. start-kes-run-server-vault-desc
The following commands do the following:
- Create a Pod for the MinIO and KES containers
- Start the KES Container attached to the Pod
- Start the MinIO Container attached to the Pod
The commands include setting an environment variable for the Vault :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
These values automatically substitute into the configuration file when running the container.
All commands assume starting the container in "Rootfull" mode.
"Rootless" configurations may work depending on your local host configuration.
.. code-block:: shell
:class: copyable
:substitutions:
# Creates the Pod named 'minio-kes-vault'
# Exposes ports for MinIO, KES, and Vault for all containers attached to the pod
# Attaches local host volumes to any container in the Pod at the specified paths
sudo podman pod create \
-p 9000:9000 -p 9090:9090 -p 7373:7373 -p 8200:8200 \
-v ~/pods/minio-sse-local/minio:/mnt/data \
-v ~/pods/minio-sse-local/certs:/certs \
-v ~/pods/minio-sse-local/keys:/keys \
-v ~/pods/minio-sse-local/config:/etc/default \
-n minio-kes-vault
# Runs the KES container attached to the `minio-kes-vault` Pod
# Sets environment variables to allow accessing the KES server using the container KES client
# Disables verification of TLS certificates to allow using self-signed client certs
# Enables ``mlock`` system call for better security
# Disables verification of client TLS certificates to support self-signed certs
sudo podman run -t \
--cap-add IPC_LOCK \
--name kes-server \
--pod "minio-kes-vault" \
-e KES_SERVER=https://127.0.0.1:7373 \
-e KES_CLIENT_KEY=/certs/minio-kes.key \
-e KES_CLIENT_CERT=/certs/minio-kes.cert \
-e VAULTAPPID="vault-app-id" \
-e VAULTAPPSECRET="vault-app-secret" \
kes:|kes-stable| server \
--mlock \
--config=/etc/default/kes-server-config.yaml \
--auth=off
# Runs the MinIO container attached to the `minio-kes-vault` Pod
# Sets an environment variable pointing to the MinIO Environment file
# Starts the server with a dedicated console port of ``9090``
sudo podman run -t \
-e "MINIO_CONFIG_ENV_FILE=/etc/default/minio" \
--name "minio" \
--pod "minio-kes-vault" \
minio:|minio-latest| server --console-address ":9090"
You can verify the installation by opening your Internet Browser and navigating to http://127.0.0.1:9090 and logging in with your MinIO Root Credentials.
.. end-kes-run-server-vault-desc
.. start-kes-generate-key-desc
MinIO requires that the |EK| exist on the root KMS *before* performing
@ -205,10 +135,11 @@ the MinIO backend.
:class: copyable
:substitutions:
sudo podman run --rm \
-e KES_SERVER=https://127.0.0.1:7373 \
-e KES_CLIENT_KEY=~/minio-kes-vault/certs/minio-kes.key \
-e KES_CLIENT_CERT=~/minio-kes-vault/certs/minio-kes.cert \
sudo podman run --rm \
-v |kescertpath|:/certs \
-e KES_SERVER=https://127.0.0.1:7373 \
-e KES_CLIENT_KEY=/certs/minio-kes.key \
-e KES_CLIENT_CERT=/certs/minio-kes.cert \
kes:|kes-stable| key create -k my-new-encryption-key
You can specify any key name as appropriate for your use case, such as a bucket-specific key ``minio-mydata-key``.

140
source/includes/container/steps-configure-minio-kes-aws.rst Normal file
View File

@ -0,0 +1,140 @@
(Podman) Deploy MinIO and KES with Server-Side Encryption using AWS Secrets Manager
-----------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\minio-kes-vault\``.
1) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
2) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-aws.rst
:start-after: start-kes-configuration-aws-desc
:end-before: end-kes-configuration-aws-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
podman run --rm \
-v |kescertpath|/certs:/certs \
kes:|kes-stable| tool identity of /certs/minio-kes.cert
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
podman run --rm \
-v |kescertpath|/certs:/certs \
kes:|kes-stable| tool identity of /certs/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
3) Create Pod and Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-common-deploy-create-pod-and-containers
:end-before: end-common-deploy-create-pod-and-containers
4) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
5) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use either the MinIO Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
.. tab-set::
.. tab-item:: MinIO Console
Open the MinIO Console by navigating to http://127.0.0.1:9090 in your preferred browser and logging in with the root credentials specified to the MinIO container.
Once logged in, create a new Bucket and name it to your preference.
Select the Gear :octicon:`gear` icon to open the management view.
Select the pencil :octicon:`pencil` icon next to the :guilabel:`Encryption` field to open the modal for configuring a bucket default SSE scheme.
Select :guilabel:`SSE-KMS`, then enter the name of the key created in the previous step.
Once you save your changes, try to upload a file to the bucket.
When viewing that file in the object browser, note that in the sidebar the metadata includes the SSE encryption scheme and information on the key used to encrypt that object.
This indicates the successful encrypted state of the object.
.. tab-item:: MinIO CLI
The following commands:
- Create a new :ref:`alias <alias>` for the MinIO deployment
- Create a new bucket for storing encrypted data
- Enable SSE-KMS encryption on that bucket
.. code-block:: shell
:class: copyable
mc alias set local http://127.0.0.1:9000 ROOTUSER ROOTPASSWORD
mc mb local/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
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.

124
source/includes/container/steps-configure-minio-kes-azure.rst Normal file
View File

@ -0,0 +1,124 @@
(Podman) Deploy MinIO and KES with Server-Side Encryption using Azure Key Vault
-------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\minio-kes-vault\``.
1) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
2) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-azure.rst
:start-after: start-kes-configuration-azure-desc
:end-before: end-kes-configuration-azure-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
podman run --rm \
-v |kescertpath|/certs:/certs \
kes:|kes-stable| tool identity of /certs/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
3) Create Pod and Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-common-deploy-create-pod-and-containers
:end-before: end-common-deploy-create-pod-and-containers
4) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
5) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use either the MinIO Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
.. tab-set::
.. tab-item:: MinIO Console
Open the MinIO Console by navigating to http://127.0.0.1:9090 in your preferred browser and logging in with the root credentials specified to the MinIO container.
Once logged in, create a new Bucket and name it to your preference.
Select the Gear :octicon:`gear` icon to open the management view.
Select the pencil :octicon:`pencil` icon next to the :guilabel:`Encryption` field to open the modal for configuring a bucket default SSE scheme.
Select :guilabel:`SSE-KMS`, then enter the name of the key created in the previous step.
Once you save your changes, try to upload a file to the bucket.
When viewing that file in the object browser, note that in the sidebar the metadata includes the SSE encryption scheme and information on the key used to encrypt that object.
This indicates the successful encrypted state of the object.
.. tab-item:: MinIO CLI
The following commands:
- Create a new :ref:`alias <alias>` for the MinIO deployment
- Create a new bucket for storing encrypted data
- Enable SSE-KMS encryption on that bucket
.. code-block:: shell
:class: copyable
mc alias set local http://127.0.0.1:9000 ROOTUSER ROOTPASSWORD
mc mb local/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
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.

127
source/includes/container/steps-configure-minio-kes-gcp.rst Normal file
View File

@ -0,0 +1,127 @@
(Podman) Deploy MinIO and KES with Server-Side Encryption using GCP Secrets Manager
-----------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\minio-kes-vault\``.
1) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
2) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
podman run --rm \
-v |kescertpath|/certs:/certs \
kes:|kes-stable| tool identity of /certs/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
3) Create Pod and Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-common-deploy-create-pod-and-containers
:end-before: end-common-deploy-create-pod-and-containers
4) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
5) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use either the MinIO Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
.. tab-set::
.. tab-item:: MinIO Console
Open the MinIO Console by navigating to http://127.0.0.1:9090 in your preferred browser and logging in with the root credentials specified to the MinIO container.
Once logged in, create a new Bucket and name it to your preference.
Select the Gear :octicon:`gear` icon to open the management view.
Select the pencil :octicon:`pencil` icon next to the :guilabel:`Encryption` field to open the modal for configuring a bucket default SSE scheme.
Select :guilabel:`SSE-KMS`, then enter the name of the key created in the previous step.
Once you save your changes, try to upload a file to the bucket.
When viewing that file in the object browser, note that in the sidebar the metadata includes the SSE encryption scheme and information on the key used to encrypt that object.
This indicates the successful encrypted state of the object.
.. tab-item:: MinIO CLI
The following commands:
- Create a new :ref:`alias <alias>` for the MinIO deployment
- Create a new bucket for storing encrypted data
- Enable SSE-KMS encryption on that bucket
.. code-block:: shell
:class: copyable
mc alias set local http://127.0.0.1:9000 ROOTUSER ROOTPASSWORD
mc mb local/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
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.

84
source/includes/container/steps-configure-minio-kes-hashicorp.rst
View File

@ -1,52 +1,15 @@
This procedure assumes a single local host machine running the MinIO and KES processes as containers.
As part of this procedure, you will:
- Deploy a |KES| container configured to use `Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
- Create a new |EK| on Vault for use with |SSE|.
- Deploy a MinIO container configured to use the |KES| container for supporting |SSE|.
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
You can use the guidance in this tutorial for deploying MinIO with |SSE| enabled for other container-based topologies.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
Install Podman or a Similar Container Management Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-deploy.rst
:start-after: start-common-prereq-container-management-interface
:end-before: end-common-prereq-container-management-interface
Use Podman to Deploy MinIO and KES with Hashicorp Vault for SSE
---------------------------------------------------------------
(Podman) Deploy MinIO and KES with Server-Side Encryption using Hashicorp Key Vault
-----------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P ~/minio-kes-vault/certs ~/minio-kes-vault/minio ~/minio-kes-vault/config
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\minio-kes-vault\``.
@ -58,37 +21,52 @@ For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\mini
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
2) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
Save the configuration file as ``~/minio-kes-vault/config/kes-config.yaml``.
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
.. code-block:: shell
:class: copyable
:substitutions:
podman run --rm \
-v ~/minio-kes-vault/certs:/certs \
kes:v|kes-stable| tool identity of /certs/minio-kes.cert
podman run --rm \
-v |kescertpath|/certs:/certs \
kes:|kes-stable| tool identity of /certs/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/container/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc

52
source/includes/k8s/common-minio-kes.rst
View File

@ -8,61 +8,11 @@ This procedure assumes an existing `Hashicorp Vault <https://www.vaultproject.io
Defer to the `Vault Documentation <https://learn.hashicorp.com/vault>`__ for guidance on deployment and configuration.
MinIO |KES| supports both the V1 and V2 Vault engines.
Select the corresponding tab to the engine used by your Vault deployment for instructions on configuring the necessary permissions:
.. tab-set::
.. tab-item:: Vault Engine 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``.
.. tab-item:: Vault Engine 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``
MinIO requires using AppRole authentication for secure communication with the Vault server.
The following commands:
- Create an App Role ID for |KES|
- Binds that role to the created KES policy
- Requests a RoleID and SecretID
.. 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
You must specify both RoleID and SecretID as part of this procedure.
.. end-kes-prereq-hashicorp-vault-desc
.. start-kes-enable-sse-kms-desc
You can use either the MinIO Tennat Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
You can use either the MinIO Tenant Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
.. tab-set::

89
source/includes/k8s/steps-configure-minio-kes-aws.rst Normal file
View File

@ -0,0 +1,89 @@
Deploy MinIO Tenant with Server-Side Encryption using AWS SecretsManager
------------------------------------------------------------------------
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO Operator Console:
.. code-block:: shell
:class: copyable
kubectl minio proxy
The command returns output similar to the following:
.. code-block:: shell
Starting port forward of the Console UI.
To connect open a browser and go to http://localhost:9090
Current JWT to login: TOKEN
Open your browser to the specified URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
2) Complete the :guilabel:`Encryption` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reference the :ref:`Deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` procedure for complete documentation of other Tenant settings.
To enable |SSE| with AWS Key Management Service during Tenant deployment, select the :guilabel:`Encryption` section and toggle the switch to :guilabel:`Enabled`.
You can then change the :guilabel:`Vault` Radio button to :guilabel:`AWS` to display the configuration settings.
.. image:: /images/k8s/operator-create-tenant-encryption-aws.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - Encryption Section - AWS Key Management Service
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Field
- Description
* - | Endpoint
| Region
- The hostname and AWS region for the AWS Secrets Manager instance (``https://secretmanager.us-east-2.amazonaws.com`` and ``us-east-2``) to use for |SSE|.
The MinIO Tenant |KES| pods *must* have network access to the specified endpoint.
This procedure assumes that your Kubernetes network configuration supports routing internal traffic to external networks like the public internet.
* - | Access Key
| Secret Key
| Token
- Specify the AWS User Access Key and Secret Key MinIO should use when authenticating to the Vault service.
Review the :ref:`AWS Prerequisites <minio-sse-aws-prereq-aws>` for instructions on generating these values.
Once you have completed the AWS |KMS| configuration, you can finish any remaining sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
3) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
4) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

87
source/includes/k8s/steps-configure-minio-kes-azure.rst Normal file
View File

@ -0,0 +1,87 @@
Deploy MinIO Tenant with Server-Side Encryption using Azure Key Vault
---------------------------------------------------------------------
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO Operator Console:
.. code-block:: shell
:class: copyable
kubectl minio proxy
The command returns output similar to the following:
.. code-block:: shell
Starting port forward of the Console UI.
To connect open a browser and go to http://localhost:9090
Current JWT to login: TOKEN
Open your browser to the specified URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
2) Complete the :guilabel:`Encryption` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reference the :ref:`Deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` procedure for complete documentation of other Tenant settings.
To enable |SSE| with |rootkms-short| during Tenant deployment, select the :guilabel:`Encryption` section and toggle the switch to :guilabel:`Enabled`.
You can then select the :guilabel:`Azure` Radio button to display the |rootkms-short| configuration settings.
.. image:: /images/k8s/operator-create-tenant-encryption-azure.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - Encryption Section
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Field
- Description
* - Endpoint
- The hostname or IP address for the |rootkms-short| service to use for |SSE|.
The MinIO Tenant |KES| pods *must* have network access to the specified endpoint.
* - | Tenant ID
| Client ID
| Client Secret
- Specify the |rootkms-short| credentials the MinIO Tenant should use when authenticating to the service.
Review the :ref:`Azure Prerequisites <minio-sse-azure-prereq-azure>` for instructions on generating these values.
Once you have completed the |rootkms-short| configuration, you can finish any remaining sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
3) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
4) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

89
source/includes/k8s/steps-configure-minio-kes-gcp.rst Normal file
View File

@ -0,0 +1,89 @@
Deploy MinIO Tenant with Server-Side Encryption using GCP Secret Manager
------------------------------------------------------------------------
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO Operator Console:
.. code-block:: shell
:class: copyable
kubectl minio proxy
The command returns output similar to the following:
.. code-block:: shell
Starting port forward of the Console UI.
To connect open a browser and go to http://localhost:9090
Current JWT to login: TOKEN
Open your browser to the specified URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
2) Complete the :guilabel:`Encryption` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reference the :ref:`Deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` procedure for complete documentation of other Tenant settings.
To enable |SSE| with |rootkms-short| during Tenant deployment, select the :guilabel:`Encryption` section and toggle the switch to :guilabel:`Enabled`.
You can then select the :guilabel:`GCP` Radio button to display the |rootkms-short| configuration settings.
.. image:: /images/k8s/operator-create-tenant-encryption-gcp.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - Encryption Section - GCP
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Field
- Description
* - | Project ID
| Endpoint
- The Project ID and endpoint for the |rootkms-short| service to use for |SSE|.
The MinIO Tenant |KES| pods *must* have network access to the specified endpoint.
* - | Client Email
| Client ID
| Private Key ID
| Private Key
- Specify the credentials for the GCP user with which the Tenant authenticates to the |rootkms-short| service.
Review the :ref:`GCP Secret Manager Prerequisites <minio-sse-gcp-prereq-gcp>` for instructions on generating these values.
Once you have completed the |rootkms-short| configuration, you can finish any remaining sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
3) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
4) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

26
source/includes/k8s/steps-configure-minio-kes-hashicorp.rst
View File

@ -1,29 +1,3 @@
This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation.
As part of this procedure, you will:
- Use the MinIO Operator Console to create or manage a MinIO Tenant.
- Access the :guilabel:`Encryption` settings for that tenant and configure |SSE| using Hashicorp Vault.
- Create a new |EK| on Vault for use with |SSE|.
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
Deploy MinIO Tenant with Server-Side Encryption using Hashicorp Vault
---------------------------------------------------------------------

103
source/includes/linux/common-minio-kes.rst
View File

@ -11,8 +11,8 @@ The following example code downloads the latest Linux AMD64-compatible binary an
:class: copyable
:substitutions:
wget https://github.com/minio/kes/releases/download/v|kes-stable|/kes-linux-amd64 -O /tmp/kes && \
chmod +x /tmp/kes && \
wget https://github.com/minio/kes/releases/download/|kes-stable|/kes-linux-amd64 -O /tmp/kes
chmod +x /tmp/kes
sudo mv /tmp/kes /usr/local/bin
kes --version
@ -24,7 +24,7 @@ MinIO strongly recommends configuring a load balancer with a "Least Connections"
.. start-kes-service-file-desc
Create the ``/etc/systemd/system/minio.service`` file on all KES hosts:
Create the ``/etc/systemd/system/kes.service`` file on all KES hosts:
.. literalinclude:: /extra/kes.service
:language: shell
@ -42,6 +42,15 @@ These commands typically require root (``sudo``) permissions.
groupadd -r kes-user
useradd -M -r -g kes-user kes-user
The ``kes-user`` user and group must have read access to all files used by the KES service:
.. code-block:: shell
:class: copyable
:substitutions:
chown -R kes-user:kes-user /opt/kes
chown -R kes-user:kes-user /etc/kes
.. end-kes-service-file-desc
.. start-kes-start-service-desc
@ -75,4 +84,90 @@ For existing MinIO deployments, run the following command on each MinIO host to
systemctl reload minio
systemctl restart minio
.. end-kes-minio-start-service-desc
.. end-kes-minio-start-service-desc
.. start-kes-generate-kes-certs-prod-desc
Enabling connectivity between MinIO and KES requires at minimum one TLS certificate for performing mutual TLS (mTLS) authentication.
Depending on your Vault configuration, you may also need to create a dedicated set of TLS certificates for KES to connect and authenticate to Vault.
Defer to your organizations best practices around generating production-ready TLS certificates.
Place the certificates and corresponding private keys an appropriate directory such that the MinIO and KES service users can access and read their contents.
This procedure assumes a structure similar to the following:
.. code-block:: shell
:substitutions:
# For the MinIO Hosts
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.cert
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.key
# If KES certs are self-signed or use a non-global CA
# Include the CA certs as well
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert
# For the KES Hosts
-rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.cert
-rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.key
If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath|/certs directory such that each MinIO server can properly validate the KES certificates.
.. end-kes-generate-kes-certs-prod-desc
.. start-kes-configuration-minio-desc
Add the following lines to the MinIO Environment file on each MinIO host.
See the tutorials for :ref:`minio-snsd`, :ref:`minio-snmd`, or :ref:`minio-mnmd` for more detailed descriptions of a base MinIO environment file.
This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server.cert`` certificates are accessible at the specified location:
.. code-block:: shell
:class: copyable
:substitutions:
# Add these environment variables to the existing environment file
MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
MINIO_KMS_KES_CERT_FILE=|miniocertpath|/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=|miniocertpath|/minio-kes.key
MINIO_KMS_KES_CAPATH=|kescertpath|/kes-server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
minio server [ARGUMENTS]
Replace ``HOSTNAME`` with the IP address or hostname of the KES server.
If the MinIO server host machines cannot resolve or reach the specified ``HOSTNAME``, the deployment may return errors or fail to start.
- If using a single KES server host, specify the IP or hostname of that host
- If using multiple KES server hosts, specify the load balancer or reverse proxy managing connections to those hosts.
MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations:
- Encrypting the MinIO backend (IAM, configuration, etc.)
- Encrypting objects using :ref:`SSE-KMS <minio-encryption-sse-kms>` if the request does not
include a specific |EK|.
- Encrypting objects using :ref:`SSE-S3 <minio-encryption-sse-s3>`.
The ``minio-kes`` certificates enable mTLS between the MinIO deployment and the KES server *only*.
They do not otherwise enable TLS for other client connections to MinIO.
.. end-kes-configuration-minio-desc
.. start-kes-generate-key-desc
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 add a new |EK| for use with |SSE|.
The following command uses the ``kes key create`` command to add a new External Key (EK) stored on the root KMS server for use with encrypting the MinIO backend.
.. code-block:: shell
:class: copyable
:substitutions:
export KES_SERVER=https://127.0.0.1:7373
export KES_CLIENT_KEY=|miniocertpath|/minio-kes.key
export KES_CLIENT_CERT=|miniocertpath|/minio-kes.cert
kes key create -k encrypted-bucket-key
.. end-kes-generate-key-desc

110
source/includes/linux/steps-configure-minio-kes-aws-quick.rst Normal file
View File

@ -0,0 +1,110 @@
Deploy MinIO and KES with Server-Side Encryption using AWS Secrets Manager for Local Development
------------------------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Server Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-aws.rst
:start-after: start-kes-configuration-aws-desc
:end-before: end-kes-configuration-aws-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

111
source/includes/linux/steps-configure-minio-kes-aws.rst Normal file
View File

@ -0,0 +1,111 @@
Enable Server-Side Encryption with AWS SecretsManager for Production
--------------------------------------------------------------------
Prior to starting these steps, create the following folders if they do not already exist:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Download KES
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
b. Create the Service File
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-service-file-desc
:end-before: end-kes-service-file-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-prod-desc
:end-before: end-kes-generate-kes-certs-prod-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano /etc/kes/config.yaml
.. include:: /includes/common/common-minio-kes-aws.rst
:start-after: start-kes-configuration-aws-desc
:end-before: end-kes-configuration-aws-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Configure the MinIO Environment File
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
MinIO defaults to expecting this file at ``/etc/default/minio``.
If you modified your deployment to use a different location for the environment file, modify the file at that location.
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
This step uses ``systemd`` for starting and managing both the KES and MinIO server processes:
a. Start the KES Service on All Hosts
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-start-service-desc
:end-before: end-kes-start-service-desc
b. Start the MinIO Server
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-minio-start-service-desc
:end-before: end-kes-minio-start-service-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

109
source/includes/linux/steps-configure-minio-kes-azure-quick.rst Normal file
View File

@ -0,0 +1,109 @@
Deploy MinIO and KES with Server-Side Encryption using Azure Key Vault for Local Development
--------------------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Server Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-azure.rst
:start-after: start-kes-configuration-azure-desc
:end-before: end-kes-configuration-azure-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

110
source/includes/linux/steps-configure-minio-kes-azure.rst Normal file
View File

@ -0,0 +1,110 @@
Deploy MinIO and KES with Server-Side Encryption using Azure KeyVault for Local Development
--------------------------------------------------------------------------------------------
Prior to starting these steps, create the following folders if they do not already exist:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Download KES
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
b. Create the Service File
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-service-file-desc
:end-before: end-kes-service-file-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-prod-desc
:end-before: end-kes-generate-kes-certs-prod-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano /etc/kes/config.yaml
.. include:: /includes/common/common-minio-kes-azure.rst
:start-after: start-kes-configuration-azure-desc
:end-before: end-kes-configuration-azure-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Configure the MinIO Environment File
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
MinIO defaults to expecting this file at ``/etc/default/minio``.
If you modified your deployment to use a different location for the environment file, modify the file at that location.
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
This step uses ``systemd`` for starting and managing both the KES and MinIO server processes:
a. Start the KES Service on All Hosts
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-start-service-desc
:end-before: end-kes-start-service-desc
b. Start the MinIO Server
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-minio-start-service-desc
:end-before: end-kes-minio-start-service-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

109
source/includes/linux/steps-configure-minio-kes-gcp-quick.rst Normal file
View File

@ -0,0 +1,109 @@
Deploy MinIO and KES with Server-Side Encryption using GCP Secrets Manager for Local Development
------------------------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Server Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-gcp.rst
:start-after: start-kes-configuration-gcp-desc
:end-before: end-kes-configuration-gcp-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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.
b. Create the MinIO Environment File
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

110
source/includes/linux/steps-configure-minio-kes-gcp.rst Normal file
View File

@ -0,0 +1,110 @@
Enable Server-Side Encryption with GCP Secrets Manager for Production
---------------------------------------------------------------------
Prior to starting these steps, create the following folders if they do not already exist:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Download KES
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
b. Create the Service File
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-service-file-desc
:end-before: end-kes-service-file-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-prod-desc
:end-before: end-kes-generate-kes-certs-prod-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano /etc/kes/config.yaml
.. include:: /includes/common/common-minio-kes-gcp.rst
:start-after: start-kes-configuration-gcp-desc
:end-before: end-kes-configuration-gcp-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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.
b. Configure the MinIO Environment File
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
MinIO defaults to expecting this file at ``/etc/default/minio``.
If you modified your deployment to use a different location for the environment file, modify the file at that location.
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
This step uses ``systemd`` for starting and managing both the KES and MinIO server processes:
a. Start the KES Service on All Hosts
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-start-service-desc
:end-before: end-kes-start-service-desc
b. Start the MinIO Server
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-minio-start-service-desc
:end-before: end-kes-minio-start-service-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

113
source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst Normal file
View File

@ -0,0 +1,113 @@
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault for Local Development
--------------------------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Server Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` certificate as a trusted Certificate Authority.
See the `Hashicorp Server Configuration Documentation <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

89
source/includes/linux/steps-configure-minio-kes-hashicorp.rst
View File

@ -1,53 +1,15 @@
This procedure assumes a single local host machine running the MinIO and KES processes.
As part of this procedure, you will:
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault for Production
-------------------------------------------------------------------------------------
- Deploy a |KES| server configured to use `Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
- Create a new |EK| on Vault for use with |SSE|.
- Deploy a MinIO server configured to use the |KES| container for supporting |SSE|.
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production environments, this procedure provides general guidance on deploying and configuring KES at scale.
Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
Deploy MinIO and KES to Enable Server-Side Encryption with Hashicorp Vault
--------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
Prior to starting these steps, create the following folders if they do not already exist:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P ~/minio-kes-vault/certs ~/minio-kes-vault/minio ~/minio-kes-vault/config
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -67,38 +29,53 @@ b. Create the Service File
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-prod-desc
:end-before: end-kes-generate-kes-certs-prod-desc
Depending on your Vault configuration, you may also need to specify the CA used to sign the KES certificates to the Vault server.
See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano /etc/kes/config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
Save the configuration file as ``~/minio-kes-vault/config/kes-config.yaml``.
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of ~/minio-kes-vault/certs/minio-kes.cert
kes tool identity of |miniocertpath|/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>`.
b. Configure the MinIO Environment File
b. Create the MinIO Environment File
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
.. include:: /includes/common/common-minio-kes.rst
MinIO defaults to expecting this file at ``/etc/default/minio``.
If you modified your deployment to use a different location for the environment file, modify the file at that location.
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
@ -108,7 +85,9 @@ b. Create the MinIO Environment File
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
This step uses ``systemd`` for starting and managing both the KES and MinIO server processes:
a. Start the KES Service on All Hosts
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-start-service-desc
@ -123,7 +102,7 @@ b. Start the MinIO Server
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc

29
source/includes/macos/common-minio-kes.rst
View File

@ -13,7 +13,7 @@ The command downloads the |kes-stable| binary for that architecture, sets it to
:class: copyable
:substitutions:
curl -O https://github.com/minio/kes/releases/download/v|kes-stable|/kes-darwin-arm64
curl -O https://github.com/minio/kes/releases/download/|kes-stable|/kes-darwin-arm64
chmod +x ./kes-darwin-arm64
sudo mv ./kes-darwin-arm64 /usr/local/bin/kes
@ -23,34 +23,9 @@ The command downloads the |kes-stable| binary for that architecture, sets it to
:class: copyable
:substitutions:
curl -O https://github.com/minio/kes/releases/download/v|kes-stable|/kes-darwin-amd64
curl -O https://github.com/minio/kes/releases/download/|kes-stable|/kes-darwin-amd64
chmod +x ./kes-darwin-amd64
sudo mv ./kes-darwin-amd64 /usr/local/bin/kes
.. end-kes-download-desc
.. start-kes-start-server-desc
Run the following command in a terminal or shell to start the KES server as a foreground process.
.. code-block:: shell
:class: copyable
kes server --mlock --auth --config=~/minio-kes-vault/kes-server-config.yaml
Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background.
.. end-kes-start-server-desc
.. start-kes-minio-start-server-desc
Run the following command in a terminal or shell to start the MinIO server as a foreground process.
.. code-block:: shell
:class: copyable
export MINIO_CONFIG_ENV_FILE=/etc/default/minio
minio server --console-address :9090
.. end-kes-minio-start-server-desc

108
source/includes/macos/steps-configure-minio-kes-aws.rst Normal file
View File

@ -0,0 +1,108 @@
Deploy MinIO and KES with Server-Side Encryption using AWS Secrets Manager
--------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/macos/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-aws.rst
:start-after: start-kes-configuration-aws-desc
:end-before: end-kes-configuration-aws-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

107
source/includes/macos/steps-configure-minio-kes-azure.rst Normal file
View File

@ -0,0 +1,107 @@
Deploy MinIO and KES with Server-Side Encryption using Azure Key Vault
----------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/macos/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-azure.rst
:start-after: start-kes-configuration-azure-desc
:end-before: end-kes-configuration-azure-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

107
source/includes/macos/steps-configure-minio-kes-gcp.rst Normal file
View File

@ -0,0 +1,107 @@
Deploy MinIO and KES with Server-Side Encryption using GCP Secrets Manager
--------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
1) Download the KES Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/macos/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-gcp.rst
:start-after: start-kes-configuration-gcp-desc
:end-before: end-kes-configuration-gcp-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of |miniocertpath|/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.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

87
source/includes/macos/steps-configure-minio-kes-hashicorp.rst
View File

@ -1,56 +1,18 @@
This procedure assumes a single local host machine running the MinIO and KES processes.
As part of this procedure, you will:
- Deploy a |KES| server configured to use `Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
- Create a new |EK| on Vault for use with |SSE|.
- Deploy a MinIO server configured to use the |KES| container for supporting |SSE|.
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production environments, MinIO recommends using Linux hosts.
See the MinIO on Linux documentation for configuring MinIO with KES and Hashicorp Vault.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment
:end-before: end-kes-new-existing-minio-deployment
Deploy MinIO and KES to Enable Server-Side Encryption with Hashicorp Vault
--------------------------------------------------------------------------
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault
----------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P ~/minio-kes-vault/certs ~/minio-kes-vault/minio ~/minio-kes-vault/config
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniodatapath|
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Download the KES Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/macos/common-minio-kes.rst
:start-after: start-kes-download-desc
@ -63,33 +25,50 @@ Prior to starting these steps, create the following folders:
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/kes-config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
Save the configuration file as ``~/minio-kes-vault/config/kes-config.yaml``.
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of ~/minio-kes-vault/certs/minio-kes.cert
kes tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
@ -102,16 +81,20 @@ The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/macos/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/macos/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
Defer to your operating system best practices for running processes in the background.
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

55
source/includes/windows/common-minio-kes.rst
View File

@ -18,21 +18,22 @@ The following commands creates two TLS certificates that expire within 30 days o
.. code-block:: powershell
:class: copyable
:substitutions:
C:\kes.exe tool identity new \
--key C:\minio-kes-vault\certs\kes-server.key \
--cert C:\minio-kes-vault\certs\kes-server.cert \
--ip "127.0.0.1" \
# These commands output the certificates to |kescertpath|
C:\kes.exe tool identity new \
--key |kescertpath| \ kes-server.key \
--cert |kescertpath| \ kes-server.cert \
--ip "127.0.0.1" \
--dns localhost
C:\kes tool identity new \
--key C:\minio-kes-vault\certs\minio-kes.key \
--cert C:\minio-kes-vault\certs\minio-kes.cert \
--ip "127.0.0.1" \
C:\kes.exe tool identity new \
--key |miniocertpath| \ minio-kes.key \
--cert |miniocertpath| \ minio-kes.cert \
--ip "127.0.0.1" \
--dns localhost
These commands output the keys to the ``C:\minio-kes-vault\certs`` directory on the host operating system.
The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate.
The above example assumes that all components (Vault, MinIO, and KES) deploy on the same local host machine accessible via ``localhost`` or ``127.0.0.1``.
You can specify additional IP or Hostnames based on the network configuration of your local host.
@ -51,7 +52,7 @@ The following PowerShell command downloads the latest Windows-compatible binary
:class: copyable
:substitutions:
Invoke-WebRequest -Uri "https://github.com/minio/kes/releases/download/v|kes-stable|/kes-linux-windows-amd64.exe" -OutFile "C:\kes.exe"
Invoke-WebRequest -Uri "https://github.com/minio/kes/releases/download/|kes-stable|/kes-linux-windows-amd64.exe" -OutFile "C:\kes.exe"
C:\kes.exe --version
@ -63,8 +64,9 @@ Run the following command in a terminal or shell to start the KES server as a fo
.. code-block:: powershell
:class: copyable
:substitutions:
C:\kes.exe server --auth --config=C:\minio-kes-vault\config\kes-server-config.yaml
C:\kes.exe server --auth --config=|kesconfigpath| \ config \ kes-config.yaml
Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background.
@ -76,9 +78,10 @@ Run the following command in a terminal or shell to start the MinIO server as a
.. code-block:: powershell
:class: copyable
:substitutions:
export MINIO_CONFIG_ENV_FILE=C:\minio-kes-vault\config\minio
C:\minio.exe server --console-address :9090
export MINIO_CONFIG_ENV_FILE=|minioconfigpath| \ config \ minio
C: \ minio.exe server --console-address :9090
.. end-kes-minio-start-server-desc
@ -91,10 +94,11 @@ The following command uses the ``kes key create`` command to create a new Extern
.. code-block:: powershell
:class: copyable
:substitutions:
export KES_SERVER=https://127.0.0.1:7373
export KES_CLIENT_KEY=C:\minio-kes-vault\certs\minio-kes.key
export KES_CLIENT_CERT=C:\minio-kes-vault\certs\minio-kes.cert
export KES_CLIENT_KEY=|miniocertpath| \ minio-kes.key
export KES_CLIENT_CERT=|miniocertpath| \ minio-kes.cert
C:\kes.exe key create -k encrypted-bucket-key
@ -118,24 +122,19 @@ See the tutorials for :ref:`minio-snsd` for more detailed descriptions of a base
This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server.cert`` certificates are accessible at the specified location:
.. code-block:: shell
.. code-block:: powershell
:class: copyable
:substitutions:
# Add these environment variables to the existing environment file
MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
MINIO_KMS_KES_CERT_FILE=C:\minio-kes-vault\certs\minio-kes.cert
MINIO_KMS_KES_KEY_FILE=C:\minio-kes-vault\certs\minio-kes.key
MINIO_KMS_KES_CAPATH=C:\minio-kes-vault\certs\kes-server.cert
MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
MINIO_KMS_KES_CERT_FILE=|miniocertpath| \ minio-kes.cert
MINIO_KMS_KES_KEY_FILE=|miniocertpath| \ minio-kes.key
MINIO_KMS_KES_CAPATH=|miniocertpath| \ kes-server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
minio server [ARGUMENTS]
Replace ``HOSTNAME`` with the IP address or hostname of the KES server.
If the MinIO server host machines cannot resolve or reach the specified ``HOSTNAME``, the deployment may return errors or fail to start.
- If using a single KES server host, specify the IP or hostname of that host
- If using multiple KES server hosts, specify the load balancer or reverse proxy managing connections to those hosts.
minio.exe server [ARGUMENTS]
MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations:

105
source/includes/windows/steps-configure-minio-kes-aws.rst Normal file
View File

@ -0,0 +1,105 @@
Deploy MinIO and KESwith Server-Side Encryption using AWS Secrets Manager
-------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: powershell
:class: copyable
:substitutions:
New-Item -Path "|kescertpath|" -ItemType "directory"
New-Item -Path "|kesconfigpath|" -ItemType "directory"
New-Item -Path "|miniodatapath|" -ItemType "directory"
1) Download KES for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |kesconfigpath|\kes-config.yaml
.. include:: /includes/common/common-minio-kes-aws.rst
:start-after: start-kes-configuration-aws-desc
:end-before: end-kes-configuration-aws-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes.exe tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |minioconfigpath|\minio
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

104
source/includes/windows/steps-configure-minio-kes-azure.rst Normal file
View File

@ -0,0 +1,104 @@
Deploy MinIO and KES with Server-Side Encryption using Azure Key Vault
----------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: powershell
:class: copyable
:substitutions:
New-Item -Path "|kescertpath|" -ItemType "directory"
New-Item -Path "|kesconfigpath|" -ItemType "directory"
New-Item -Path "|miniodatapath|" -ItemType "directory"
1) Download KES for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |kesconfigpath|\kes-config.yaml
.. include:: /includes/common/common-minio-kes-azure.rst
:start-after: start-kes-configuration-azure-desc
:end-before: end-kes-configuration-azure-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes.exe tool identity of |miniocertpath|/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>`.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |minioconfigpath|\minio
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

103
source/includes/windows/steps-configure-minio-kes-gcp.rst Normal file
View File

@ -0,0 +1,103 @@
Deploy MinIO and KES with Server-Side Encryption using GCP Secrets Manager
--------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: powershell
:class: copyable
:substitutions:
New-Item -Path "|kescertpath|" -ItemType "directory"
New-Item -Path "|kesconfigpath|" -ItemType "directory"
New-Item -Path "|miniodatapath|" -ItemType "directory"
1) Download KES for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |kesconfigpath|\kes-config.yaml
.. include:: /includes/common/common-minio-kes-gcp.rst
:start-after: start-kes-configuration-gcp-desc
:end-before: end-kes-configuration-gcp-desc
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes.exe tool identity of |miniocertpath|/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.
b. Create the MinIO Environment File
Create the environment file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |minioconfigpath|\minio
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
b. Start the MinIO Server
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
6) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

83
source/includes/windows/steps-configure-minio-kes-hashicorp.rst
View File

@ -1,55 +1,15 @@
This procedure assumes a single local host machine running the MinIO and KES processes.
As part of this procedure, you will:
- Deploy a |KES| server configured to use `Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
- Create a new |EK| on Vault for use with |SSE|.
- Deploy a MinIO server configured to use the |KES| container for supporting |SSE|.
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production baremetal environments, deploy MinIO onto Linux hosts and follow the corresponding documentation for this procedure.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
Deploy MinIO and KES to Enable Server-Side Encryption with Hashicorp Vault
--------------------------------------------------------------------------
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault
----------------------------------------------------------------------
Prior to starting these steps, create the following folders:
.. code-block:: powershell
:class: copyable
:substitutions:
New-Item -Path "C:\minio-kes-vault" -ItemType "directory"
New-Item -Path "C:\minio-kes-vault\certs" -ItemType "directory"
New-Item -Path "C:\minio-kes-vault\minio" -ItemType "directory"
New-Item -Path "C:\minio-kes-vault\config" -ItemType "directory"
New-Item -Path "|kescertpath|" -ItemType "directory"
New-Item -Path "|kesconfigpath|" -ItemType "directory"
New-Item -Path "|miniodatapath|" -ItemType "directory"
1) Download KES for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -65,34 +25,53 @@ Prior to starting these steps, create the following folders:
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
Defer to the client documentation for instructions on trusting a third-party CA.
3) Create the KES and MinIO Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Create the KES Configuration File
Create the configuration file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |kesconfigpath|\kes-config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
Save the configuration file as ``C:\minio-kes-vault\config\kes-config.yaml``.
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
.. code-block:: shell
:class: copyable
:substitutions:
kes tool identity of C:\minio-kes-vault\certs\minio-kes.cert
kes.exe tool identity of |miniocertpath|/minio-kes.cert
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``.
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
- Set ``AWSACCESSKEY`` and ``AWSSECRETKEY`` to the appropriate :ref:`AWS Credentials <minio-sse-aws-prereq-aws>`.
b. Create the MinIO Environment File
.. include:: /includes/common/common-minio-kes.rst
Create the environment file using your preferred text editor.
The following example uses the Windows Notepad program:
.. code-block:: powershell
:substitutions:
notepad |minioconfigpath|\minio
.. include:: /includes/windows/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc

4
source/operations/install-deploy-manage/deploy-minio-tenant.rst
View File

@ -416,9 +416,9 @@ The :guilabel:`Security` section displays TLS certificate settings for the MinIO
8) The :guilabel:`Encryption` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :guilabel:`Encryption` section displays the :ref:`Server-Side Encryption <minio-sse>` settings for the MinIO Tenant.
The :guilabel:`Encryption` section displays the :ref:`Server-Side Encryption (SSE) <minio-sse>` settings for the MinIO Tenant.
Enabling SSE also deploys a MinIO :minio-git:`KES <kes>` service in the Tenant to faciliate SSE operations.
Enabling SSE also creates :minio-git:`MinIO Key Encryption Service <kes>` pods in the Tenant to facilitate SSE operations.
.. list-table::
:header-rows: 1

6
source/operations/server-side-encryption.rst
View File

@ -56,8 +56,7 @@ supports the following encryption strategies:
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 a tutorial on enabling SSE-KMS in a local (non-production) MinIO Deployment, see :ref:`minio-encryption-sse-kms-quickstart`.
.. tab-item:: SSE-S3
:sync: sse-s3
@ -69,8 +68,7 @@ supports the following encryption strategies:
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 a tutorial on enabling SSE-s3 in a local (non-production) MinIO Deployment, see :ref:`minio-encryption-sse-s3-quickstart`.
.. tab-item:: SSE-C
:sync: sse-c

365
source/operations/server-side-encryption/configure-minio-kes-aws.rst
View File

@ -1,8 +1,8 @@
.. _minio-sse-aws:
===============================================
Server-Side Object Encryption with AWS Root KMS
===============================================
===============================================================
Server-Side Object Encryption with AWS Secrets Manager Root KMS
===============================================================
.. default-domain:: minio
@ -10,59 +10,124 @@ Server-Side Object Encryption with AWS Root KMS
: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)`
.. |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)`
.. |rootkms| replace:: `AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`__
.. |rootkms-short| replace:: AWS Secrets Manager
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 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|.
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:
.. Conditionals to handle the slight divergences in procedures between platforms.
- Configure |KES| to use
`AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`__ as the root
|KMS|.
.. cond:: linux
- 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>`.
This procedure provides guidance for deploying and configuring KES at scale for a supporting |SSE| on a production MinIO deployment, with |rootkms| as the external root |KMS|.
You can also use this procedure for deploying to local environments for testing and evaluation.
As part of this procedure, you will:
#. Deploy one or more |KES| servers configured to use |rootkms| as the root |KMS|.
You may optionally deploy a load balancer for managing connections to those KES servers.
#. Create a new |EK| on |rootkms-short| for use with |SSE|.
#. Create or modify a MinIO deployment with support for |SSE| using |KES|.
Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
.. cond:: macos or windows
This procedure assumes a single local host machine running the MinIO and KES processes, with |rootkms| as the external root |KMS|..
As part of this procedure, you will:
#. Deploy a |KES| server configured to use |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO server in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: container
This procedure assumes a single host machine running the MinIO and KES containers, with |rootkms| as the external root |KMS|..
As part of this procedure, you will:
#. Deploy a |KES| container configured to use |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO Server container in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: k8s
This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation, with a cluster-accessible |rootkms| service as the external root |KMS|.
As part of this procedure, you will:
#. Use the MinIO Operator Console to create or manage a MinIO Tenant.
#. Access the :guilabel:`Encryption` settings for that tenant and configure |SSE| using |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The procedures on this page *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of the MinIO Kubernetes Operator.
This procedure assumes the latest stable Operator and Plugin version |operator-version-stable|.
See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator.
.. _minio-sse-aws-prereq-aws:
AWS Key Management Service
~~~~~~~~~~~~~~~~~~~~~~~~~~
Ensure Access to the AWS Secrets Manager and 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.
This procedure assumes access to and familiarity with |rootkms| and `|rootkms-short| <https://aws.amazon.com/kms/>`__.
MinIO specifically requires the following AWS settings or
configurations:
.. cond:: k8s
- A new AWS
:aws-docs:`Programmatic Access <IAM/latest/UserGuide/id_users_create.html>`
user with corresponding access key and secret key.
This procedure assumes your Kubernetes cluster configuration allows for cluster-internal pods and services to resolve and connect to endpoints outside of the cluster, such as the public internet.
- A policy that grants the created user access to AWS Secrets Manager and
AWS KMS. The following policy grants the minimum necessary permissions:
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 |rootkms-short|.
The following policy grants the minimum necessary permissions:
.. code-block:: json
:class: copyable
@ -99,186 +164,80 @@ configurations:
``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
.. cond:: linux or macos or windows
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
Enable MinIO Server-Side Encryption with AWS Root KMS
-----------------------------------------------------
.. cond:: container
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>`.
Install Podman or a Similar Container Management Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Prior to starting these steps, create the following folders:
.. include:: /includes/container/common-deploy.rst
:start-after: start-common-prereq-container-management-interface
:end-before: end-common-prereq-container-management-interface
.. code-block:: shell
:class: copyable
.. The included file has the correct header structure.
There are slight divergences between platforms so this ends up being easier compared to cascading conditionals to handle little nitty-gritty differences.
mkdir -P ~/kes/certs ~/kes/config
.. |namespace| replace:: minio-kes-aws
1) Download the MinIO Key Encryption Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: k8s
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
.. include:: /includes/k8s/steps-configure-minio-kes-aws.rst
2) Generate the TLS Private and Public Key for KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: container
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
.. |kescertpath| replace:: ~/minio-kes-aws/certs
.. |kesconfigpath| replace:: ~/minio-kes-aws/config
.. |kesconfigcertpath| replace:: /certs/
.. |miniocertpath| replace:: ~/minio-kes-aws/certs
.. |minioconfigpath| replace:: ~/minio-kes-aws/config
.. |miniodatapath| replace:: ~/minio-kes-aws/minio
3) Generate the TLS Private and Public Key for MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/steps-configure-minio-kes-aws.rst
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-minio-certs-desc
:end-before: end-kes-generate-minio-certs-desc
.. cond:: linux
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:
aws:
secretsmanager:
endpoint: secretsmanager.REGION.amazonaws.com # 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
.. |kescertpath| replace:: /opt/kes/certs
.. |kesconfigpath| replace:: /opt/kes/config
.. |kesconfigcertpath| replace:: /opt/kes/certs/
.. |miniocertpath| replace:: /opt/minio/certs
.. |minioconfigpath| replace:: /opt/minio/config
.. |miniodatapath| replace:: ~/minio
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.
.. include:: /includes/linux/steps-configure-minio-kes-aws-quick.rst
- Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``.
.. include:: /includes/linux/steps-configure-minio-kes-aws.rst
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``.
.. cond:: macos
- Set ``AWSACCESSKEY`` and ``AWSSECRETKEY`` to the appropriate
:ref:`AWS Credentials <minio-sse-aws-prereq-aws>`.
.. |kescertpath| replace:: ~/minio-kes-aws/certs
.. |kesconfigpath| replace:: ~/minio-kes-aws/config
.. |kesconfigcertpath| replace:: ~/minio-kes-aws/certs/
.. |miniocertpath| replace:: ~/minio-kes-aws/certs
.. |minioconfigpath| replace:: ~/minio-kes-aws/config
.. |miniodatapath| replace:: ~/minio-kes-aws/minio
5) Start KES
~~~~~~~~~~~~
.. include:: /includes/macos/steps-configure-minio-kes-aws.rst
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-run-server-desc
:end-before: end-kes-run-server-desc
.. cond:: windows
6) Generate a Cryptographic Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. |kescertpath| replace:: C:\\minio-kes-aws\\certs
.. |kesconfigpath| replace:: C:\\minio-kes-aws\\config
.. |kesconfigcertpath| replace:: C:\\minio-kes-aws\\certs\\
.. |miniocertpath| replace:: C:\\minio-kes-aws\\certs
.. |minioconfigpath| replace:: C:\\minio-kes-aws\\config
.. |miniodatapath| replace:: C:\\minio-kes-aws\\minio
.. 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.
.. include:: /includes/windows/steps-configure-minio-kes-aws.rst
Configuration Reference for AWS Root KMS
----------------------------------------
@ -341,31 +300,31 @@ using AWS Secrets Manager and AWS KMS as the root Key Management Service
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc
* - ``keystore.secretsmanager``
* - ``keystore.aws.secretsmanager``
- The configuration for the AWS Secrets Manager and AWS KMS.
- ``endpoint`` - The endpoint for the Secrets Manager service,

307
source/operations/server-side-encryption/configure-minio-kes-azure.rst
View File

@ -15,6 +15,9 @@ Server-Side Object Encryption with Azure Key Vault Root KMS
.. |KMS| replace:: :abbr:`KMS (Key Management System)`
.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) <kes>`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
.. |rootkms| replace:: `Azure Key Vault <https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__
.. |rootkms-short| replace:: Azure Key Vault
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
@ -27,23 +30,93 @@ 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:
.. Conditionals to handle the slight divergences in procedures between platforms.
- Configure |KES| to use
`Azure Key Vault
<https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__
as the root |KMS|.
.. cond:: linux
- 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>`.
This procedure provides guidance for deploying and configuring KES at scale for a supporting |SSE| on a production MinIO deployment, with |rootkms| as the external root |KMS|.
You can also use this procedure for deploying to local environments for testing and evaluation.
As part of this procedure, you will:
#. Deploy one or more |KES| servers configured to use |rootkms| as the root |KMS|.
You may optionally deploy a load balancer for managing connections to those KES servers.
#. Create a new |EK| on |rootkms-short| for use with |SSE|.
#. Create or modify a MinIO deployment with support for |SSE| using |KES|.
Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
.. cond:: macos or windows
This procedure assumes a single local host machine running the MinIO and KES processes, with |rootkms| as the external root |KMS|..
As part of this procedure, you will:
#. Deploy a |KES| server configured to use |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO server in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: container
This procedure assumes a single host machine running the MinIO and KES containers, with |rootkms| as the external root |KMS|..
As part of this procedure, you will:
#. Deploy a |KES| container configured to use |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO Server container in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: k8s
This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation, with a cluster-accessible |rootkms| service as the external root |KMS|.
As part of this procedure, you will:
#. Use the MinIO Operator Console to create or manage a MinIO Tenant.
#. Access the :guilabel:`Encryption` settings for that tenant and configure |SSE| using |rootkms| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The procedures on this page *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of the MinIO Kubernetes Operator.
This procedure assumes the latest stable Operator and Plugin version |operator-version-stable|.
See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator.
.. _minio-sse-azure-prereq-azure:
Azure Key Vault
@ -76,185 +149,77 @@ configurations:
Set the :guilabel:`Principal` for the new policy to the KES Application ID.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: linux or macos or windows
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
.. cond:: container
Enable MinIO Server-Side Encryption with Azure Key Vault Root KMS
-----------------------------------------------------------------
Install Podman or a Similar Container Management Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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/container/common-deploy.rst
:start-after: start-common-prereq-container-management-interface
:end-before: end-common-prereq-container-management-interface
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
.. |namespace| replace:: minio-kes-azure
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: k8s
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
.. include:: /includes/k8s/steps-configure-minio-kes-azure.rst
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: container
.. tab-set::
.. |kescertpath| replace:: ~/minio-kes-azure/certs
.. |kesconfigpath| replace:: ~/minio-kes-azure/config
.. |kesconfigcertpath| replace:: /certs/
.. |miniocertpath| replace:: ~/minio-kes-azure/certs
.. |minioconfigpath| replace:: ~/minio-kes-azure/config
.. |miniodatapath| replace:: ~/minio-kes-azure/minio
.. tab-item:: SSE-KMS
.. include:: /includes/container/steps-configure-minio-kes-azure.rst
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. cond:: linux
.. code-block:: shell
:class: copyable
.. |kescertpath| replace:: /opt/kes/certs
.. |kesconfigpath| replace:: /opt/kes/config
.. |kesconfigcertpath| replace:: /opt/kes/certs/
.. |miniocertpath| replace:: /opt/minio/certs
.. |minioconfigpath| replace:: /opt/minio/config
.. |miniodatapath| replace:: ~/minio
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.
.. include:: /includes/linux/steps-configure-minio-kes-azure-quick.rst
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.
.. include:: /includes/linux/steps-configure-minio-kes-azure.rst
.. tab-item:: SSE-S3
.. cond:: macos
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|.
.. |kescertpath| replace:: ~/minio-kes-azure/certs
.. |kesconfigpath| replace:: ~/minio-kes-azure/config
.. |kesconfigcertpath| replace:: ~/minio-kes-azure/certs/
.. |miniocertpath| replace:: ~/minio-kes-azure/certs
.. |minioconfigpath| replace:: ~/minio-kes-azure/config
.. |miniodatapath| replace:: ~/minio-kes-azure/minio
.. code-block:: shell
:class: copyable
.. include:: /includes/macos/steps-configure-minio-kes-azure.rst
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
.. cond:: windows
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
.. |kescertpath| replace:: C:\\minio-kes-azure\\certs
.. |kesconfigpath| replace:: C:\\minio-kes-azure\\config
.. |kesconfigcertpath| replace:: C:\\minio-kes-azure\\certs\\
.. |miniocertpath| replace:: C:\\minio-kes-azure\\certs
.. |minioconfigpath| replace:: C:\\minio-kes-azure\\config
.. |miniodatapath| replace:: C:\\minio-kes-azure\\minio
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.
.. include:: /includes/windows/steps-configure-minio-kes-azure.rst
Configuration Reference for Azure Key Vault Root KMS
----------------------------------------------------
@ -318,27 +283,27 @@ using Azure Key Vault as the root Key Management Service
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc

326
source/operations/server-side-encryption/configure-minio-kes-gcp.rst
View File

@ -10,11 +10,14 @@ Server-Side Object Encryption with GCP Secret Manager Root KMS
: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)`
.. |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)`
.. |rootkms| replace:: `Google Cloud Platform Secret Manager
<https://cloud.google.com/secret-manager/>`__
.. |rootkms-short| replace:: GCP Secret Manager
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
@ -27,21 +30,94 @@ 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:
.. Conditionals to handle the slight divergences in procedures between platforms.
- Configure |KES| to use
`Google Cloud Platform Secret Manager
<https://cloud.google.com/secret-manager/>`__ as the root |KMS|.
.. cond:: linux
- 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>`.
This procedure provides guidance for deploying and configuring KES at scale for a supporting |SSE| on a production MinIO deployment.
You can also use this procedure for deploying to local environments for testing and evaluation.
As part of this procedure, you will:
#. Deploy one or more |KES| servers configured to use |rootkms| as the root |KMS|.
You may optionally deploy a load balancer for managing connections to those KES servers.
#. Create a new |EK| on |rootkms-short| for use with |SSE|.
#. Create or modify a MinIO deployment with support for |SSE| using |KES|.
Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
.. cond:: macos or windows
This procedure assumes a single local host machine running the MinIO and KES processes.
As part of this procedure, you will:
#. Deploy a |KES| server configured to use |rootkms-short| as the root |KMS|.
#. Create a new |EK| on |rootkms-short| for use with |SSE|.
#. Deploy a MinIO server in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: container
This procedure assumes a single host machine running the MinIO and KES containers.
As part of this procedure, you will:
#. Deploy a |KES| container configured to use |rootkms-short| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO Server container in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with |rootkms-short|.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. cond:: k8s
This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation.
As part of this procedure, you will:
#. Use the MinIO Operator Console to create or manage a MinIO Tenant.
#. Access the :guilabel:`Encryption` settings for that tenant and configure |SSE| using |rootkms-short|.
#. Create a new |EK| on |rootkms-short| for use with |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and |rootkms-short|.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The procedures on this page *requires* a valid installation of the MinIO
Kubernetes Operator and assumes the local host has a matching installation of
the MinIO Kubernetes Operator. This procedure assumes the latest stable Operator
and Plugin version |operator-version-stable|.
See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator.
.. _minio-sse-gcp-prereq-gcp:
GCP Secret Manager
@ -53,6 +129,10 @@ The `Secret Manager Quickstart
<https://cloud.google.com/secret-manager/docs/quickstart>`__
provides a sufficient foundation for the purposes of this procedure.
.. cond:: k8s
This procedure assumes your Kubernetes cluster configuration allows for cluster-internal pods and services to resolve and connect to endpoints outside the cluster, such as the public internet.
MinIO specifically requires the following GCP settings or
configurations:
@ -75,187 +155,79 @@ configurations:
including private keys. Copy these credentials to a safe and secure location
for use with this procedure.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: linux or macos or windows
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
.. cond:: container
Enable MinIO Server-Side Encryption with GCP Secret Manager Root KMS
--------------------------------------------------------------------
Install Podman or a Similar Container Management Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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/container/common-deploy.rst
:start-after: start-common-prereq-container-management-interface
:end-before: end-common-prereq-container-management-interface
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
.. The included file has the correct header structure.
There are slight divergences between platforms so this ends up being easier compared to cascading conditionals to handle little nitty-gritty differences.
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. |namespace| replace:: minio-kes-gcp
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
.. cond:: container
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. |kescertpath| replace:: ~/minio-kes-gcp/certs
.. |kesconfigpath| replace:: ~/minio-kes-gcp/config
.. |kesconfigcertpath| replace:: /certs/
.. |miniocertpath| replace:: ~/minio-kes-gcp/certs
.. |minioconfigpath| replace:: ~/minio-kes-gcp/config
.. |miniodatapath| replace:: ~/minio-kes-gcp/minio
.. tab-set::
.. include:: /includes/container/steps-configure-minio-kes-gcp.rst
.. tab-item:: SSE-KMS
.. cond:: linux
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. |kescertpath| replace:: /opt/kes/certs
.. |kesconfigpath| replace:: /opt/kes/config
.. |kesconfigcertpath| replace:: /opt/kes/certs/
.. |miniocertpath| replace:: /opt/minio/certs
.. |minioconfigpath| replace:: /opt/minio/config
.. |miniodatapath| replace:: ~/minio
.. code-block:: shell
:class: copyable
.. include:: /includes/linux/steps-configure-minio-kes-gcp-quick.rst
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
.. include:: /includes/linux/steps-configure-minio-kes-gcp.rst
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
.. cond:: macos
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.
.. |kescertpath| replace:: ~/minio-kes-gcp/certs
.. |kesconfigpath| replace:: ~/minio-kes-gcp/config/
.. |kesconfigcertpath| replace:: ~/minio-kes-gcp/certs
.. |miniocertpath| replace:: ~/minio-kes-gcp/certs
.. |minioconfigpath| replace:: ~/minio-kes-gcp/config
.. |miniodatapath| replace:: ~/minio-kes-gcp/minio
.. tab-item:: SSE-S3
.. include:: /includes/macos/steps-configure-minio-kes-gcp.rst
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|.
.. cond:: k8s
.. code-block:: shell
:class: copyable
.. include:: /includes/k8s/steps-configure-minio-kes-gcp.rst
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
.. cond:: windows
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
.. |kescertpath| replace:: C:\\minio-kes-gcp\\certs
.. |kesconfigpath| replace:: C:\\minio-kes-gcp\\config
.. |kesconfigcertpath| replace:: C:\\minio-kes-gcp\\certs\\
.. |miniocertpath| replace:: C:\\minio-kes-gcp\\certs
.. |minioconfigpath| replace:: C:\\minio-kes-gcp\\config
.. |miniodatapath| replace:: C:\\minio-kes-gcp\\minio
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.
.. include:: /includes/windows/steps-configure-minio-kes-gcp.rst
Configuration Reference for GCP Secret Manager Root KMS
-------------------------------------------------------
@ -319,27 +291,27 @@ using GCP Secrets Manager as the root Key Management Service
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc

231
source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst
View File

@ -10,11 +10,13 @@ Server-Side Object Encryption with Hashicorp Vault Root KMS
: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)`
.. |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)`
.. |rootkms| replace:: `Hashicorp Vault <https://vaultproject.io/>`__
.. |rootkms-short| replace:: Vault
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.
@ -22,16 +24,217 @@ SSE also provides key functionality to regulatory and compliance requirements ar
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|.
.. Conditionals to handle the slight divergences in procedures between platforms.
.. cond:: linux
This procedure provides guidance for deploying and configuring KES at scale for a supporting |SSE| on a production MinIO deployment.
You can also use this procedure for deploying to local environments for testing and evaluation.
As part of this procedure, you will:
#. Deploy one or more |KES| servers configured to use |rootkms| as the root |KMS|.
You may optionally deploy a load balancer for managing connections to those KES servers.
#. Create a new |EK| on Vault for use with |SSE|.
#. Create or modify a MinIO deployment with support for |SSE| using |KES|.
Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
.. cond:: macos or windows
This procedure assumes a single local host machine running the MinIO and KES processes.
As part of this procedure, you will:
#. Deploy a |KES| server configured to use |rootkms-short| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO server in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.
.. cond:: container
This procedure assumes a single host machine running the MinIO and KES containers.
As part of this procedure, you will:
#. Deploy a |KES| container configured to use |rootkms-short| as the root |KMS|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Deploy a MinIO Server container in :ref:`Single-Node Single-Drive mode <minio-snsd>` configured to use the |KES| container for supporting |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.
.. cond:: k8s
This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation.
As part of this procedure, you will:
#. Use the MinIO Operator Console to create or manage a MinIO Tenant.
#. Access the :guilabel:`Encryption` settings for that tenant and configure |SSE| using |rootkms-short|.
#. Create a new |EK| on Vault for use with |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For productoin baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.
.. important::
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-encrypted-backend-desc
:end-before: end-kes-encrypted-backend-desc
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The procedures on this page *requires* a valid installation of the MinIO
Kubernetes Operator and assumes the local host has a matching installation of
the MinIO Kubernetes Operator. This procedure assumes the latest stable Operator
and Plugin version |operator-version-stable|.
See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator.
.. _minio-sse-vault-prereq-vault:
Deploy or Ensure Access to a Hashicorp Vault Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: linux or macos or windows or container
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
.. cond:: k8s
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-prereq-hashicorp-vault-desc
:end-before: end-kes-prereq-hashicorp-vault-desc
MinIO |KES| supports both the V1 and V2 Vault engines.
Select the corresponding tab to the engine used by your Vault deployment for instructions on configuring the necessary permissions:
.. tab-set::
.. tab-item:: Vault Engine 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``.
.. tab-item:: Vault Engine 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``
MinIO requires using AppRole authentication for secure communication with the Vault server.
The following commands:
- Create an App Role ID for |KES|
- Binds that role to the created KES policy
- Requests a RoleID and SecretID
.. 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
You must specify both RoleID and SecretID as part of this procedure.
.. cond:: linux or macos or windows
Deploy or Ensure Access to a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-new-existing-minio-deployment-desc
:end-before: end-kes-new-existing-minio-deployment-desc
.. cond:: container
Install Podman or a Similar Container Management Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/container/common-deploy.rst
:start-after: start-common-prereq-container-management-interface
:end-before: end-common-prereq-container-management-interface
.. The included file has the correct header structure.
There are slight divergences between platforms so this ends up being easier compared to cascading conditionals to handle little nitty-gritty differences.
.. |namespace| replace:: minio-kes-vault
.. cond:: container
.. |kescertpath| replace:: ~/minio-kes-vault/certs
.. |kesconfigpath| replace:: ~/minio-kes-vault/config
.. |kesconfigcertpath| replace:: /certs/
.. |miniocertpath| replace:: ~/minio-kes-vault/certs
.. |minioconfigpath| replace:: ~/minio-kes-vault/config
.. |miniodatapath| replace:: ~/minio-kes-vault/minio
.. include:: /includes/container/steps-configure-minio-kes-hashicorp.rst
.. cond:: linux
.. |kescertpath| replace:: /opt/kes/certs
.. |kesconfigpath| replace:: /opt/kes/config
.. |kesconfigcertpath| replace:: /opt/kes/certs/
.. |miniocertpath| replace:: /opt/minio/certs
.. |minioconfigpath| replace:: /opt/minio/config
.. |miniodatapath| replace:: ~/minio
.. include:: /includes/linux/steps-configure-minio-kes-hashicorp-quick.rst
.. include:: /includes/linux/steps-configure-minio-kes-hashicorp.rst
.. cond:: macos
.. |kescertpath| replace:: ~/minio-kes-vault/certs
.. |kesconfigpath| replace:: ~/minio-kes-vault/config/
.. |kesconfigcertpath| replace:: ~/minio-kes-vault/certs
.. |miniocertpath| replace:: ~/minio-kes-vault/certs
.. |minioconfigpath| replace:: ~/minio-kes-vault/config
.. |miniodatapath| replace:: ~/minio-kes-vault/minio
.. include:: /includes/macos/steps-configure-minio-kes-hashicorp.rst
.. cond:: k8s
@ -40,8 +243,16 @@ The root KMS provides stateful and secured storage of External Keys (EK) while |
.. cond:: windows
.. |kescertpath| replace:: C:\\minio-kes-vault\\certs
.. |kesconfigpath| replace:: C:\\minio-kes-vault\\config
.. |kesconfigcertpath| replace:: C:\\minio-kes-vault\\certs\\
.. |miniocertpath| replace:: C:\\minio-kes-vault\\certs
.. |minioconfigpath| replace:: C:\\minio-kes-vault\\config
.. |miniodatapath| replace:: C:\\minio-kes-vault\\minio
.. include:: /includes/windows/steps-configure-minio-kes-hashicorp.rst
.. Procedure for K8s only, for adding KES to an existing Tenant
Configuration Reference for Hashicorp Vault
-------------------------------------------
@ -106,27 +317,27 @@ using Hashicorp Vault as the root Key Management Service (KMS) for |SSE|:
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/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
- .. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc