1
0
mirror of https://github.com/minio/docs.git synced 2025-07-31 18:04:52 +03:00

Docs Multiplatform Slice

This commit is contained in:
Ravind Kumar
2022-05-06 16:44:42 -04:00
parent df33ddee6a
commit b99c20a16f
134 changed files with 3689 additions and 2200 deletions

View File

@ -0,0 +1,382 @@
.. _minio-sse-aws:
===============================================
Server-Side Object Encryption with AWS Root KMS
===============================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. |EK| replace:: :abbr:`EK (External Key)`
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
.. |KMS| replace:: :abbr:`KMS (Key Management System)`
.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) <kes>`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses |KES-git| and an
external root Key Management Service (KMS) for performing secured cryptographic
operations at scale. The root KMS provides stateful and secured storage of
External Keys (EK) while |KES| is stateless and derives additional cryptographic
keys from the root-managed |EK|.
This procedure does the following:
- Configure |KES| to use
`AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`__ as the root
|KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-aws-prereq-aws:
AWS Key Management Service
~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`AWS Key Management Service <https://aws.amazon.com/kms/>`__ and
`AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`__.
The `Getting Started with AWS Key Management Service
<https://aws.amazon.com/kms/getting-started/>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following AWS settings or
configurations:
- A new AWS
:aws-docs:`Programmatic Access <IAM/latest/UserGuide/id_users_create.html>`
user with corresponding access key and secret key.
- A policy that grants the created user access to AWS Secrets Manager and
AWS KMS. The following policy grants the minimum necessary permissions:
.. code-block:: json
:class: copyable
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "minioSecretsManagerAccess",
"Action": [
"secretsmanager:CreateSecret",
"secretsmanager:DeleteSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:ListSecrets"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "minioKmsAccess",
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:Encrypt"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
AWS provides the ``SecretsManagerReadWrite`` and
``AWSKeyManagementServicePowerUser`` canned roles that meet and exceed the
minimum required permissions.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
Enable MinIO Server-Side Encryption with AWS Root KMS
-----------------------------------------------------
The following steps deploy |KES-git| configured to use an existing AWS KMS and
Secrets Manager deployment as the root KMS for supporting |SSE|. These steps
assume the AWS components meet the :ref:`prerequisites
<minio-sse-aws-prereq-aws>`.
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
mkdir -P ~/kes/certs ~/kes/config
1) Download the MinIO Key Encryption Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate the TLS Private and Public Key for KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Generate the TLS Private and Public Key for MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-minio-certs-desc
:end-before: end-kes-generate-minio-certs-desc
4) Create the KES Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|KES| uses a YAML-formatted configuration file. The following example YAML
specifies the minimum required fields for enabling |SSE| using AWS Secrets
Manager:
.. code-block:: shell
:class: copyable
address: 0.0.0.0:7373
# Disable the root identity, as we do not need that level of access for
# supporting SSE operations.
root: disabled
# Specify the TLS keys generated in the previous step here
# For production environments, use keys signed by a known and trusted
# Certificate Authority (CA).
tls:
key: /data/certs/server.key
cert: /data/certs/server.cert
# Create a policy named 'minio' that grants access to the
# /create, /generate, and /decrypt KES APIs for any key name
# KES uses mTLS to grant access to this policy, where only the client
# whose TLS certificate hash matches one of the "identities" can
# use this policy. Specify the hash of the MinIO server TLS certificate
# hash here.
policy:
minio:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
# Specify the connection information for the KMS and Secrets Manager endpoint.
# The endpoint should be resolvable from the host.
# This example assumes that the associated AWS account has the necessary
# access key and secret key
keystore:
secretsmanager:
endpoint: secretsmanager.REGION.amazonaws # use the Secrets Manager endpoint for your region
region: REGION # e.g. us-east-1
kmskey: "" # Optional. The root AWS KMS key to use for cryptographic operations. Formerly described as the "Customer Master Key".
credentials:
accesskey: "${AWSACCESSKEY}" # AWS Access Key
secretkey: "${AWSSECRETKEY}" # AWS Secret Key
Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
value ``${VARIABLE}`` uses the environment variable with matching name as the
value. You can use this functionality to set credentials without writing them to
the configuration file.
- Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``.
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``.
- Set ``AWSACCESSKEY`` and ``AWSSECRETKEY`` to the appropriate
:ref:`AWS Credentials <minio-sse-aws-prereq-aws>`.
5) Start KES
~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-run-server-desc
:end-before: end-kes-run-server-desc
6) Generate a Cryptographic Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: SSE-KMS
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
.. tab-item:: SSE-S3
The following command enables SSE-S3 on all objects written to the
specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
key for performing |SSE|.
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
Configuration Reference for AWS Root KMS
----------------------------------------
The following section describes each of the |KES-git| configuration settings for
using AWS Secrets Manager and AWS KMS as the root Key Management Service
(KMS) for |SSE|:
.. tab-set::
.. tab-item:: YAML Overview
The following YAML describes the minimum required fields for configuring
AWS Secrets Manager as an external KMS for supporting |SSE|.
Any field with value ``${VARIABLE}`` uses the environment variable
with matching name as the value. You can use this functionality to set
credentials without writing them to the configuration file.
.. code-block:: yaml
address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}
tls:
key: kes-server.key
cert: kes-server.cert
policy:
minio-server:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY}
keys:
- name: "minio-encryption-key-alpha"
- name: "minio-encryption-key-baker"
- name: "minio-encryption-key-charlie"
keystore:
secretsmanager:
endpoint: secretsmanager.REGION.amazonaws
region: REGION
kmskey: ""
credentials:
accesskey: "${AWS_ACCESS_KEY}"
secretkey: "${AWS_SECRET_KEY}"
.. tab-item:: Reference
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Key
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-address-desc
:end-before: end-kes-conf-address-desc
* - ``root``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-root-desc
:end-before: end-kes-conf-root-desc
* - ``tls``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-tls-desc
:end-before: end-kes-conf-tls-desc
* - ``policy``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-policy-desc
:end-before: end-kes-conf-policy-desc
* - ``keys``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc
* - ``keystore.secretsmanager``
- The configuration for the AWS Secrets Manager and AWS KMS.
- ``endpoint`` - The endpoint for the Secrets Manager service,
including the region.
- ``approle`` - The AWS region to use for other AWS services.
- ``kmskey`` - The root KMS Key to use for cryptographic
operations. Formerly known as the Customer Master Key.
- ``credentials`` - The AWS Credentials to use for performing
authenticated operations against Secrets Manager and KMS.
The specified credentials *must* have the appropriate
:ref:`permissions <minio-sse-aws-prereq-aws>`

View File

@ -0,0 +1,355 @@
.. _minio-sse-azure:
===========================================================
Server-Side Object Encryption with Azure Key Vault Root KMS
===========================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. |EK| replace:: :abbr:`EK (External Key)`
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
.. |KMS| replace:: :abbr:`KMS (Key Management System)`
.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) <kes>`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses |KES-git| and an
external root Key Management Service (KMS) for performing secured cryptographic
operations at scale. The root KMS provides stateful and secured storage of
External Keys (EK) while |KES| is stateless and derives additional cryptographic
keys from the root-managed |EK|.
This procedure does the following:
- Configure |KES| to use
`Azure Key Vault
<https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__
as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-azure-prereq-azure:
Azure Key Vault
~~~~~~~~~~~~~~~
This procedure assumes familiarity with `Azure Key Vault
<https://azure.microsoft.com/en-us/services/key-vault/#product-overview>`__. The
`Key Vault Quickstart
<https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following Azure settings or
configurations:
- `Register an application <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>`__
for |KES| (e.g. ``minio-kes``). Note the :guilabel:`Application (client) ID`,
:guilabel:`Directory (tenant) ID`, and :guilabel:`Client credentials`.
You may need to create the client credentials secret and copy the
:guilabel:`Secret Value` for use in this procedure.
- Create an `Access Policy <https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal>`__
for use by KES. The policy **must** have the following
:guilabel:`Secret Permissions`:
- ``Get``
- ``List``
- ``Set``
- ``Delete``
- ``Purge``
Set the :guilabel:`Principal` for the new policy to the KES Application ID.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
Enable MinIO Server-Side Encryption with Azure Key Vault Root KMS
-----------------------------------------------------------------
The following steps deploy |KES-git| configured to use an existing AWS KMS and
Key Vault deployment as the root KMS for supporting |SSE|. These steps
assume the AWS components meet the :ref:`prerequisites
<minio-sse-azure-prereq-azure>`.
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
mkdir -P ~/kes/certs ~/kes/config
1) Download the MinIO Key Encryption Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate the TLS Private and Public Key for KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Generate the TLS Private and Public Key for MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-minio-certs-desc
:end-before: end-kes-generate-minio-certs-desc
4) Create the KES Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|KES| uses a YAML-formatted configuration file. The following example YAML
specifies the minimum required fields for enabling |SSE| using AWS Secrets
Manager:
.. code-block:: shell
:class: copyable
address: 0.0.0.0:7373
# Disable the root identity, as we do not need that level of access for
# supporting SSE operations.
root: disabled
# Specify the TLS keys generated in the previous step here
# For production environments, use keys signed by a known and trusted
# Certificate Authority (CA).
tls:
key: /data/certs/server.key
cert: /data/certs/server.cert
# Create a policy named 'minio' that grants access to the
# /create, /generate, and /decrypt KES APIs for any key name
# KES uses mTLS to grant access to this policy, where only the client
# whose TLS certificate hash matches one of the "identities" can
# use this policy. Specify the hash of the MinIO server TLS certificate
# hash here.
policy:
minio:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
# Specify the connection information for the Key Vualt endpoint.
# The endpoint should be resolvable from the host.
# This example assumes that the specified Key Vault and Azure tenant/client
# have the necessary permissions set.
keystore:
azure:
keyvault:
endpoint: "https://<keyvaultinstance>vault.azure.net" # The Azure Keyvault Instance Endpoint
credentials:
tenant_id: "${TENANTID}" # The directory/tenant UUID
client_id: "${CLIENTID}" # The application/client UUID
client_secret: "${CLIENTSECRET}" # The Active Directory secret for the application
Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
value ``${VARIABLE}`` uses the environment variable with matching name as the
value. You can use this functionality to set credentials without writing them to
the configuration file.
- Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``.
- Replace the ``endpoint`` with the URL for the Keyvault instance.
- Set ``TENANTID``, ``CLIENTID``, and ``CLIENTSECRET`` to match the credentials
for a project user with
the :ref:`required permissions <minio-sse-azure-prereq-azure>`.
5) Start KES
~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-run-server-desc
:end-before: end-kes-run-server-desc
6) Generate a Cryptographic Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: SSE-KMS
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
.. tab-item:: SSE-S3
The following command enables SSE-S3 on all objects written to the
specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
key for performing |SSE|.
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
Configuration Reference for Azure Key Vault Root KMS
----------------------------------------------------
The following section describes each of the |KES-git| configuration settings for
using Azure Key Vault as the root Key Management Service
(KMS) for |SSE|:
.. tab-set::
.. tab-item:: YAML Overview
The following YAML describes the minimum required fields for configuring
Azure Key Vault as an external KMS for supporting |SSE|.
Any field with value ``${VARIABLE}`` uses the environment variable
with matching name as the value. You can use this functionality to set
credentials without writing them to the configuration file.
.. code-block:: yaml
address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}
tls:
key: kes-server.key
cert: kes-server.cert
policy:
minio-server:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY}
keys:
- name: "minio-encryption-key-alpha"
- name: "minio-encryption-key-baker"
- name: "minio-encryption-key-charlie"
keystore:
azure:
keyvault:
endpoint: "https://<keyvaultinstance>.vault.azure.net"
credentials:
tenant_id: "${TENANTID}" # The directory/tenant UUID
client_id: "${CLIENTID}" # The application/client UUID
client_secret: "${CLIENTSECRET}" # The Active Directory secret for the application
.. tab-item:: Reference
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Key
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-address-desc
:end-before: end-kes-conf-address-desc
* - ``root``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-root-desc
:end-before: end-kes-conf-root-desc
* - ``tls``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-tls-desc
:end-before: end-kes-conf-tls-desc
* - ``policy``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-policy-desc
:end-before: end-kes-conf-policy-desc
* - ``keys``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc
* - ``keystore.azure.keyvault``
- The configuration for the Azure Key Vault
- ``endpoint`` - The hostname for the Key Vault service.
- ``credentials`` - Replace the ``credentials`` with the
credentials for the Active Directory application as which KES
authenticates.
The specified credentials must have the appropriate
:ref:`permissions <minio-sse-azure-prereq-azure>`

View File

@ -0,0 +1,353 @@
.. _minio-sse-gcp:
==============================================================
Server-Side Object Encryption with GCP Secret Manager Root KMS
==============================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. |EK| replace:: :abbr:`EK (External Key)`
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
.. |KMS| replace:: :abbr:`KMS (Key Management System)`
.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) <kes>`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses |KES-git| and an
external root Key Management Service (KMS) for performing secured cryptographic
operations at scale. The root KMS provides stateful and secured storage of
External Keys (EK) while |KES| is stateless and derives additional cryptographic
keys from the root-managed |EK|.
This procedure does the following:
- Configure |KES| to use
`Google Cloud Platform Secret Manager
<https://cloud.google.com/secret-manager/>`__ as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-gcp-prereq-gcp:
GCP Secret Manager
~~~~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`GCP Secret Manager <https://cloud.google.com/secret-manager>`__.
The `Secret Manager Quickstart
<https://cloud.google.com/secret-manager/docs/quickstart>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following GCP settings or
configurations:
- `Enable Secret Manager <https://cloud.google.com/secret-manager/docs/configuring-secret-manager>`__
in the project.
- Create a new GCP Service Account for supporting |KES|. Ensure the user has
a role with *at minimum* the following permissions:
.. code-block:: text
:class: copyable
secretmanager.secrets.create
secretmanager.secrets.delete
secretmanager.secrets.get
The ``Secret manager Admin`` role meets the minimum required permissions.
GCP should return a set of credentials associated to the new service account,
including private keys. Copy these credentials to a safe and secure location
for use with this procedure.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
Enable MinIO Server-Side Encryption with GCP Secret Manager Root KMS
--------------------------------------------------------------------
The following steps deploy |KES-git| configured to use an existing AWS KMS and
Secrets Manager deployment as the root KMS for supporting |SSE|. These steps
assume the AWS components meet the :ref:`prerequisites
<minio-sse-gcp-prereq-gcp>`.
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
mkdir -P ~/kes/certs ~/kes/config
1) Download the MinIO Key Encryption Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate the TLS Private and Public Key for KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Generate the TLS Private and Public Key for MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-minio-certs-desc
:end-before: end-kes-generate-minio-certs-desc
4) Create the KES Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|KES| uses a YAML-formatted configuration file. The following example YAML
specifies the minimum required fields for enabling |SSE| using AWS Secrets
Manager:
.. code-block:: shell
:class: copyable
address: 0.0.0.0:7373
# Disable the root identity, as we do not need that level of access for
# supporting SSE operations.
root: disabled
# Specify the TLS keys generated in the previous step here
# For production environments, use keys signed by a known and trusted
# Certificate Authority (CA).
tls:
key: /data/certs/server.key
cert: /data/certs/server.cert
# Create a policy named 'minio' that grants access to the
# /create, /generate, and /decrypt KES APIs for any key name
# KES uses mTLS to grant access to this policy, where only the client
# whose TLS certificate hash matches one of the "identities" can
# use this policy. Specify the hash of the MinIO server TLS certificate
# hash here.
policy:
minio:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
# Specify the connection information for the Secrets Manager endpoint.
# The endpoint should be resolvable from the host.
# This example assumes that the associated GCP account has the necessary
# access key and secret key
keystore:
gcp:
secretmanager:
project_id: "${GCPPROJECTID}" # The GCP Project to use
credentials:
client_email: "${GCPCLIENTEMAIL}" # The client email for your GCP Credentials
client_id: "${GCPCLIENTID}" # The Client ID for your GCP Credentials
private_key_id: "${GCPPRIVATEKEYID}" # the private key ID for your GCP credentials
private_key: "${GCPPRIVATEKEY}" # The content of your GCP Private Key
Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
value ``${VARIABLE}`` uses the environment variable with matching name as the
value. You can use this functionality to set credentials without writing them to
the configuration file.
- Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``.
- Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance
KES should use.
- Set ``GCPCLIENTEMAIL``, ``GCPCLIENTID``, ``GCPPRIVATEKEYID``, and
``GCPPRIVATEKEY`` to the credentials associated to the
:ref:`GCP Service Account <minio-sse-gcp-prereq-gcp>`
KES should use when accessing the Secrets Manager service.
5) Start KES
~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-run-server-desc
:end-before: end-kes-run-server-desc
6) Generate a Cryptographic Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: SSE-KMS
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
.. tab-item:: SSE-S3
The following command enables SSE-S3 on all objects written to the
specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
key for performing |SSE|.
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
Configuration Reference for GCP Secret Manager Root KMS
-------------------------------------------------------
The following section describes each of the |KES-git| configuration settings for
using GCP Secrets Manager as the root Key Management Service
(KMS) for |SSE|:
.. tab-set::
.. tab-item:: YAML Overview
The following YAML describes the minimum required fields for configuring
GCP Secret Manager as an external KMS for supporting |SSE|.
Any field with value ``${VARIABLE}`` uses the environment variable
with matching name as the value. You can use this functionality to set
credentials without writing them to the configuration file.
.. code-block:: yaml
address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}
tls:
key: kes-server.key
cert: kes-server.cert
policy:
minio-server:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY}
keys:
- name: "minio-encryption-key-alpha"
- name: "minio-encryption-key-baker"
- name: "minio-encryption-key-charlie"
keystore:
gcp:
secretmanager:
project_id: "${GCPPROJECTID}"
credentials:
client_email: "${GCPCLIENTEMAIL}"
client_id: "${GCPCLIENTID}"
private_key_id: "${GCPPRIVATEKEYID}"
private_key: "${GCPPRIVATEKEY}"
.. tab-item:: Reference
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Key
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-address-desc
:end-before: end-kes-conf-address-desc
* - ``root``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-root-desc
:end-before: end-kes-conf-root-desc
* - ``tls``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-tls-desc
:end-before: end-kes-conf-tls-desc
* - ``policy``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-policy-desc
:end-before: end-kes-conf-policy-desc
* - ``keys``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc
* - ``keystore.gcp.secretmanager``
- The configuration for the GCP Secret Manager
- ``project_id`` - The GCP Project of the Secret Manager instance.
- ``credentials`` - Replace the ``credentials`` with the
credentials for a project user with the
:ref:`required permissions <minio-sse-gcp-prereq-gcp>`.

View File

@ -0,0 +1,397 @@
.. _minio-sse-vault:
===========================================================
Server-Side Object Encryption with Hashicorp Vault Root KMS
===========================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. |EK| replace:: :abbr:`EK (External Key)`
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
.. |KMS| replace:: :abbr:`KMS (Key Management System)`
.. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) <kes>`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses |KES-git| and an
external root Key Management Service (KMS) for performing secured cryptographic
operations at scale. The root KMS provides stateful and secured storage of
External Keys (EK) while |KES| is stateless and derives additional cryptographic
keys from the root-managed |EK|.
This procedure does the following:
- Configure |KES| to use
`Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
- Configure MinIO to use the |KES| instance for supporting |SSE|.
- Configure automatic bucket-default
:ref:`SSE-KMS <minio-encryption-sse-kms>` and
:ref:`SSE-S3 <minio-encryption-sse-s3>`.
Prerequisites
-------------
.. _minio-sse-vault-prereq-vault:
Hashicorp Vault
~~~~~~~~~~~~~~~
This procedure assumes familiarity with
`Hashicorp Vault <https://www.vaultproject.io/>`__. The
Vault `Quick Start
<https://learn.hashicorp.com/tutorials/vault/getting-started-install>`__
provides a sufficient foundation for the purposes of this procedure.
MinIO specifically requires the following Vault settings or configurations:
- Enable the Vault K/V engine. KES version 0.15.0 and later support both the
v1 and v2 engines. This procedure uses the v1 engine.
- For K/V v1, create an access policy ``kes-policy.hcl`` with a configuration
similar to the following:
.. code-block:: shell
:class: copyable
path "kv/*" {
capabilities = [ "create", "read", "delete" ]
}
Write the policy to Vault using
``vault policy write kes-policy kes-policy.hcl``.
- For K/V v2, create an access policy ``kes-policy.hcl`` with a configuration
similar to the following:
.. code-block:: shell
:class: copyable
path "kv/data/*" {
capabilities = [ "create", "read"]
path "kv/metadata/*" {
capabilities = [ "list", "delete"]
Write the policy to Vault using
``vault policy write kes-policy kes-policy.hcl``
- Enable Vault AppRole authentication, create an AppRole ID, bind it to
the necessary policy, and request both roleID and secret ID.
.. code-block:: shell
:class: copyable
vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m
vault write auth/approle/role/kes-role policies=kes-policy
vault read auth/approle/role/kes-role/role-id
vault write -f auth/approle/role/kes-role/secret-id
The instructions on this page include configuring and starting Vault for
supporting development/evaluation of MinIO |SSE|. **DO NOT** use these
instructions for deploying Vault for any long-term development or production
environments. Extended development and production environments should defer to
the `Vault Documentation <https://learn.hashicorp.com/vault>`__ for specific
guidance on deployment and configuration.
Network Encryption (TLS)
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-network-encryption-desc
:end-before: end-kes-network-encryption-desc
Podman Container Manager
~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-podman-desc
:end-before: end-kes-podman-desc
Enable MinIO Server-Side Encryption with Hashicorp Vault
--------------------------------------------------------
The following steps deploy |KES-git| configured to use an existing Hashicorp
Vault deployment as the root KMS for supporting |SSE|. These steps assume the
Vault deployment meets the :ref:`prerequisites <minio-sse-vault-prereq-vault>`.
Prior to starting these steps, create the following folders:
.. code-block:: shell
:class: copyable
mkdir -P ~/kes/certs ~/kes/config
1) Download the MinIO Key Encryption Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
2) Generate the TLS Private and Public Key for KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-kes-certs-desc
:end-before: end-kes-generate-kes-certs-desc
3) Generate the TLS Private and Public Key for MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-minio-certs-desc
:end-before: end-kes-generate-minio-certs-desc
4) Create the KES Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|KES| uses a YAML-formatted configuration file. The following example YAML
specifies the minimum required fields for enabling |SSE| using Hashicorp Vault:
.. code-block:: shell
:class: copyable
address: 0.0.0.0:7373
# Disable the root identity, as we do not need that level of access for
# supporting SSE operations.
root: disabled
# Specify the TLS keys generated in the previous step here
# For production environments, use keys signed by a known and trusted
# Certificate Authority (CA).
tls:
key: /data/certs/server.key
cert: /data/certs/server.cert
# Create a policy named 'minio' that grants access to the
# /create, /generate, and /decrypt KES APIs for any key name
# KES uses mTLS to grant access to this policy, where only the client
# whose TLS certificate hash matches one of the "identities" can
# use this policy. Specify the hash of the MinIO server TLS certificate
# hash here.
policy:
minio:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert'
# Specify the connection information for the Vault server.
# The endpoint should be resolvable from the host.
# This example assumes that Vault is configured with an AppRole ID and
# Secret for use with KES.
keystore:
vault:
endpoint: https://HOSTNAME:8200
approle:
id: "${VAULTAPPID}" # Hashicorp Vault AppRole ID
secret: "${VAULTAPPSECRET}" # Hashicorp Vault AppRole Secret ID
retry: 15s
status:
ping: 10s
# Required if Vault uses certificates signed by an unknown CA,
# e.g. self-signed or internal (non-globally trusted).
tls:
ca: vault-tls.cert
Save the configuration file as ``~/kes/config/kes-config.yaml``. Any field with
value ``${VARIABLE}`` uses the environment variable with matching name as the
value. You can use this functionality to set credentials without writing them to
the configuration file.
- Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``.
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate
:ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
5) Start KES
~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-run-server-desc
:end-before: end-kes-run-server-desc
6) Generate a Cryptographic Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
You can check the newly created key on the Vault server by running the
``vault kv list kv/`` command, where ``kv/`` is the path to the vault storing
|KES|-generated keys.
7) Configure MinIO to connect to KES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-kes.rst
:start-after: start-kes-configure-minio-desc
:end-before: end-kes-configure-minio-desc
8) Enable Automatic Server-Side Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: SSE-KMS
The following command enables SSE-KMS on all objects written to the
specified bucket:
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
.. tab-item:: SSE-S3
The following command enables SSE-S3 on all objects written to the
specified bucket. MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME`
key for performing |SSE|.
.. code-block:: shell
:class: copyable
mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket
Replace ``ALIAS`` with the :mc:`alias <mc alias>` of the MinIO
deployment configured in the previous step.
Write a file to the bucket using :mc:`mc cp` or any S3-compatible
SDK with a ``PutObject`` function. You can then run :mc:`mc stat`
on the file to confirm the associated encryption metadata.
Configuration Reference for Hashicorp Vault
-------------------------------------------
The following section describes each of the |KES-git| configuration settings for
using Hashicorp Vault as the root Key Management Service (KMS) for |SSE|:
.. tab-set::
.. tab-item:: YAML Overview
The following YAML describes the minimum required fields for configuring
Hashicorp Vault as an external KMS for supporting |SSE|.
Any field with value ``${VARIABLE}`` uses the environment variable
with matching name as the value. You can use this functionality to set
credentials without writing them to the configuration file.
.. code-block:: yaml
address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}
tls:
key: kes-server.key
cert: kes-server.cert
policy:
minio-server:
allow:
- /v1/key/create/*
- /v1/key/generate/*
- /v1/key/decrypt/*
identities:
- ${MINIO_IDENTITY}
keys:
- name: "minio-encryption-key-alpha"
- name: "minio-encryption-key-baker"
- name: "minio-encryption-key-charlie"
keystore:
vault:
endpoint: https://vault.example.net:8200
approle:
id: ${KES_APPROLE_ID}
secret: ${KES_APPROLE_SECRET}
retry: 15s
status:
ping: 10s
tls:
ca: vault-tls.cert
.. tab-item:: Reference
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Key
- Description
* - ``address``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-address-desc
:end-before: end-kes-conf-address-desc
* - ``root``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-root-desc
:end-before: end-kes-conf-root-desc
* - ``tls``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-tls-desc
:end-before: end-kes-conf-tls-desc
* - ``policy``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-policy-desc
:end-before: end-kes-conf-policy-desc
* - ``keys``
- .. include:: /includes/common-minio-kes.rst
:start-after: start-kes-conf-keys-desc
:end-before: end-kes-conf-keys-desc
* - ``keystore.vault``
- The configuration for the Hashicorp Vault keystore. The following
fields are *required*:
- ``endpoint`` - The hostname for the vault server(s). The
hostname *must* be resolvable by the KES server host.
- ``approle`` - The `AppRole
<https://www.vaultproject.io/docs/auth/approle>`__ used by
KES for performing authenticated operations against Vault.
The specified AppRole must have the
appropriate :ref:`permissions <minio-sse-vault-prereq-vault>`
- ``tls.ca`` - The Certificate Authority used to sign the
Vault TLS certificates. Typically required if the Vault
server uses self-signed certificates *or* is signed by an unknown
CA (internal or non-global).