From 894f62a45ef05c151eed90da023d6ef5a776a633 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Wed, 21 Oct 2020 18:04:27 -0400 Subject: [PATCH] KES migration --- source/includes/minio-kes-installation.rst | 100 +++++ source/includes/minio-server-installation.rst | 6 +- source/index.rst | 1 + source/minio-cli/kes/kes-identity.rst | 64 +++ source/minio-cli/kes/kes-key.rst | 172 +++++++ source/minio-cli/kes/kes-policy.rst | 145 ++++++ source/minio-cli/kes/kes-server.rst | 91 ++++ source/minio-cli/kes/kes-tool-identity.rst | 110 +++++ source/minio-cli/minio-kes-reference.rst | 421 ++++++++++++++++++ source/minio-server/minio-server.rst | 39 ++ source/security/encryption/minio-kes.rst | 341 ++++++++++++-- sphinxext/minio.py | 10 +- 12 files changed, 1460 insertions(+), 40 deletions(-) create mode 100644 source/includes/minio-kes-installation.rst create mode 100644 source/minio-cli/kes/kes-identity.rst create mode 100644 source/minio-cli/kes/kes-key.rst create mode 100644 source/minio-cli/kes/kes-policy.rst create mode 100644 source/minio-cli/kes/kes-server.rst create mode 100644 source/minio-cli/kes/kes-tool-identity.rst create mode 100644 source/minio-cli/minio-kes-reference.rst diff --git a/source/includes/minio-kes-installation.rst b/source/includes/minio-kes-installation.rst new file mode 100644 index 00000000..2317760e --- /dev/null +++ b/source/includes/minio-kes-installation.rst @@ -0,0 +1,100 @@ +.. tabs:: + + .. tab:: Linux + + The following commands add a *temporary* extension to your system + PATH for running the ``kes`` utility. Defer to your operating system + instructions for making permanent modifications to your system PATH. + + Alternatively, execute ``kes`` by navigating to the download folder and + running ``./kes --help`` + + **64-bit ARM64** + + .. code-block:: shell + :class: copyable + + curl https://github.com/minio/kes/releases/latest/download/kes-linux-arm64 \ + --create-dirs \ + -o $HOME/minio-binaries/kes + + chmod +x $HOME/minio-binaries/kes + export PATH=$PATH:$HOME/minio-binaries/ + + kes --help + + **64-bit AMD64** + + .. code-block:: shell + :class: copyable + + curl https://github.com/minio/kes/releases/latest/download/kes-linux-amd64 \ + --create-dirs \ + -o $HOME/minio-binaries/kes + + chmod +x $HOME/minio-binaries/kes + export PATH=$PATH:$HOME/minio-binaries/ + + kes --help + + **32-bit ARM** + + .. code-block:: shell + :class: copyable + + curl https://github.com/minio/kes/releases/latest/download/kes-linux-arm \ + --create-dirs \ + -o $HOME/minio-binaries/kes + + chmod +x $HOME/minio-binaries/kes + export PATH=$PATH:$HOME/minio-binaries/ + + kes --help + + .. tab:: macOS + + .. code-block:: shell + :class: copyable + + curl https://github.com/minio/kes/releases/latest/download/kes-darwin-amd64 \ + --create-dirs \ + -o $HOME/minio-binaries/minio + + chmod +x $HOME/minio-binaries/minio + export PATH=$PATH:$HOME/minio-binaries/ + + kes --help + + .. tab:: Windows + + Open the following URL in a browser and save the file: + + https://github.com/minio/kes/releases/latest/download/kes-windows-amd64.exe + + Execute the file by double clicking on it, *or* by running the + following in the command prompt or powershell: + + .. code-block:: doscon + + C:\path\to\mc.exe --help + + .. tab:: Source + + Installation from source is intended for developers and advanced users + and requires a working Golang environment with minimum version + ``GO 1.14``. See + `How to install Golang `__. + + Run the following commands in a terminal environment to install ``kes`` + from source: + + .. code-block:: shell + :class: copyable + + go get -d github.com/minio/kes/cmd/kes + cd ${GOPATH}/src/github.com/minio/kes/cmd/kes + make + + To update a source-based installation, use ``go get -u``. + + diff --git a/source/includes/minio-server-installation.rst b/source/includes/minio-server-installation.rst index 994d757a..ff36f761 100644 --- a/source/includes/minio-server-installation.rst +++ b/source/includes/minio-server-installation.rst @@ -63,16 +63,16 @@ .. tab:: Windows - Open the following file in a browser: + Open the following URL in a browser and save the file: https://dl.min.io/server/minio/release/windows-amd64/minio.exe Execute the file by double clicking on it, *or* by running the following in the command prompt or powershell: - .. code-block:: powershell + .. code-block:: doscon - \path\to\mc.exe --help + C:\path\to\mc.exe --help .. tab:: Source diff --git a/source/index.rst b/source/index.rst index 490d4fc1..8e8a49dc 100644 --- a/source/index.rst +++ b/source/index.rst @@ -25,4 +25,5 @@ Users deploying onto a Kubernetes cluster should start with our /security/security-overview /minio-cli/minio-mc /minio-cli/minio-mc-admin + /minio-cli/minio-kes-reference /minio-server/minio-server diff --git a/source/minio-cli/kes/kes-identity.rst b/source/minio-cli/kes/kes-identity.rst new file mode 100644 index 00000000..5118ffc4 --- /dev/null +++ b/source/minio-cli/kes/kes-identity.rst @@ -0,0 +1,64 @@ +================ +``kes identity`` +================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes identity + +The :mc:`kes identity` command performs non-persistent association or removal +of x.509 identities to :ref:`policies ` on a KES server. +All changes made by :mc:`kes identity` are lost when the KES server restarts. + +To make persistent changes to KES policies, modify the +:kesconf:`policy` section of the KES +:ref:`configuration file `. Specifically, for each +:kesconf:`policy.policyname` to modify, you must add/remove the +identities to/from the :kesconf:`policy.policyname.identities` array. + +Use the :mc:`kes tool identity of` command line tool to compute the +identity hash for the x.509 certificate to add or remove from a policy. + +This page provides reference information for the :mc:`kes policy` command. + +- For more complete information on KES policies, see + :ref:`minio-kes-policy`. + +- For more complete conceptual information on KES, see :ref:`minio-kes`. + +Examples +-------- + +Assign an Identity to a Policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +List Identities on the KES Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Remove an Identity from the KES Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Syntax +------ + +.. mc-cmd:: assign + :fullpath: + + Assigns a new x.509 identity to a policy on the KES server. + + Use the :mc:`kes tool identity of` command to compute the identity hash + for the x.509 certificate. + +.. mc-cmd:: list + :fullpath: + + Lists the x.509 identities on the KES server. + +.. mc-cmd:: forget + :fullpath: + + Removes an x.509 identity from the KES server. \ No newline at end of file diff --git a/source/minio-cli/kes/kes-key.rst b/source/minio-cli/kes/kes-key.rst new file mode 100644 index 00000000..4149f86e --- /dev/null +++ b/source/minio-cli/kes/kes-key.rst @@ -0,0 +1,172 @@ +=========== +``kes key`` +=========== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes key + +The :mc:`kes key` command manages creating cryptographic keys for use with +Server-Side Object Encryption (SSE). + +This page provides reference information for the :mc:`kes key` +command. + +- For more complete conceptual information on KES, see :ref:`minio-kes`. + +- For an example of using :mc:`kes key` to generate secret keys using + Thales CipherTrust as the KMS, see + +- Other specific tutorials to follow. + +Syntax +------ + +.. mc-cmd:: create + :fullpath: + + Creates a new secret key on the KES server. + + Creates a new CMK. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes key create [ARGUMENTS] NAME [KEY] + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + The name of the secret key. + + .. mc-cmd:: KEY + + *Optional* + + The value to use as the secret key. Specify a base64-encoded string. + + Omit :mc-cmd:`~kes key create KEY` to direct KES to automatically + generate a random value for the key. + + .. mc-cmd:: insecure, k + :option: + + Skips x.509 Certificate Validation during TLS handshakes. This option + is required if using self-signed certificates. + +.. mc-cmd:: delete + :fullpath: + + Deletes a master key on the KES server. Deleting a master key prevents + decrypting any cryptographic keys derived using that master key, which + in turn prevents decrypting any objects encrypted with those cryptographic + keys. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes key delete [ARGUMENTS] NAME + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + *Required* + + The name of the master key to delete. + + .. mc-cmd:: insecure, k + :option: + + Skips x.509 Certificate Validation during TLS handshakes. This option + is required if using self-signed certificates. + +.. mc-cmd:: derive + :fullpath: + + Derives a new cryptographic key using a master key on the KES server. The + cryptographic key can support Server-Side Object Encryption (SSE-S3). + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes key derive [ARGUMENTS] NAME [CONTEXT] + + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + *Required* + + The name of the master key on the KES server to use to generate the + cryptographic key. + + .. mc-cmd:: CONTEXT + + *Optional* + + A base64-encoded string to use with the master key for deriving the + cryptographic key. + + .. mc-cmd:: insecure, k + :option: + + Skips x.509 Certificate Validation during TLS handshakes. This option + is required if using self-signed certificates. + +.. mc-cmd:: decrypt + :fullpath: + + Decrypt the cyphertext associated to a cryptographic key generated using + :mc-cmd:`kes key derive`. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes key decrypt [ARGUMENTS] NAME CIPHERTEXT [CONTEXT] + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + *Required* + + The name of master key used to generate teh cryptographic key. + + :mc-cmd:`kes key decrypt` fails if the specified master key + was not used to encrypt the :mc-cmd:`~kes key decrypt CIPHERTEXT`. + + .. mc-cmd:: CIPHERTEXT + + *Required* + + The cryptographic key to decrypt using the specified + :mc-cmd:`master key `. + + .. mc-cmd:: CONTEXT + + *Optional* + + The base64-encoded string specified to + :mc-cmd:`kes key derive CONTEXT` when creating the cryptographic key, if + any. + + .. mc-cmd:: insecure, k + :option: + + Skips x.509 Certificate Validation during TLS handshakes. This option + is required if using self-signed certificates. \ No newline at end of file diff --git a/source/minio-cli/kes/kes-policy.rst b/source/minio-cli/kes/kes-policy.rst new file mode 100644 index 00000000..6d314b02 --- /dev/null +++ b/source/minio-cli/kes/kes-policy.rst @@ -0,0 +1,145 @@ +============== +``kes policy`` +============== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes policy + +The :mc:`kes policy` command performs non-persistent creation and modification +of access policies on a MinIO Key Encryption Service (KES). All changes made by +:mc:`kes policy` are lost when the KES server restarts. + +To make persistent changes to KES policies, add or modify the policies +listed under the :kesconf:`policy` section of the +:ref:`KES configuration file `. :mc:`kes policy` supports +testing the effect of new or modified policies prior to adding them to the +KES configuration file. + +This page provides reference information for the :mc:`kes policy` +command. + +- For more complete information on KES policies, see + :ref:`minio-kes-policy`. + +- For more complete conceptual information on KES, see :ref:`minio-kes`. + +.. _minio-kes-policy-document: + +Policy Document Structure +~~~~~~~~~~~~~~~~~~~~~~~~~ + +KES uses JSON-formatted policy documents to describe the permissions granted +to authenticated clients. + +The KES Policy Document has the following schema: + +.. code-block:: json + :class: copyable + + { + "policyName": { + "paths": [ + "ENDPOINT", + "ENDPOINT" + ], + "identities": [ + "IDENTITY", + "IDENTITY" + ] + } + } + +The following table describes each field in the KES Policy Document: + +.. kespolicy:: policyName + + *Type: object* + + The name of the KES policy. Replace ``"policyName"`` with a unique name + for the KES policy. You can specify multiple :kespolicy:`policyName` + objects in the KES Policy document: + + .. code-block:: json + + { + "keyManagement" : {}, + "encryptDecrypt" : {} + } + +.. kespolicy:: policyName.paths + + *Type: array* + + An array of KES API endpoints for which the + :kespolicy:`~policyName.identities` can access. + + Each endpoint *must* be a glob pattern in the following form: + + .. code-block:: shell + + ///[//] + + You can specify an asterisk ``*`` to create a catch-all pattern for + a given endpoint. For example, the following endpoint pattern + allows complete access to key creation via the ``/v1/key/create`` + endpoint: + + .. code-block:: shell + + /v1/key/create/* + + See :ref:`minio-kes-endpoints` for a list of KES endpoints and the + actions associated to each. + +.. kespolicy:: policyName.identities + + *Type: array* + + An array of x.509 identities associated to the policy. KES grants clients + authenticating with a matching x.509 certificate access to the + endpoints listed in the :kespolicy:`~policyName.paths` for the + policy. + + Use :mc-cmd:`kes tool identity of` to compute the name of each x.509 + certificate you want to associate to the policy and specify that value to the + array. + +Examples +-------- + +Add a New Policy +~~~~~~~~~~~~~~~~ + +List Existing Policies +~~~~~~~~~~~~~~~~~~~~~~ + +Remove an Existing Policy +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Syntax +------ + +.. mc-cmd:: add + :fullpath: + + This command adds a new policy to the KES server. + +.. mc-cmd:: show + :fullpath: + + This command outputs the policy JSON document too ``STDOUT``. + +.. mc-cmd:: list + :fullpath: + + This command lists all policies on the KES server. + +.. mc-cmd:: delete + :fullpath: + + This command deletes a policy on the KES server. \ No newline at end of file diff --git a/source/minio-cli/kes/kes-server.rst b/source/minio-cli/kes/kes-server.rst new file mode 100644 index 00000000..9e7df043 --- /dev/null +++ b/source/minio-cli/kes/kes-server.rst @@ -0,0 +1,91 @@ +============== +``kes server`` +============== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes server + +The :mc:`kes server` command starts a MinIO Key Encryption Server (KES) server. +The :mc:`kes server` process handles requests for creating and retrieving +cryptography keys from a supported Key Management System (KMS). KES is a +required component for enabling Server-Side Object Encryption in MinIO +deployments. + +This page provides reference information for the :mc:`kes server` command. +For more complete conceptual information on KEs, see +:ref:`minio-kes`. + +Server Configuration File +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples +-------- + +The following list links to tutorials for configuring KES with supported Key +Management Services (KMS): + +- Thales/Gemalto +- AWS +- GCP +- ETC. + +To deploy KES for evaluation and initial development, you can also use +the :ref:`KES Getting Started Guide ` to deploy +KES using the local filesystem as the backing KMS. + +Syntax +------ + +The command has the following syntax: + +.. code-block:: shell + :class: copyable + + kes server --cert CERTIFICATE --key PRIVATEKEY --root ROOT_IDENTITY [OPTIONAL_FLAGS] + +:mc:`kes server` supports the following arguments: + +.. mc-cmd:: cert + :option: + + The location of the public certificate ``.crt`` to use for + enabling :abbr:`TLS (Transport Layer Encryption)`. + +.. mc-cmd:: config + :option: + + The path to the KES configuration file. See :ref:`minio-kes-config` for + more information on the configuration file format and contents. + +.. mc-cmd:: key + :option: + + The location of the private key ``.key`` to use for enabling + :abbr:`TLS (Transport Layer Encryption`). + +.. mc-cmd:: root + :option: + + The identity with root permissions on the KES server. Use + ``kes tool identity of CERTIFICATE`` to retrieve the certificate to use + for the root identity. + +.. mc-cmd:: port + :option: + + The port on which the :mc:`kes server` listens. + + Defaults to ``7373``. + +.. mc-cmd:: auth + :option: + + Disables strict validation of TLS certificates. Required if using + self-signed certificates for the + :mc-cmd-option:`~kes server key` and + :mc-cmd-option:`~kes server cert`. diff --git a/source/minio-cli/kes/kes-tool-identity.rst b/source/minio-cli/kes/kes-tool-identity.rst new file mode 100644 index 00000000..018f019e --- /dev/null +++ b/source/minio-cli/kes/kes-tool-identity.rst @@ -0,0 +1,110 @@ +===================== +``kes tool identity`` +===================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes tool identity + +The :mc:`kes tool identity` command creates a self-signed x.509 certificate +for use with deploying a :mc:`kes server` for local evaluation and initial +development. + +This page provides reference information for the :mc:`kes tool identity` +command. + +- For an example of using :mc:`kes tool identity`, see the + :ref:`KES Getting Started Guide `. + +- For more complete conceptual information on KES, see :ref:`minio-kes`. + +:mc:`kes tool identity` only supports generating self-signed certificates and +is best suited for supporting early development and evaluation of KES. To +configure a KES server to use an x.509 certificate generated through other +means, including ACME-based tools like CertBot, use :mc:`kes identity assign` +instead. + +Syntax +------ + +.. mc-cmd:: new + :fullpath: + + Creates a new x.509 certificate identity for use with accessing the KES + server. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes tool identity new [ARGUMENTS] NAME + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + The x.509 ``commonName`` to associate to the generated x.509 certificates. + + Defaults to ``""`` if unspecified. + + .. mc-cmd:: key + :option: + + The path to the private key to create for the identity. + + Defaults to ``./private.key``. + + .. mc-cmd:: cert + :option: + + The path to the public key certificate to create for the identity. + + Defaults to ``./public.cert``. + + .. mc-cmd:: time, t + :option: + + The duration to certificate expiration. + + Defaults to ``720h`` or 720 hours. + + .. mc-cmd:: force, f + :option: + + Directs :mc-cmd:`kes tool identity new` to overwrite the + specified :mc-cmd-option:`~kes tool identity new key` or + :mc-cmd:`~kes tool identity new cert` if either exists. + +.. mc-cmd:: of + :fullpath: + + Computes the identity string from a TLS certificate. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + kes tool identity of [ARGUMENTS] NAME + + The command accepts the following arguments: + + .. mc-cmd:: NAME + + The name of the certificate for which the command computes the identity + string. + + .. mc-cmd:: hash + :option: + + The hash function used to compute the identity. Specify one of the + following functions: + + - ``SHA-256`` + - ``SHA-384`` + - ``SHA-512`` \ No newline at end of file diff --git a/source/minio-cli/minio-kes-reference.rst b/source/minio-cli/minio-kes-reference.rst new file mode 100644 index 00000000..1584e5ae --- /dev/null +++ b/source/minio-cli/minio-kes-reference.rst @@ -0,0 +1,421 @@ +====================================== +MinIO Key Encryption Service (``kes``) +====================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: kes + +Overview +-------- + +The MinIO Key Encryption Service (KES) is a stateless and distributed +key-management system for high-performance applications. KES provides +a bridge between applications running in bare-metal or orchestrated +environments to centralised KMS solutions. + +This page provides a reference for the :mc:`kes` command line tool. For more +complete conceptual information on KES, see :ref:`minio-kes`. + +For tutorials on deploying KES to support Server-Side Object Encryption, see: + +- Server-Side Object Encryption with Thales CipherText +- Other similar tutorials. + +.. _minio-kes-installation: + +Installation +------------ + +.. include:: /includes/minio-kes-installation.rst + +.. _minio-kes-config: + +KES Configuration File +---------------------- + +The KES configuration file is a ``YAML`` document containing information for +running the KES server. Use +:mc-cmd-option:`kes server config` to specify the path to the configuration file +on startup. + +General Configuration +~~~~~~~~~~~~~~~~~~~~~ + +.. kesconf:: address + + The network addresses and port on which :mc:`kes server` binds to on startup. + Specify a string as ``IP:PORT``: + + - To specify only a custom IP address, omit ``:PORT``. + + - To specify only a custom port, omit ``IP``. + + Defaults to port ``7373`` on all network addresses on the host machine. + +.. kesconf:: root + + Specify ``disabled`` to disable the :ref:`root ` identity + on the KES server. The ``root`` identity has super administrator access to + the KES server. + + If omitted, the :mc:`kes server` *requires* specifying an x.509 certificate + using the :mc-cmd-option:`~kes server root` command line option. + +TLS Configuration +~~~~~~~~~~~~~~~~~ + +The following section describes TLS-related configuration for the KES server: + +.. code-block:: yaml + + tls: + key: + cert: + +.. kesconf:: tls + + The root field for TLS-related configuration. + +.. kesconf:: tls.key + + The path to the TLS private ``.key`` file KES uses when establishing + TLS-secured communications. + + Ensure the Certificate Authority used to sign the private key exists in the + host OS system trusted certificate store. Defer to the host operating + system documentation for adding Certificate Authorities to the certificate + store. + + To direct KES to accept invalid certificates, include the + :mc-cmd-option:`kes server auth` option when starting the KES server. + +.. kesconf:: tls.cert + + The path to the TLS public certificate ``.cert`` file KES uses when + establishing TLS-secured communications. + + Ensure the Certificate Authority used to sign the private key exists in the + host OS system trusted certificate store. Defer to the host operating + system documentation for adding Certificate Authorities to the certificate + store. + + To direct KES to accept invalid certificates, include the + :mc-cmd-option:`kes server auth` option when starting the KES server. + +Cache Configuration +~~~~~~~~~~~~~~~~~~~ + +The following section describes cache-related configuration for +controlling how often the KES server fetches keys from an external KMS. + +.. code-block:: yaml + + cache: + expiry: + any: + unused: + +.. kesconf:: cache + + The root field for cache-related configuration. + +.. kesconf:: cache.expiry + + The root field for cache expiry configuration. + +.. kesconf:: cache.expiry.any + + The duration between clearing the in-memory cache of Customer Master Keys + (CMK) retrieved by KES. Specify a string as ``##h##m##s``: + + - ``30s`` sets a cache expiry of 30 seconds. + - ``1m0s`` sets a cache expiry of 1 minute. + - ``2m30s`` sets a cache expiry of 2 minutes and 30 seconds. + + Lower values trade higher security for more frequent outgoing network + requests to the external KMS. Higher values may provide increased performance + at the cost of security due to long-cached CMK. + + For example, a ``30s`` expiry allows KES to go up to 30 seconds + without making a request to the external KMS. However, if the CMK is disabled + or deleted during that time period, KES continues to encrypt and decrypt + data using that CMK until the next refresh. + + The following table provides guidance for setting the cache value: + + .. list-table:: + :header-rows: 1 + :widths: 40 60 + :width: 50% + + * - Security Goal + - Value + + * - *Liberal* + - ``5m0s`` + + * - *Moderate* + - ``1m0s`` + + * - *Conservative* + - ``30s`` + +.. kesconf:: cache.expiry.unused + + The duration after which KES considers a cached Customer Master Key as + unused and removes that key from the cache. Specify a string as ``##h##m##s``: + + - ``30s`` sets a cache expiry of 30 seconds. + - ``1m0s`` sets a cache expiry of 1 minute. + - ``2m30s`` sets a cache expiry of 2 minutes and 30 seconds. + + The following table provides guidance for setting the cache value: + + .. list-table:: + :header-rows: 1 + :widths: 40 60 + :width: 50% + + * - Security Goal + - Value + + * - *Liberal* + - ``30s`` + + * - *Moderate* + - ``20s`` + + * - *Conservative* + - ``5s`` + +Logging Configuration +~~~~~~~~~~~~~~~~~~~~~ + +The following section describes logging-related configuration for the KES +server: + +.. code-block:: yaml + + log: + error: + audit: + +.. kesconf:: log + + The root field for log-related configuration. + +.. kesconf:: log.error + + Enables or disables error logging to ``STDERR``. + + - Specify ``on`` to enable error logging. + + - Specify ``off`` to disable error logging. + + Defaults to ``on``. + +.. kesconf:: log.audit + + Enables or disables audit logging to ``STDOUT``. + + - Specify ``on`` to enable audit logging. + + - Specify ``off`` to disable audit logging. + + Defaults to ``off``. + + The KES server emits an audit event for every client request. Each + event describes the complete request-response pair and includes information + about the requesting client. The audit information *never* contains + plaintext cryptographic keys. + + KES server may produce many audit events depending on the number of MinIO + servers or other clients making requests to the server. + +Policy Configuration +~~~~~~~~~~~~~~~~~~~~ + +The following section describes policy-related configuration for the KES server. +Policies control :ref:`Identity and Access Management ` for +the KES server. + +Policies listed in this section are *persistent* through KES server restarts. +Policies created using :mc:`kes policy` are *ephemeral* and are removed after +KES server restart. To make a policy created or modified through +:mc:`kes policy` persistent. add that policy to this section of the +KES configuration file: + +.. code-block:: yaml + + policy: + policyname: + paths: + identities: + +.. kesconf:: policy + + The root field for policy-related configuration. + +.. kesconf:: policy.policyname + + The name of the policy. Replace the field ``policyname`` with a string + for the policy name. The policy name *must* be unique among all other + ``policyname`` objects specified to :kesconf:`policy`. + +.. kesconf:: policy.policyname.paths + + An array of :ref:`KES API Endpoints ` which + the specified :kesconf:`policy.policyname.identities` can access. + + Each endpoint *must* be a glob pattern in the following form: + + .. code-block:: shell + + ///[//] + + You can specify an asterisk ``*`` to create a catch-all pattern for + a given endpoint. For example, the following endpoint pattern + allows complete access to key creation via the ``/v1/key/create`` + endpoint: + +.. kesconf:: policy.policyname.identities + + An array of x.509 identities associated to the policy. KES grants clients + authenticating with a matching x.509 certificate access to the + endpoints listed in the :kespolicy:`~policyName.paths` for the + policy. + + Use :mc-cmd:`kes tool identity of` to compute the name of each x.509 + certificate you want to associate to the policy and specify that value + to the array. + +Filesystem KMS Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section describes Filesystem KMS-related configuration for the +KES server. + +Configuring the KES server for Filesystem KMS directs KES to store +generated Customer Master Keys (CMK) on-disk. Filesystem KMS is appropriate +for local development and evaluation of KES *only* and should *never* be used +for production environments. + +.. code-block:: yaml + + keys: + fs: + path: + +.. kesconf:: keys + :noindex: + + The root field for KMS-related configuration. + +.. kesconf:: keys.fs + + The root field for Filesystem KMS-related configuration. + +.. kesconf:: keys.fs.path + + The filesystem path to the directory on disk where KES stores any + generated CMK. + +Hashicorp Vault Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section describes Hashicorp Vault-related configuration for +the KES server. + +For more complete documentation on configuring KES for connecting to a +Hashicorp Vault KMS, see . + +.. code-block:: yaml + + keys: + vault: + endpoint: https://[IP|HOSTNAME] + approle: + id: "" + secret: "" + retry: + status: + ping: + tls: + ca: + +.. kesconf:: keys + :noindex: + + The root field for KMS-related configuration. + +.. kesconf:: keys.vault + + The root field for Hashicorp Vault-related configuration. + +.. kesconf:: keys.vault.endpoint + + Specify the URL endpoint of the Hashicorp Vault server. + +.. kesconf:: keys.vault.prefix + + Specify the prefix under which the KES server looks for secret keys. + Required if the Vault ``AppRole`` capabilities specifies a prefix for keys + generated by that ``AppRole``. + +.. kesconf:: keys.vault.approle + + Contains information related to Hashicorp Vault + `AppRole Authentication `__. + + KES authenticates to Hashicorp Vault using the ``AppRole`` ID and secret. + The specified ``AppRole`` *must* grant KES ``create``, ``read``, and + ``delete`` capabilities on Vault. Defer to Vault documentation for + more complete guidance on configuring ``AppRole`` ID and permission. + +.. kesconf:: keys.vault.approle.id + + Specify the ID of the Vault ``AppRole`` with which KES authenticates. + +.. kesconf:: keys.vault.approle.secret + + Specify the corresponding secret ID for the specified + :kesconf:`keys.vault.approle.id`. + +.. kesconf:: keys.vault.approle.retry + + The duration KES waits before attempting to reconnect to the Vault server. + Specify a string as ``##h##m##s``. + +.. kesconf:: keys.vault.status + + Contains information related to retrieving the status of the Vault server. + +.. kesconf:: keys.vault.status.ping + + The duration KES waits between requesting status information onn the Vault + server. Specify a string as ``##h##m##s``. + +.. kesconf:: keys.vault.tls + + Contains information related to the TLS Certificate Authority used by the + vault server. KES may require this for self-signed certificates *or* + for certificates signed by a non-global Certificate Authority. + +.. kesconf:: keys.vault.tls.ca + + Specify the full path to the Certificate Authority ``*.crt`` file used to + sign the Vault TLS certificates. + + + +.. toctree:: + :titlesonly: + :hidden: + :glob: + + /minio-cli/kes/* \ No newline at end of file diff --git a/source/minio-server/minio-server.rst b/source/minio-server/minio-server.rst index ba41f971..ae6c27da 100644 --- a/source/minio-server/minio-server.rst +++ b/source/minio-server/minio-server.rst @@ -321,3 +321,42 @@ Root Credentials the server configuration with the new credentials. After the process restarts successfully, you can restart it without :envvar:`MINIO_SECRET_KEY_OLD`. + +Key Encryption Service (KES) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following environment variables support configuring access to +MinIO :ref:`Key Encryption Service `: + +.. envvar:: MINIO_KMS_KES_ENDPOINT + + The endpoint of the KES server. :mc:`kes server` by default binds to + port ``7373`` on all network interfaces. + +.. envvar:: MINIO_KMS_KES_KEY_FILE + + The key file of the x.509 identity to use when authenticating to the + KES server. The specified identity *must* have KES policies attached + such that it can access *at minimum* the following API endpoints: + + + + See :ref:`minio-kes-iam` for more information on KES Identity and Access + Management. + +.. envvar:: MINIO_KMS_KES_CERT_FILE + + The public certificate of the x.509 identity to use when authenticating + to the KES server. The specified identity *must* have KES policies + attached such that it can access *at minimum* the following API endpoints: + + + + See :ref:`minio-kes-iam` for more information on KES Identity and Access + Management. + +.. envvar:: MINIO_KMS_KES_KEY_NAME + + Sets the name of the Customer Master Key (CMK) to use for performing + Server-Side Encryption on the MinIO deployment. + diff --git a/source/security/encryption/minio-kes.rst b/source/security/encryption/minio-kes.rst index ab44066c..4991a05a 100644 --- a/source/security/encryption/minio-kes.rst +++ b/source/security/encryption/minio-kes.rst @@ -18,67 +18,338 @@ key-management system for high-performance applications. KES provides a bridge between applications running in bare-metal or orchestrated environments to centralised KMS solutions. - +.. image:: https://raw.githubusercontent.com/minio/kes/master/.github/arch.png + :alt: The KES server sits between the MinIO deployment and the KMS. + :width: 90% + :align: center KES is designed for simplicity, scalability, and security. It requires minimal configuration to enable full functionality and requires only basic familiarity with cryptography or key-management concepts. MinIO servers require KES for performing Server-Side Encryption (SSE) of objects -using Key Management Services (KMS). +using Key Management Services (KMS). Applications *may* use KES to support +cryptographic key operations independent of MinIO. -KES Server Process ------------------- +This page documents conceptual information about MinIO KES. For documentation +on the :mc:`kes` command line tool, see the +:doc:`KES reference page `. -.. mc:: kes server +.. _minio-kes-getting-started: -:mc:`kes server` command starts the KES server. The :mc:`kes server` process -handles requests for creating and retrieving cryptography keys from a supported -Key Management System (KMS). +Getting Started +--------------- -The command has the following syntax: +The following procedure creates a MinIO Key Encryption Service (KES) server that +generates and stores keys in-memory for use with evaluating Server Side Object +Encryption with MinIO. This configuration is appropriate for local development +*only*. **Do not** use this procedure to deploy a KES server for development or +production. + +1. Install the KES Server +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/minio-kes-installation.rst + +2. Generate a TLS Private Key and Certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +a. Issue the following command in a shell or terminal environment to generate a + self-signed TLS private key: + + .. code-block:: shell + :class: copyable + + openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key + +b. Issue the following command in a shell or terminal environment to + use the private key and generate the x.509 Certificate: + + .. code-block:: shell + :class: copyable + + openssl req -new -x509 -days 30 \ + -key server.key -out server.cert \ + -subj "/C=/ST=/L=/O=/CN=localhost" \ + -addext "subjectAltName = IP:127.0.0.1" + + The command output may include warnings about missing fields. You can + safely ignore these warnings for self-signed certificates. + +3. Create the Root Identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``kes tool identity new`` command to create the root identity. +This identity has full permissions to perform any action on the KES server: .. code-block:: shell :class: copyable - kes server --cert CERTIFICATE --key PRIVATEKEY --root ROOT_IDENTITY [OPTIONAL_FLAGS] + kes tool identity new --key=root.key --cert=root.cert root -:mc:`kes server` supports the following arguments: +The command automatically generates the ``root.key`` and ``root.cert`` +keys in the folder from which ``kes tool identity new`` runs. -.. mc-cmd:: cert - :option: +4. Start the KES server +~~~~~~~~~~~~~~~~~~~~~~~ - The location of the public certificate ``.crt`` to use for - enabling :abbr:`TLS (Transport Layer Encryption)`. +Use the :mc:`kes server` command to start the KES server: -.. mc-cmd:: config - :option: +.. code-block:: shell + :class: copyable - The path to the KES configuration file. See :ref:`minio-kes-config` for - more information on the configuration file format and contents. + kes server \ + --key=server.key \ + --cert=server.cert \ + --root=$(kes tool identity of root.cert) \ + --auth=off -.. mc-cmd:: key - :option: +The :mc-cmd-option:`~kes server auth` flag disables strict TLS certificate +validation and allows using self-signed certificates. - The location of the private key ``.key`` to use for enabling - :abbr:`TLS (Transport Layer Encryption`). +5. Connect to the KES Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. mc-cmd:: root - :option: +Set the following environment variables in a terminal or shell: - ToDo: Description +.. code-block:: shell + :class: copyable -.. mc-cmd:: port - :option: + export KES_CLIENT_KEY=root.key + export KES_CLIENT_CERT=root.cert - The port on which the :mc:`kes server` listens. +Specify the full path to the ``root.key`` and ``root.cert`` created in +:guilabel:`3. Create the Root Identity`. - Defaults to ``7373``. +You can create a new Customer Master Key using the +:mc-cmd:`kes key create` command. The command uses the environment variables +as the credentials for authenticating to the KES server: -.. _minio-kes-config: +.. code-block:: shell + :class: copyable -KES Configuration File ----------------------- + kes key create -k my-master-key -ToDo: Import https://github.com/minio/kes/wiki/Configuration , need to -include instructions on how to set the config file (directory, cli option etc.) \ No newline at end of file +KES uses the new Customer Master Key to create a Key Encryption Key (KEK). +KES uses the KEK to generate additional cryptographic keys for performing +encryption. + +6. Configure MinIO to Connect to the KES Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This step assumes access to a host machine with the :mc:`minio` installed. If +the :mc:`minio` server process is already running, this step requires restarting +that process. + +Set the following environment variables on each host which runs a MinIO server: + +.. code-block:: shell + :class: copyable + + export MINIO_KMS_KES_ENDPOINT=https://[IP | HOSTNAME]:7373 + export MINIO_KMS_KES_KEY_FILE=root.key + export MINIO_KMS_KES_CERT_FILE=root.cert + export MINIO_KMS_KES_KEY_NAME=my-master-key + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + :width: 100% + + * - Environment Variable + - Description + + * - :envvar:`MINIO_KMS_KES_ENDPOINT` + - The endpoint of the KES server. :mc:`kes server` by default binds to + port ``7373`` on all network interfaces. + + * - :envvar:`MINIO_KMS_KES_KEY_FILE` + - The key file of the x.509 identity to use when authenticating to the + KES server. Specify the full path to the ``root.key`` certificate + created in :guilabel:`3. Create the Root Identity`. + + * - :envvar:`MINIO_KMS_KES_CERT_FILE` + - The public certificate of the x.509 identity to use when authenticating + to the KES server. Specify the full path to the ``root.key`` certificate + created in :guilabel:`3. Create the Root Identity`. + + * - :envvar:`MINIO_KMS_KES_KEY_NAME` + - The name of the Customer Master Key to use for performing Server-Side + Object Encryption. + + +Next Steps +~~~~~~~~~~ + +ToDo: List of tutorials for performing cryptographic operations, possibly +SSE-C + +KES Quick Reference +------------------- + +The following table lists the high-level commands of the +:mc:`kes` command line tool: + +.. _minio-kes-iam: + +KES Identity and Access Management +---------------------------------- + +The KES server configuration includes one or more +:ref:`policies ` that associate x.509 identities +to the API endpoints which those identities can access. Client's *must* +present an x.509 certificate when connecting to the KES server. + +KES Identity +~~~~~~~~~~~~ + +This section to contain information on creating x.509 certificates for use +with KES. + +.. _minio-kes-policy: + +KES Policies +~~~~~~~~~~~~ + +The KES server provides two methods for configuring policies: + +- The :kesconf:`policy` section of the KES + :ref:`configuration file ` lists the persistent + policies for the KES server. + +- The :mc:`kes policy` command supports creating *ephemeral* policies for the + KES server. The :mc:`kes identity` command supports *ephemeral* modification + of the identities associated to policies on the KES server. + + Policies created or modified using either :mc:`kes policy` or + :mc:`kes identity` disappear after restarting the KES server. + +The following ``YAML`` document provides an example of the :kesconf:`policy` +section of the KES server configuration document. The policy ``minio-sse`` +includes the appropriate :ref:`API endpoints ` for +supporting MinIO Server-Side Encryption: + +.. code-block:: yaml + :class: copyable + + policy: + minio-sse: + paths: + - /v1/key/create/* + - /v1/key/generate/* + - /v1/key/decrypt/* + - /v1/key/delete/* + identities: + - HASH + +Each element in the :kesconf:`policy.policyname.paths` array represents an +:ref:`API endpoint ` to which the policy grants access. + +Each element in the :kesconf:`policy.policyname.identities` array represents +the hash of an x.509 certificate generated using the +:mc:`kes tool identity of` command line operation. + +.. _minio-kes-iam-root: + +KES Root Identity +~~~~~~~~~~~~~~~~~ + +The KES ``root`` identity has super-administrator access to all +:ref:`minio-kes-endpoints` and can perform any action on any resource on the KES +server. + +All KES identities consist of an x.509 certificate pair (private ``*.key`` and +public ``*.cert``). Exercise caution when storing or transmitting the ``root`` +x.509 certificates, as any client with access to these certificates can +perform super-administrator actions on the KES server. + +The KES server disables the ``root`` identity by default. To create the +``root`` identity, either: + +- Start the KES server with the :mc-cmd-option:`~kes server root` option, *or* + +- Specify :kesconf:`root : disabled ` in the KES server configuration + document. + +.. _minio-kes-endpoints: + +KES API Endpoints +----------------- + +The following section lists the available KES API endpoints as a quick +reference. For more complete documentation on syntax and usage for each +endpoint, see the :minio-git:`KES Wiki `. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + :width: 100% + + * - Endpoint + - Description + + * - ``/version`` + - Returns the version of the KES server. + + * - ``/v1/key/create`` + - Creates a cryptographic key on the KES server. + + To restrict access to a specific key prefix, specify that prefix as + an argument to the API. For example, the following endpoint pattern + allows creating keys with the prefix ``myapp``: + + .. code-block:: shell + + /v1/key/create/myapp-* + + * - ``/v1/key/import`` + - Imports a cryptographic key into the KES server. + + * - ``/v1/key/delete`` + - Deletes a cryptographic key on the KES server. + + Deleting a cryptographic key prevents decrypting any data encrypted + with that key, rendering that data permanently unreadable. Consider + restricting access to this endpoint to only those clients which require + it. + + * - ``/v1/key/generate`` + - Generates a Data Encryption Key (DEK) on the KES server. + Client's can use the DEK for performing Server-Side Object Encryption. + + * - ``/v1/key/encrypt`` + - Encrypts a plaintext value using a Data Encryption Key. + + * - ``/v1/key/decrypt`` + - Decrypts a ciphertext value using a Data Encryption Key. + + * - ``/v1/policy/write`` + - Adds a new :ref:`policy ` to the KES server. + + * - ``/v1/policy/read`` + - Retrieves an existing :ref:`policy ` from the KES + server. + + * - ``/v1/policy/list`` + - Lists all :ref:`policies ` on the KES server. + + * - ``/v1/policy/delete`` + - Deletes a :ref:`policy ` from the KES server. + + * - ``/v1/identity/assign`` + - Assigns an x.509 identity to a :ref:`policy ` on the + KES server. + + * - ``/v1/identity/list`` + - Lists all x.509 identities associated to a + :ref:`policy ` on the KES server. + + * - ``/v1/identity/forget`` + - Remove an x.509 identity associated to a :ref:`policy ` + on the KES server. + + * - ``/v1/log/audit/trace`` + - Returns a stream of audit log events produced by the KES server. + + * - ``/v1/log/log/error/trace`` + - Returns a stream of error events produced by the KES server. \ No newline at end of file diff --git a/sphinxext/minio.py b/sphinxext/minio.py index d3bef7b5..cdf07d7b 100644 --- a/sphinxext/minio.py +++ b/sphinxext/minio.py @@ -498,7 +498,9 @@ class MinIODomain(Domain): 'mc-cmd': ObjType(_('mc-cmd'), 'mc-cmd'), 'mc-cmd-option': ObjType(_('mc-cmd-option'), 'mc-cmd-option'), 'policy-action': ObjType(_('policy-action'), 'policy-action'), - 'envvar': ObjType(_('envvar'), 'envvar') + 'envvar': ObjType(_('envvar'), 'envvar'), + 'kespolicy': ObjType(_('kespolicy'), 'kespolicy'), + 'kesconf': ObjType(_('kesconf'), 'kesconf'), } directives = { 'data': MinioObject, @@ -508,7 +510,9 @@ class MinIODomain(Domain): 'mc': MinioMCCommand, 'mc-cmd': MinioMCObject, 'policy-action': MinioObject, - 'envvar': MinioObject + 'envvar': MinioObject, + 'kespolicy': MinioObject, + 'kesconf': MinioObject, } roles = { 'data': MinioXRefRole(), @@ -520,6 +524,8 @@ class MinIODomain(Domain): 'mc-cmd-option': MinioCMDOptionXRefRole(), 'policy-action': MinioXRefRole(), 'envvar': MinioXRefRole(), + 'kespolicy': MinioXRefRole(), + 'kesconf': MinioXRefRole(), } initial_data = {