From d5d3243413984427780d09b22544ae91a873ea4f Mon Sep 17 00:00:00 2001 From: Ravind Kumar Date: Fri, 30 Sep 2022 17:47:12 -0400 Subject: [PATCH] DOCS-580: Fixing reported issues with Vault tutorial (#591) @djwfyi cursory review in case I missed something. Closes #580 I do need to do further testing beyond the patches here. But I'm going to handle that out-of-band. --- source/extra/kes.service | 4 ++- .../includes/common/common-minio-kes-aws.rst | 6 ++-- .../common/common-minio-kes-azure.rst | 2 +- .../includes/common/common-minio-kes-gcp.rst | 2 +- .../common/common-minio-kes-hashicorp.rst | 9 ++++-- source/includes/common/common-minio-kes.rst | 9 +++--- source/includes/linux/common-minio-kes.rst | 17 +++++----- .../steps-configure-minio-kes-aws-quick.rst | 2 +- .../linux/steps-configure-minio-kes-aws.rst | 2 +- .../steps-configure-minio-kes-azure-quick.rst | 2 +- .../linux/steps-configure-minio-kes-azure.rst | 2 +- .../steps-configure-minio-kes-gcp-quick.rst | 2 +- .../linux/steps-configure-minio-kes-gcp.rst | 2 +- ...ps-configure-minio-kes-hashicorp-quick.rst | 4 +-- .../steps-configure-minio-kes-hashicorp.rst | 4 +-- .../macos/steps-configure-minio-kes-aws.rst | 2 +- .../macos/steps-configure-minio-kes-azure.rst | 2 +- .../macos/steps-configure-minio-kes-gcp.rst | 2 +- .../steps-configure-minio-kes-hashicorp.rst | 2 +- source/includes/windows/common-minio-kes.rst | 32 +++++++++---------- .../configure-minio-kes-hashicorp.rst | 4 +++ 21 files changed, 61 insertions(+), 52 deletions(-) diff --git a/source/extra/kes.service b/source/extra/kes.service index 72b96784..5314d298 100644 --- a/source/extra/kes.service +++ b/source/extra/kes.service @@ -8,11 +8,13 @@ AssertFileIsExecutable=/usr/local/bin/kes [Service] WorkingDirectory=/etc/kes/ +AmbientCapabilities=CAP_IPC_LOCK + User=kes Group=kes ProtectProc=invisible -ExecStart=/usr/local/bin/kes server --config=/etc/kes/config.yaml +ExecStart=/usr/local/bin/kes server --config=/opt/kes/config.yaml --mlock # Let systemd restart this service always Restart=always diff --git a/source/includes/common/common-minio-kes-aws.rst b/source/includes/common/common-minio-kes-aws.rst index feea1c7e..80776fb7 100644 --- a/source/includes/common/common-minio-kes-aws.rst +++ b/source/includes/common/common-minio-kes-aws.rst @@ -34,7 +34,7 @@ Manager: - /v1/key/generate/* - /v1/key/decrypt/* identities: - - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' + - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert' # In production environments, each client connecting to KES must # Have their TLS hash listed under at least one `policy`. @@ -92,7 +92,7 @@ Manager: - /v1/key/generate/* - /v1/key/decrypt/* identities: - - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' + - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert' # Specify the connection information for the KMS and Secrets Manager endpoint. # The endpoint should be resolvable from the host. @@ -115,7 +115,7 @@ 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``. + ``kes 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``. diff --git a/source/includes/common/common-minio-kes-azure.rst b/source/includes/common/common-minio-kes-azure.rst index 74fe8512..ae0ce256 100644 --- a/source/includes/common/common-minio-kes-azure.rst +++ b/source/includes/common/common-minio-kes-azure.rst @@ -35,7 +35,7 @@ Manager: - /v1/key/generate/* - /v1/key/decrypt/* identities: - - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' + - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert' # Specify the connection information for the Key Vualt endpoint. # The endpoint should be resolvable from the host. diff --git a/source/includes/common/common-minio-kes-gcp.rst b/source/includes/common/common-minio-kes-gcp.rst index 42eb2f0d..079119b3 100644 --- a/source/includes/common/common-minio-kes-gcp.rst +++ b/source/includes/common/common-minio-kes-gcp.rst @@ -34,7 +34,7 @@ Manager: - /v1/key/generate/* - /v1/key/decrypt/* identities: - - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' + - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert' # Specify the connection information for the Secrets Manager endpoint. # The endpoint should be resolvable from the host. diff --git a/source/includes/common/common-minio-kes-hashicorp.rst b/source/includes/common/common-minio-kes-hashicorp.rst index 71bbcf36..9c8c0f43 100644 --- a/source/includes/common/common-minio-kes-hashicorp.rst +++ b/source/includes/common/common-minio-kes-hashicorp.rst @@ -9,9 +9,10 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul address: 0.0.0.0:7373 - # Disable the root identity, as we do not need that level of access for + # Disable the root administrator identity, as we do not need that level of access for # supporting SSE operations. - root: disabled + admin: + identity: disabled # Specify the TLS keys generated in the previous step here # For production environments, use keys signed by a known and trusted @@ -29,7 +30,7 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul - /v1/key/generate/* # e.g. '/minio-' - /v1/key/decrypt/* identities: - - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' + - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert' # In production environments, each client connecting to KES must # Have their TLS hash listed under at least one `policy`. @@ -40,6 +41,8 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul keystore: vault: endpoint: https://HOSTNAME:8200 + engine: "/path/to/engine" # Replace with the path to the K/V Engine + version: "v1|v2" # Specify v1 or v2 depending on the version of the K/V Engine approle: id: "VAULTAPPID" # Hashicorp Vault AppRole ID secret: "VAULTAPPSECRET" # Hashicorp Vault AppRole Secret ID diff --git a/source/includes/common/common-minio-kes.rst b/source/includes/common/common-minio-kes.rst index 2118bb3e..0339bdf8 100644 --- a/source/includes/common/common-minio-kes.rst +++ b/source/includes/common/common-minio-kes.rst @@ -48,13 +48,13 @@ The following commands create two TLS certificates that expire within 30 days of # These commands output keys to |kescertpath| # and |miniocertpath| respectively - kes tool identity new \ + kes identity new \ --key |kescertpath|/kes-server.key \ --cert |kescertpath|/kes-server.cert \ --ip "127.0.0.1" \ --dns localhost - kes tool identity new \ + kes identity new \ --key |miniocertpath|/minio-kes.key \ --cert |miniocertpath|/minio-kes.cert \ --ip "127.0.0.1" \ @@ -85,6 +85,7 @@ Run the following commands in a terminal or shell to start the KES server as a f .. code-block:: shell :class: copyable + :substitutions: sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes)) @@ -223,7 +224,7 @@ Defaults to port ``7373`` on all host network interfaces. .. start-kes-conf-root-desc The identity for the KES superuser (``root``) identity. -Clients connecting with a TLS certificate whose hash (``kes tool identity of client.cert``) matches this value have access to all KES API operations. +Clients connecting with a TLS certificate whose hash (``kes identity of client.cert``) matches this value have access to all KES API operations. Specify ``disabled`` to remove the root identity and rely only on the ``policy`` configuration for controlling identity and access management to KES. @@ -256,7 +257,7 @@ the ``minio-sse-`` prefix. |KES| uses mTLS to authorize connecting clients by comparing the hash of the TLS certificate against the ``identities`` of each configured -policy. Use the ``kes tool identity of`` command to compute the identity of the +policy. Use the ``kes identity of`` command to compute the identity of the MinIO mTLS certificate and add it to the ``policy..identities`` array to associate MinIO to the ```` policy. diff --git a/source/includes/linux/common-minio-kes.rst b/source/includes/linux/common-minio-kes.rst index e7c06ecb..a343ebc2 100644 --- a/source/includes/linux/common-minio-kes.rst +++ b/source/includes/linux/common-minio-kes.rst @@ -31,7 +31,7 @@ Create the ``/etc/systemd/system/kes.service`` file on all KES hosts: You may need to run ``systemctl daemon-reload`` to load the new service file into ``systemctl``. -The ``kes.service`` file runs as the ``kes-user`` User and Group by default. +The ``kes.service`` file runs as the ``kes`` User and Group by default. You can create the user and group using the ``useradd`` and ``groupadd`` commands. The following example creates the user and group. These commands typically require root (``sudo``) permissions. @@ -39,17 +39,16 @@ These commands typically require root (``sudo``) permissions. .. code-block:: shell :class: copyable - groupadd -r kes-user - useradd -M -r -g kes-user kes-user + groupadd -r kes + useradd -M -r -g kes kes -The ``kes-user`` user and group must have read access to all files used by the KES service: +The ``kes`` user and group must have read access to all files used by the KES service: .. code-block:: shell :class: copyable :substitutions: - chown -R kes-user:kes-user /opt/kes - chown -R kes-user:kes-user /etc/kes + chown -R kes:kes /opt/kes .. end-kes-service-file-desc @@ -107,10 +106,10 @@ This procedure assumes a structure similar to the following: -rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert # For the KES Hosts - -rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.cert - -rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.key + -rw-r--r-- 1 kes:kes |kescertpath|/kes-server.cert + -rw-r--r-- 1 kes:kes |kescertpath|/kes-server.key -If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath|/certs directory such that each MinIO server can properly validate the KES certificates. +If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath| directory such that each MinIO server can properly validate the KES certificates. .. end-kes-generate-kes-certs-prod-desc diff --git a/source/includes/linux/steps-configure-minio-kes-aws-quick.rst b/source/includes/linux/steps-configure-minio-kes-aws-quick.rst index 0a71e843..b4eef630 100644 --- a/source/includes/linux/steps-configure-minio-kes-aws-quick.rst +++ b/source/includes/linux/steps-configure-minio-kes-aws-quick.rst @@ -52,7 +52,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. The value **must** match for both ``endpoint`` and ``region``. diff --git a/source/includes/linux/steps-configure-minio-kes-aws.rst b/source/includes/linux/steps-configure-minio-kes-aws.rst index e2ddf23a..bff954de 100644 --- a/source/includes/linux/steps-configure-minio-kes-aws.rst +++ b/source/includes/linux/steps-configure-minio-kes-aws.rst @@ -58,7 +58,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. The value **must** match for both ``endpoint`` and ``region``. diff --git a/source/includes/linux/steps-configure-minio-kes-azure-quick.rst b/source/includes/linux/steps-configure-minio-kes-azure-quick.rst index aeb0443a..951327f8 100644 --- a/source/includes/linux/steps-configure-minio-kes-azure-quick.rst +++ b/source/includes/linux/steps-configure-minio-kes-azure-quick.rst @@ -52,7 +52,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``endpoint`` with the URL for the Keyvault instance. diff --git a/source/includes/linux/steps-configure-minio-kes-azure.rst b/source/includes/linux/steps-configure-minio-kes-azure.rst index c6468429..6085c91a 100644 --- a/source/includes/linux/steps-configure-minio-kes-azure.rst +++ b/source/includes/linux/steps-configure-minio-kes-azure.rst @@ -58,7 +58,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``endpoint`` with the URL for the Keyvault instance. diff --git a/source/includes/linux/steps-configure-minio-kes-gcp-quick.rst b/source/includes/linux/steps-configure-minio-kes-gcp-quick.rst index d02fa10d..da641d9e 100644 --- a/source/includes/linux/steps-configure-minio-kes-gcp-quick.rst +++ b/source/includes/linux/steps-configure-minio-kes-gcp-quick.rst @@ -52,7 +52,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. diff --git a/source/includes/linux/steps-configure-minio-kes-gcp.rst b/source/includes/linux/steps-configure-minio-kes-gcp.rst index 077028c1..260744eb 100644 --- a/source/includes/linux/steps-configure-minio-kes-gcp.rst +++ b/source/includes/linux/steps-configure-minio-kes-gcp.rst @@ -58,7 +58,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. diff --git a/source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst b/source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst index c32801ee..61faa6f7 100644 --- a/source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst +++ b/source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst @@ -56,10 +56,10 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``vault.endpoint`` with the hostname of the Vault server(s). - + - Set the ``vault.engine`` and ``vault.version`` to the appropriate values for the Vault K/V Engine configuration - Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials `. b. Create the MinIO Environment File diff --git a/source/includes/linux/steps-configure-minio-kes-hashicorp.rst b/source/includes/linux/steps-configure-minio-kes-hashicorp.rst index 8a7f2b16..9250a120 100644 --- a/source/includes/linux/steps-configure-minio-kes-hashicorp.rst +++ b/source/includes/linux/steps-configure-minio-kes-hashicorp.rst @@ -48,7 +48,7 @@ a. Create the KES Configuration File .. code-block:: shell :substitutions: - nano /etc/kes/config.yaml + nano /opt/kes/config.yaml .. include:: /includes/common/common-minio-kes-hashicorp.rst :start-after: start-kes-configuration-hashicorp-vault-desc @@ -62,7 +62,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``vault.endpoint`` with the hostname of the Vault server(s). diff --git a/source/includes/macos/steps-configure-minio-kes-aws.rst b/source/includes/macos/steps-configure-minio-kes-aws.rst index 9e0d10ed..4d24c95e 100644 --- a/source/includes/macos/steps-configure-minio-kes-aws.rst +++ b/source/includes/macos/steps-configure-minio-kes-aws.rst @@ -50,7 +50,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. The value **must** match for both ``endpoint`` and ``region``. diff --git a/source/includes/macos/steps-configure-minio-kes-azure.rst b/source/includes/macos/steps-configure-minio-kes-azure.rst index ae2da3da..4eee969b 100644 --- a/source/includes/macos/steps-configure-minio-kes-azure.rst +++ b/source/includes/macos/steps-configure-minio-kes-azure.rst @@ -50,7 +50,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``endpoint`` with the URL for the Keyvault instance. diff --git a/source/includes/macos/steps-configure-minio-kes-gcp.rst b/source/includes/macos/steps-configure-minio-kes-gcp.rst index e2a09292..92a80d36 100644 --- a/source/includes/macos/steps-configure-minio-kes-gcp.rst +++ b/source/includes/macos/steps-configure-minio-kes-gcp.rst @@ -50,7 +50,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. diff --git a/source/includes/macos/steps-configure-minio-kes-hashicorp.rst b/source/includes/macos/steps-configure-minio-kes-hashicorp.rst index 0ceaa753..8fdf4b3f 100644 --- a/source/includes/macos/steps-configure-minio-kes-hashicorp.rst +++ b/source/includes/macos/steps-configure-minio-kes-hashicorp.rst @@ -53,7 +53,7 @@ a. Create the KES Configuration File :class: copyable :substitutions: - kes tool identity of |miniocertpath|/minio-kes.cert + kes identity of |miniocertpath|/minio-kes.cert - Replace the ``vault.endpoint`` with the hostname of the Vault server(s). diff --git a/source/includes/windows/common-minio-kes.rst b/source/includes/windows/common-minio-kes.rst index b89a2af8..595eedd1 100644 --- a/source/includes/windows/common-minio-kes.rst +++ b/source/includes/windows/common-minio-kes.rst @@ -22,16 +22,16 @@ The following commands creates two TLS certificates that expire within 30 days o # These commands output the certificates to |kescertpath| - C:\kes.exe tool identity new \ - --key |kescertpath| \ kes-server.key \ - --cert |kescertpath| \ kes-server.cert \ - --ip "127.0.0.1" \ + C:\kes.exe identity new \ + --key |kescertpath|\kes-server.key \ + --cert |kescertpath|\kes-server.cert \ + --ip "127.0.0.1" \ --dns localhost - C:\kes.exe tool identity new \ - --key |miniocertpath| \ minio-kes.key \ - --cert |miniocertpath| \ minio-kes.cert \ - --ip "127.0.0.1" \ + C:\kes.exe identity new \ + --key |miniocertpath|\minio-kes.key \ + --cert |miniocertpath|\minio-kes.cert \ + --ip "127.0.0.1" \ --dns localhost The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate. @@ -66,7 +66,7 @@ Run the following command in a terminal or shell to start the KES server as a fo :class: copyable :substitutions: - C:\kes.exe server --auth --config=|kesconfigpath| \ config \ kes-config.yaml + C:\kes.exe server --auth --config=|kesconfigpath|\config\kes-config.yaml Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background. @@ -80,8 +80,8 @@ Run the following command in a terminal or shell to start the MinIO server as a :class: copyable :substitutions: - export MINIO_CONFIG_ENV_FILE=|minioconfigpath| \ config \ minio - C: \ minio.exe server --console-address :9090 + export MINIO_CONFIG_ENV_FILE=|minioconfigpath|\config\minio + C:\minio.exe server --console-address :9090 .. end-kes-minio-start-server-desc @@ -97,8 +97,8 @@ The following command uses the ``kes key create`` command to create a new Extern :substitutions: export KES_SERVER=https://127.0.0.1:7373 - export KES_CLIENT_KEY=|miniocertpath| \ minio-kes.key - export KES_CLIENT_CERT=|miniocertpath| \ minio-kes.cert + export KES_CLIENT_KEY=|miniocertpath|\minio-kes.key + export KES_CLIENT_CERT=|miniocertpath|\minio-kes.cert C:\kes.exe key create -k encrypted-bucket-key @@ -129,9 +129,9 @@ 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_CAPATH=|miniocertpath| \ kes-server.cert + MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert + MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key + MINIO_KMS_KES_CAPATH=|miniocertpath|\kes-server.cert MINIO_KMS_KES_KEY_NAME=minio-backend-default-key minio.exe server [ARGUMENTS] diff --git a/source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst b/source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst index a6ebdd53..b6e37090 100644 --- a/source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst +++ b/source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst @@ -155,15 +155,18 @@ Select the corresponding tab to the engine used by your Vault deployment for ins 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`` MinIO requires using AppRole authentication for secure communication with the Vault server. The following commands: +- Enable AppRole Authentication - Create an App Role ID for |KES| - Binds that role to the created KES policy - Requests a RoleID and SecretID @@ -171,6 +174,7 @@ The following commands: .. code-block:: shell :class: copyable + vault auth enable approle 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