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

Updates for mc RELEASE.2024-06-20T14-50-54Z (#1279)

Updates for mc release 2024-06-20T14-50-54Z
    
- Adds info about requiring Raw Base64 or Hex keys
- Updates links for KES docs on encryption pages
- Updates encryption pages to use ventilated prose (one sentence per
line)
- Adds new flag for `mc get`
- Updates `mc put` with enc-# flags
    
Closes #1253
This commit is contained in:
Daryl White
2024-07-25 12:31:28 -04:00
committed by GitHub
parent cb658261c8
commit 848b5b7d34
6 changed files with 136 additions and 159 deletions

View File

@ -76,35 +76,34 @@ Encrypting an object using SSE-C prevents MinIO from applying
Quickstart
----------
MinIO SSE-C requires the client to perform all key creation and storage
operations.
MinIO SSE-C requires the client to perform all key creation and storage operations.
This procedure uses :mc:`mc` for performing operations on the source MinIO
deployment. Install :mc:`mc` on a machine with network access to the source
deployment. See the ``mc`` :ref:`Installation Quickstart <mc-install>` for
instructions on downloading and installing ``mc``.
This procedure uses :mc:`mc` for performing operations on the source MinIO deployment.
Install :mc:`mc` on a machine with network access to the source deployment.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
The SSE-C key *must* be a 256-bit base64-encoded string. The client
application is responsible for generation and storage of the encryption key.
MinIO does *not* store SSE-C encryption keys and cannot decrypt SSE-C
encrypted objects without the client-managed key.
The SSE-C key *must* be a 256-bit raw encoded string or a hex encoded string.
The client application is responsible for generation and storage of the encryption key.
MinIO does *not* store SSE-C encryption keys and cannot decrypt SSE-C encrypted objects without the client-managed key.
.. note::
Support for hex encoded keys was added in MinIO Client ``RELEASE.2024-06-20T14-50-54Z``.
1) Generate the Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generate the 256-bit base64-encoded string for use as the encryption key.
Generate the 256-bit base64 raw encoded string or a hex encoded string for use as the encryption key.
The following example generates a string that meets the encryption key
requirements. The resulting string is appropriate for non-production
environments:
The following example generates a string that meets the encryption key requirements.
The resulting string is appropriate for non-production environments:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Defer to your organizations requirements for generating cryptographically
secure encryption keys.
Defer to your organizations requirements for generating cryptographically secure encryption keys.
Copy the encryption key for use in the next step.
@ -117,8 +116,7 @@ MinIO supports the following AWS S3 headers for specifying SSE-C encryption:
- ``X-Amz-Server-Side-Encryption-Customer-Key`` set to the encryption key value.
- ``X-Amz-Server-Side-Encryption-Customer-Key-MD5`` to the 128-bit MD5 digest of
the encryption key.
- ``X-Amz-Server-Side-Encryption-Customer-Key-MD5`` to the 128-bit MD5 digest of the encryption key.
The MinIO :mc:`mc` commandline tool S3-compatible SDKs include specific syntax
for setting headers. Certain :mc:`mc` commands like :mc:`mc cp` include specific

View File

@ -18,25 +18,17 @@ Server-Side Encryption with Per-Bucket Keys (SSE-KMS)
.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO Server-Side Encryption (SSE) protects objects as part of write operations, allowing clients to take advantage of server processing power to secure objects at the storage layer (encryption-at-rest).
SSE also provides key functionality to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses the :minio-git:`MinIO Key Encryption Service (KES) <kes>` and an
external Key Management Service (KMS) for performing secured cryptographic
operations at scale. MinIO also supports client-managed key management, where
the application takes full responsibility for creating and managing encryption
keys for use with MinIO SSE.
MinIO SSE uses the :kes-docs:`MinIO Key Encryption Service (KES) <>` and a :kes-docs:`supported external Key Management Service (KMS) <#supported-kms-targets>` for performing secured cryptographic operations at scale.
MinIO also supports client-managed key management, where the application takes full responsibility for creating and managing encryption keys for use with MinIO SSE.
MinIO SSE-KMS en/decrypts objects using an External Key (EK) managed by a Key
Management System (KMS). Each bucket and object can have a separate |EK|,
supporting more granular cryptographic operations in the deployment. MinIO can
only decrypt an object if it can access both the KMS *and* the |EK| used to
encrypt that object.
MinIO SSE-KMS encrypts or decrypts objects using an External Key (EK) managed by a Key Management System (KMS).
Each bucket and object can have a separate |EK|, supporting more granular cryptographic operations in the deployment.
MinIO can only decrypt an object if it can access both the KMS *and* the |EK| used to encrypt that object.
You can enable bucket-default SSE-KMS encryption using the
:mc:`mc encrypt set` command:
You can enable bucket-default SSE-KMS encryption using the :mc:`mc encrypt set` command:
.. code-block:: shell
:class: copyable
@ -95,20 +87,15 @@ This procedure requires the following components:
instructions on downloading and installing ``mc``.
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
with internet access. See the ``kes``
:minio-git:`Getting Started <kes/wiki/Getting-Started>` guide for
instructions on downloading, installing, and configuring KES.
- Install :kes-docs:`MinIO Key Encryption Service (KES) <>` on a machine with internet access.
See the ``kes`` :kes-docs:`Getting Started <tutorials/getting-started/>` guide for instructions on downloading, installing, and configuring KES.
1) Create an Encryption Key for SSE-KMS Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :minio-git:`kes <kes>` commandline tool to create a new External Key
(EK) for use with SSE-KMS Encryption.
Use the :kes-docs:`kes <cli/>` command line tool to create a new External Key (EK) for use with SSE-KMS Encryption.
Issue the following command to retrieve the root
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>` for the KES
server:
The following command retrieves the root :kes-docs:`identity <concepts/#authorization>` for the ``play`` KES server:
.. code-block:: shell
:class: copyable
@ -131,31 +118,23 @@ Set the following environment variables in the terminal or shell:
:width: 100%
* - ``KES_CLIENT_KEY``
- The private key for an :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`. This step uses the root
identity for the MinIO ``play`` KES sandbox, which provides access
to all operations on the KES server.
- The private key for an :kes-docs:`identity <concepts/#authorization>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``, ``/v1/generate``, and ``/v1/list`` :kes-docs:`API endpoints <concepts/server-api/>`.
This step uses the ``root`` identity for the MinIO ``play`` KES sandbox, which provides access to all operations on the KES server.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
This step uses the root identity for the MinIO ``play`` KES
sandbox, which provides access to all operations on the KES server.
- The corresponding certificate for the :kes-docs:`identity <concepts/#authorization>` on the KES server.
This step uses the ``root`` identity for the MinIO ``play`` KES sandbox, which provides access to all operations on the KES server.
Issue the following command to create a new |EK| through
KES.
The following command creates a new |EK| through KES.
.. code-block:: shell
:class: copyable
kes key create my-minio-sse-kms-key
This tutorial uses the example ``my-minio-sse-kms-key`` name for ease of
reference. Specify a unique key name to prevent collision
with existing keys.
This tutorial uses the example ``my-minio-sse-kms-key`` name for ease of reference.
Specify a unique key name to prevent collision with existing keys.
2) Configure MinIO for SSE-KMS Object Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -179,26 +158,19 @@ MinIO server host in the deployment:
- The endpoint for the MinIO ``Play`` KES service.
* - :envvar:`MINIO_KMS_KES_KEY_FILE`
- The private key file corresponding to an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity key file as the ``KES_KEY_FILE`` environment variable
in the previous step.
- The private key file corresponding to an :kes-docs:`identity <concepts/#authorization>` on the KES service.
The identity must grant permission to create, generate, and decrypt keys.
Specify the same identity key file as the ``KES_KEY_FILE`` environment variable in the previous step.
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
- The public certificate file corresponding to an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
on the KES service. The identity must grant permission to
create, generate, and decrypt keys. Specify the same
identity certificate as the ``KES_CERT_FILE`` environment
variable in the previous step.
- The public certificate file corresponding to an :kes-docs:`identity <concepts/#authorization>` on the KES service.
The identity must grant permission to create, generate, and decrypt keys.
Specify the same identity certificate as the ``KES_CERT_FILE`` environment variable in the previous step.
* - :envvar:`MINIO_KMS_KES_KEY_NAME`
- The name of the External Key (EK) to use for
performing SSE encryption operations. KES retrieves the |EK| from
the configured Key Management Service (KMS). Specify the name of the
key created in the previous step.
- The name of the External Key (EK) to use for performing SSE encryption operations.
KES retrieves the |EK| from the configured Key Management Service (KMS).
Specify the name of the key created in the previous step.
3) Restart the MinIO Deployment to Enable SSE-KMS
@ -212,14 +184,12 @@ Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
mc admin service restart ALIAS
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to restart.
4) Configure Automatic Bucket Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc:`mc encrypt set` command to enable automatic SSE-KMS protection
of all objects written to a specific bucket.
Use the :mc:`mc encrypt set` command to enable automatic SSE-KMS protection of all objects written to a specific bucket.
.. code-block:: shell
:class: copyable
@ -232,12 +202,10 @@ of all objects written to a specific bucket.
- Replace :mc-cmd:`BUCKET <mc encrypt set ALIAS>` with the full path to the
bucket or bucket prefix on which you want to enable automatic SSE-KMS.
Objects written to the specified bucket are automatically encrypted using
the specified |EK|
Objects written to the specified bucket are automatically encrypted using the specified |EK|.
Repeat this step for each bucket on which you want to enable automatic
SSE-KMS encryption. You can generate additional keys per bucket or bucket
prefix, such that the scope of each |EK| is limited to a subset of objects.
Repeat this step for each bucket on which you want to enable automatic SSE-KMS encryption.
You can generate additional keys per bucket or bucket prefix, such that the scope of each |EK| is limited to a subset of objects.
.. _minio-encryption-sse-kms-erasure-locking:
@ -261,8 +229,7 @@ The scope of a single |EK| depends on:
- Which buckets specified that |EK| for automatic SSE-KMS encryption,
*and*
- Which write operations specified that |EK| when requesting SSE-KMS
encryption.
- Which write operations specified that |EK| when requesting SSE-KMS encryption.
For example, consider a MinIO deployment using one |EK| per bucket.
Disabling a single |EK| renders all objects in the associated bucket

View File

@ -23,7 +23,7 @@ allowing clients to take advantage of server processing power to secure objects
at the storage layer (encryption-at-rest). SSE also provides key functionality
to regulatory and compliance requirements around secure locking and erasure.
MinIO SSE uses the :minio-git:`MinIO Key Encryption Service (KES) <kes>` and an
MinIO SSE uses the :kes-docs:`MinIO Key Encryption Service (KES) <>` and an
external Key Management Service (KMS) for performing secured cryptographic
operations at scale. MinIO also supports client-managed key management, where
the application takes full responsibility for creating and managing encryption
@ -34,8 +34,7 @@ Key Management System (KMS). You must specify the |EK| using the
:envvar:`MINIO_KMS_KES_KEY_NAME` environment variable when starting up the
MinIO server. MinIO uses the same EK for *all* SSE-S3 cryptographic operations.
You can enable bucket-default SSE-S3 encryption using the
:mc:`mc encrypt set` command:
You can enable bucket-default SSE-S3 encryption using the :mc:`mc encrypt set` command:
.. code-block:: shell
:class: copyable
@ -45,16 +44,15 @@ You can enable bucket-default SSE-S3 encryption using the
- Replace ``play/mybucket`` with the :mc:`alias <mc alias>` and bucket
on which you want to enable automatic SSE-KMS encryption.
MinIO SSE-S3 is functionally compatible with AWS S3
:s3-docs:`Server-Side Encryption with Amazon S3-Managed Keys
<UsingServerSideEncryption.html>` while expanding support to include the
following KMS providers:
MinIO SSE-S3 is functionally compatible with AWS S3 :s3-docs:`Server-Side Encryption with Amazon S3-Managed Keys <UsingServerSideEncryption.html>` while expanding support to include the following KMS providers:
- :ref:`AWS SecretsManager <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`HashiCorp KeyVault <minio-sse-vault>`
- Thales CipherTrust (formerly Gemalto KeySecure)
- :kes-docs:`AWS Secrets Manager <integrations/aws-secrets-manager/>`
- :kes-docs:`Azure KeyVault <integrations/azure-keyvault/>`
- :kes-docs:`Entrust KeyControl <integrations/entrust-keycontrol/>`
- :kes-docs:`Fortanix SDKMS <integrations/fortanix-sdkms/>`
- :kes-docs:`Google Cloud Secret Manager <integrations/google-cloud-secret-manager/>`
- :kes-docs:`HashiCorp Vault <integrations/hashicorp-vault-keystore/>`
- :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) <integrations/thales-ciphertrust/>`
.. _minio-encryption-sse-s3-quickstart:
@ -73,11 +71,13 @@ supporting |SSE| with SSE-S3 in evaluation and early development environments.
For extended development or production environments, use one of the following
supported external Key Management Services (KMS):
- :ref:`AWS SecretsManager <minio-sse-aws>`
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
- :ref:`Azure Key Vault <minio-sse-azure>`
- :ref:`HashiCorp KeyVault <minio-sse-vault>`
- Thales CipherTrust (formerly Gemalto KeySecure)
- :kes-docs:`AWS Secrets Manager <integrations/aws-secrets-manager/>`
- :kes-docs:`Azure KeyVault <integrations/azure-keyvault/>`
- :kes-docs:`Entrust KeyControl <integrations/entrust-keycontrol/>`
- :kes-docs:`Fortanix SDKMS <integrations/fortanix-sdkms/>`
- :kes-docs:`Google Cloud Secret Manager <integrations/google-cloud-secret-manager/>`
- :kes-docs:`HashiCorp Vault <integrations/hashicorp-vault-keystore/>`
- :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) <integrations/thales-ciphertrust/>`
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-play-sandbox-warning
@ -85,26 +85,19 @@ supported external Key Management Services (KMS):
This procedure requires the following components:
- Install :mc:`mc` on a machine with network access to the source
deployment. See the ``mc`` :ref:`Installation Quickstart <mc-install>` for
instructions on downloading and installing ``mc``.
- Install :mc:`mc` on a machine with network access to the source deployment.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
with internet access. See the ``kes``
:minio-git:`Getting Started <kes/wiki/Getting-Started>` guide for
instructions on downloading, installing, and configuring KES.
- Install :kes-docs:`MinIO Key Encryption Service (KES) <>` on a machine with internet access.
See the KES :kes-docs:`Getting Started <tutorials/getting-started/>` guide for instructions on downloading, installing, and configuring KES.
1) Create an Encryption Key for SSE-S3 Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :minio-git:`kes <kes>` commandline tool to create a new External Key
(EK) for use with SSE-S3 Encryption.
Use the :kes-docs:`kes <cli>` command line tool to create a new External Key (EK) for use with SSE-S3 Encryption.
Issue the following command to retrieve the root
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>` for the KES
server:
The following command retrieves the root :minio-git:`identity <kes/wiki/Configuration#policy-configuration>` for the KES server connected to the KES ``play`` sandbox:
.. code-block:: shell
:class: copyable
@ -127,30 +120,23 @@ Set the following environment variables in the terminal or shell:
:width: 100%
* - ``KES_CLIENT_KEY``
- The private key for an :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``,
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
<kes/wiki/Server-API#api-overview>`. This step uses the root
identity for the MinIO ``play`` KES sandbox, which provides access
to all operations on the KES server.
- The private key for an :kes-docs:`identity <concepts/#authorization>` on the KES server.
The identity must grant access to at minimum the ``/v1/create``, ``/v1/generate``, and ``/v1/list`` :kes-docs:`API endpoints <concepts/server-api/>`.
This step uses the ``root`` identity for the MinIO ``play`` KES sandbox, which provides access to all operations on the KES server.
* - ``KES_CLIENT_CERT``
- The corresponding certificate for the :minio-git:`identity
<kes/wiki/Configuration#policy-configuration>` on the KES server.
This step uses the root identity for the MinIO ``play`` KES
sandbox, which provides access to all operations on the KES server.
- The corresponding certificate for the :kes-docs:`identity <concepts/#authorization>` on the KES server.
This step uses the ``root`` identity for the MinIO ``play`` KES sandbox, which provides access to all operations on the KES server.
Issue the following command to create a new |EK| through
KES:
The following command creates a new |EK| through the :kes-docs:`KES CLI <cli/kes-key/create/>`:
.. code-block:: shell
:class: copyable
kes key create my-minio-sse-s3-key
This tutorial uses the example ``my-minio-sse-s3-key`` name for ease of
reference. Specify a unique key name to prevent collision with existing keys.
This tutorial uses the example ``my-minio-sse-s3-key`` name for ease of reference.
Specify a unique key name to prevent collision with existing keys.
2) Configure MinIO for SSE-S3 Object Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -206,8 +192,7 @@ Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
mc admin service restart ALIAS
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to restart.
4) Configure Automatic Bucket Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~