From 36f5bea8ea411b6cdf839b9fdbca1b0b323ccc23 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Thu, 3 Oct 2024 12:38:10 -0400 Subject: [PATCH] Updating encryption pages for KES API (#1333) Our preferred method for authenticating from MinIO to KES is with an API identity. This PR updates encryption docs to reflect this. Closes #1280 --- .../server-side-encryption-sse-kms.rst | 31 ++++++++++++------- .../server-side-encryption-sse-s3.rst | 14 +++++++-- .../includes/container/common-minio-kes.rst | 14 +++++++-- source/includes/windows/common-minio-kes.rst | 22 +++++++++++-- 4 files changed, 64 insertions(+), 17 deletions(-) diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst index 5289180e..67b0a6b1 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst @@ -146,9 +146,19 @@ MinIO server host in the deployment: :class: copyable export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373 - export MINIO_KMS_KES_KEY_FILE=root.key - export MINIO_KMS_KES_CERT_FILE=root.cert - export MINIO_KMS_KES_KEY_NAME=my-minio-sse-kms-key + export MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials + export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key + +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. .. list-table:: :stub-columns: 1 @@ -157,15 +167,14 @@ MinIO server host in the deployment: * - :envvar:`MINIO_KMS_KES_ENDPOINT` - The endpoint for the MinIO ``Play`` KES service. - * - :envvar:`MINIO_KMS_KES_KEY_FILE` - - The private key file corresponding to an :kes-docs:`identity ` 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_API_KEY` + - The API key :kes-docs:`generated by KES ` for the MinIO deployment. + The identity of the API key must grant permission to create, generate, and decrypt keys. - * - :envvar:`MINIO_KMS_KES_CERT_FILE` - - The public certificate file corresponding to an :kes-docs:`identity ` 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 API key is the preferred way to authenticate with the KES server. + If circumstances require it, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead. + Specify *either* the API key *or* the Key File and Cert File. + Do *not* populate all three environment variables. * - :envvar:`MINIO_KMS_KES_KEY_NAME` - The name of the External Key (EK) to use for performing SSE encryption operations. diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst index a446e2c2..c70a17bf 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst @@ -148,10 +148,20 @@ MinIO server host in the deployment: :class: copyable export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373 - export MINIO_KMS_KES_KEY_FILE=root.key - export MINIO_KMS_KES_CERT_FILE=root.cert + export MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + .. list-table:: :stub-columns: 1 :widths: 30 80 diff --git a/source/includes/container/common-minio-kes.rst b/source/includes/container/common-minio-kes.rst index f35d5aec..7dae61c1 100644 --- a/source/includes/container/common-minio-kes.rst +++ b/source/includes/container/common-minio-kes.rst @@ -99,11 +99,21 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server # KES Configurations MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373 - MINIO_KMS_KES_CERT_FILE=/certs/minio-kes.cert - MINIO_KMS_KES_KEY_FILE=/certs/minio-kes.key + MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials MINIO_KMS_KES_CAPATH=/certs/server.cert MINIO_KMS_KES_KEY_NAME=minio-backend-default-key +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations: - Encrypting the MinIO backend (IAM, configuration, etc.) diff --git a/source/includes/windows/common-minio-kes.rst b/source/includes/windows/common-minio-kes.rst index 7e827449..c7b24e54 100644 --- a/source/includes/windows/common-minio-kes.rst +++ b/source/includes/windows/common-minio-kes.rst @@ -98,11 +98,29 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server # Add these environment variables to the existing environment file MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373 - MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert - MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key + MINIO_KMS_KES_API_KEY= MINIO_KMS_KES_CAPATH=|miniocertpath|\kes-server.cert MINIO_KMS_KES_KEY_NAME=minio-backend-default-key + +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + + .. code-block:: shell + :substitions: + + MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert + MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key + + MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations: - Encrypting the MinIO backend (IAM, configuration, etc.)