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
@ -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>`
|
||||
@ -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>`
|
||||
@ -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>`.
|
||||
@ -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).
|
||||
Reference in New Issue
Block a user