minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-08-08 01:43:18 +03:00
Code Activity

KES migration

Browse Source
This commit is contained in:
ravindk89
2020-10-21 18:04:27 -04:00
parent 748f713279
commit 894f62a45e
12 changed files with 1460 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
source/includes/minio-kes-installation.rst Normal file
View File

@@ -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 <https://golang.org/doc/install>`__.
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``.

6
source/includes/minio-server-installation.rst
View File

@@ -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

1
source/index.rst
View File

@@ -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

64
source/minio-cli/kes/kes-identity.rst Normal file
View File

@@ -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 <minio-kes-policy>` 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 <minio-kes-config>`. 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.

172
source/minio-cli/kes/kes-key.rst Normal file
View File

@@ -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 <tutorial>
- 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 <kes key decrypt NAME>`.
.. 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.

145
source/minio-cli/kes/kes-policy.rst Normal file
View File

@@ -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 <minio-kes-config>`. :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
<APIVERSION>/<API>/<operation>/[<argument>/<argument>/]
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.

91
source/minio-cli/kes/kes-server.rst Normal file
View File

@@ -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 <minio-kes-getting-started>` 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`.

110
source/minio-cli/kes/kes-tool-identity.rst Normal file
View File

@@ -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 <minio-kes-getting-started>`.
- 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``

421
source/minio-cli/minio-kes-reference.rst Normal file
View File

@@ -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 <minio-kes-iam-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: <string>
cert: <string>
.. 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: <string>
unused: <string>
.. 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: <string>
audit: <string>
.. 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 <minio-kes-iam>` 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: <array>
identities: <array>
.. 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 <minio-kes-endpoints>` which
the specified :kesconf:`policy.policyname.identities` can access.
Each endpoint *must* be a glob pattern in the following form:
.. code-block:: shell
<APIVERSION>/<API>/<operation>/[<argument>/<argument>/]
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: <string>
.. 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 <TODO>.
.. code-block:: yaml
keys:
vault:
endpoint: https://[IP|HOSTNAME]
approle:
id: "<string>"
secret: "<string>"
retry: <string>
status:
ping: <string>
tls:
ca: <string>
.. 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 <https://www.vaultproject.io/docs/auth/approle>`__.
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/*

39
source/minio-server/minio-server.rst
View File

@@ -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 <minio-kes>`:
.. 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:
<list to follow>
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:
<list to follow>
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.

341
source/security/encryption/minio-kes.rst
View File

@@ -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.
<DIAGRAM>
.. 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 </minio-cli/minio-kes-reference>`.
.. 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.)
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 <minio-kes-policy>` 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 <minio-kes-config>` 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 <minio-kes-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 <minio-kes-endpoints>` 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 <root>` 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 </kes/wiki/Server-API>`.
.. 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 <minio-kes-policy>` to the KES server.
* - ``/v1/policy/read``
- Retrieves an existing :ref:`policy <minio-kes-policy>` from the KES
server.
* - ``/v1/policy/list``
- Lists all :ref:`policies <minio-kes-policy>` on the KES server.
* - ``/v1/policy/delete``
- Deletes a :ref:`policy <minio-kes-policy>` from the KES server.
* - ``/v1/identity/assign``
- Assigns an x.509 identity to a :ref:`policy <minio-kes-policy>` on the
KES server.
* - ``/v1/identity/list``
- Lists all x.509 identities associated to a
:ref:`policy <minio-kes-policy>` on the KES server.
* - ``/v1/identity/forget``
- Remove an x.509 identity associated to a :ref:`policy <minio-kes-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.

10
sphinxext/minio.py
View File

@@ -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 = {