mirror of
https://github.com/minio/docs.git
synced 2025-07-30 07:03:26 +03:00
DOCS-IA: Platformize SSE Docs. Hashicorp Pass (#518)
* Platformization of Data Encryption Docs: Hashicorp Pass * Platformization of Data Encryption Docs: Hashicorp Pass * Big pass, CR changes + K8s
This commit is contained in:
Ravind Kumar
GitHub
@ -19,7 +19,14 @@ This feature allows access to :ref:`erasure coding dependent features <minio-era
|
||||
MinIO only starts in |SNSD| mode if the storage volume or path is empty *or* only contain files generated by a previous |SNSD| deployment.
|
||||
See the documentation on :ref:`SNSD behavior with pre-existing data <minio-snsd-pre-existing-data>` for more information.
|
||||
|
||||
For extended development or production environments, deploy MinIO in :guilabel:`Distributed Mode`. See :ref:`deploy-minio-distributed </operations/install-deploy-manage/multi-site-replication>` for more information.
|
||||
.. cond:: container
|
||||
|
||||
For extended development or production environments in orchestrated environments, use the MinIO Kubernetes Operator to deploy a Tenant on multiple worker nodes.
|
||||
|
||||
.. cond:: linux
|
||||
|
||||
For extended development or production environments, deploy MinIO in a :ref:`Multi-Node Multi-Drive (Distributed) <minio-mnmd>` topology
|
||||
|
||||
|
||||
.. _minio-snsd-pre-existing-data:
|
||||
|
||||
|
||||
@ -16,279 +16,32 @@ Server-Side Object Encryption with Hashicorp Vault Root KMS
|
||||
.. |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 Server-Side Encryption (SSE) protects objects as part of write operations, allowing clients to take advantage of server processing power to secure objects at the storage layer (encryption-at-rest).
|
||||
SSE also provides key functionality to regulatory and compliance requirements around secure locking and erasure.
|
||||
|
||||
MinIO SSE uses |KES-git| and an
|
||||
external root Key Management Service (KMS) for performing secured cryptographic
|
||||
operations at scale. The root KMS provides stateful and secured storage of
|
||||
External Keys (EK) while |KES| is stateless and derives additional cryptographic
|
||||
keys from the root-managed |EK|.
|
||||
MinIO SSE uses |KES-git| and an external root Key Management Service (KMS) for performing secured cryptographic operations at scale.
|
||||
The root KMS provides stateful and secured storage of External Keys (EK) while |KES| is stateless and derives additional cryptographic keys from the root-managed |EK|.
|
||||
|
||||
This procedure does the following:
|
||||
.. cond:: container
|
||||
|
||||
- Configure |KES| to use
|
||||
`Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
|
||||
.. include:: /includes/container/steps-configure-minio-kes-hashicorp.rst
|
||||
|
||||
- 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>`.
|
||||
.. cond:: linux
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
.. include:: /includes/linux/steps-configure-minio-kes-hashicorp.rst
|
||||
|
||||
.. _minio-sse-vault-prereq-vault:
|
||||
.. cond:: macos
|
||||
|
||||
Hashicorp Vault
|
||||
~~~~~~~~~~~~~~~
|
||||
.. include:: /includes/macos/steps-configure-minio-kes-hashicorp.rst
|
||||
|
||||
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.
|
||||
.. cond:: k8s
|
||||
|
||||
MinIO specifically requires the following Vault settings or configurations:
|
||||
.. include:: /includes/k8s/steps-configure-minio-kes-hashicorp.rst
|
||||
|
||||
- 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.
|
||||
.. cond:: windows
|
||||
|
||||
- For K/V v1, create an access policy ``kes-policy.hcl`` with a configuration
|
||||
similar to the following:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
.. include:: /includes/windows/steps-configure-minio-kes-hashicorp.rst
|
||||
|
||||
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
|
||||
-------------------------------------------
|
||||
|
||||
Reference in New Issue
Block a user