Entrust KeyControl

Entrust KeyControl是一个专有的KMS，KES支持使用它来存储密钥。

前提条件

本程序基于Entrust KeyControl v10.1编写和测试。所提供的说明可能适用于其他KeyControl版本。本程序假设您已具备Entrust产品的使用经验，并遵循其文档、最佳实践和其他已发布材料来部署KeyControl服务。

有关设置 Entrust KeyControl 集群的说明，请参阅 Entrust 文档：

设置 Entrust KeyControl

在设置 KES 服务器之前，请先在 KeyControl 中完成以下部分以添加新的 Vault、Box 以及一个或多个用户。

创建一个新的保险库

使用具有根级权限的用户登录到您的KeyControl集群（例如，secroot) 并创建一个新的PASMvault.

创建类似以下内容的条目：

类型: PASM
名称: minio
描述保险库的可选附加信息，或留空。
管理员名称用于管理保险库的用户名。

注意：此用户拥有对 Vault 的完全访问权限。
管理员邮箱保管库管理员的电子邮件地址

注意：KeyControl 会向此电子邮件地址发送一次性密码以访问保险库。您需要在下一步中使用此密码。

根据 KeyControl 或您自己的指南进行其他必要的设置。您可以将名称和描述设置为更符合您的 MinIO 部署需求，或根据您自己的指南进行设置。

访问新的 Vault

访问 Vault URL。

此 URL 应随一次性密码一同出现在电子邮件中。您也可以从 KeyControl 的 Vault 选项卡中找到该 URL。
使用管理员用户名和通过电子邮件发送的一次性密码来访问 Vault。

创建一个新的 Box

KeyControl 将密钥存储在 Vault 内的 Box 中。添加一个 Box 来存储您的密钥。

按照提示进行操作，并输入类似以下内容：

名称框的描述性名称，例如MinIO租户名称。
描述有关框中密钥的可选附加信息。
Secret Expiration留空。
Secret Checkout Duration留空。
密钥轮换持续时间留空。

根据 KeyControl 或您自己的指南进行其他必要录入。

附加 'Vault User' 角色策略

KeyControl 使用基于角色的访问控制。添加一个策略，其中包含Vault User角色并将策略附加到 KES 使用的用户账户。

按照提示进行操作，并输入类似以下内容：

名称KES 服务。
描述策略的可选详细描述。
角色Vault 用户角色。
用户KeyControl 账户 KES 用于访问密钥。
Box从下拉菜单中选择您在上一步中添加的方框。
Secrets所有密钥。

根据 KeyControl 或您自己的指南进行其他必要录入。

KES Server Setup

在创建新的保险库、保险库内的box以及KeyControl中的用户访问策略后，您可以设置KES服务器。

生成 KES 服务器私钥和证书

为您的 KES 服务器生成 TLS 私钥和证书。如果您已有要用于 KES 服务器的 TLS 证书或正在运行的 KES 服务器，可以跳过此步骤。

以下命令生成一个新的 TLS 私钥（private.key) 和一个自签名的 X.509 证书 (public.crt) 为该 IP 地址签发127.0.0.1和 DNS 名称localhost.

kes identity new --key private.key --cert public.crt --ip "127.0.0.1" --dns localhost

输出类似于以下内容：

Your API key:

   kes:v1:APvbt/zbiewXNB+EwciOT+I21peq0odFYCwkJX8mMCxM

This is the only time it is shown. Keep it secret and secure!

Your Identity:

   1d1f89ad528a3bbb8fd64252d443c993f5a4d679b074d5bad49785e02ec38199

The identity is not a secret. It can be shared. Any peer
needs this identity in order to verify your API key.

The generated TLS private key is stored at: private.key
The generated TLS certificate is stored at: public.crt

The identity can be computed again via:

    kes identity of kes:v1:APvbt/zbiewXNB+EwciOT+I21peq0odFYCwkJX8mMCxM
    kes identity of public.crt

生成一个新的API密钥

客户端应用程序需要凭据才能访问 KES 服务器。以下命令用于生成新的 API 密钥。

kes identity new

生成的密钥类似于：

Your API key:

   kes:v1:AOlQZJRMYZeOioGk0ubYBMSFt1w6Hh1QZl3zG4PQxK/g

This is the only time it is shown. Keep it secret and secure!

Your Identity:

   eb559798a2fbcc3efbf036bed11108116e63f293324abdfe7574249ef5e56b36

The identity is not a secret. It can be shared. Any peer
needs this identity in order to verify your API key.

The identity can be computed again via:

    kes identity of kes:v1:AOlQZJRMYZeOioGk0ubYBMSFt1w6Hh1QZl3zG4PQxK/g

配置 KES 服务器

创建 KES 服务器配置文件：config.yml确保策略部分中的身份标识与您的 API 密钥身份标识一致。

address: 0.0.0.0:7373 # Listen on all network interfaces on port 7373

admin:
  identity: disabled  # We disable the admin identity since we don't need it in this guide 
   
tls:
  key: private.key    # The KES server TLS private key
  cert: public.crt    # The KES server TLS certificate
   
policy:
  my-app: 
    allow:
    - /v1/key/create/my-key*
    - /v1/key/generate/my-key*
    - /v1/key/decrypt/my-key*
    identities:
    - eb559798a2fbcc3efbf036bed11108116e63f293324abdfe7574249ef5e56b36 # Use the identity of your API key
   
keystore:
     entrust:
       keycontrol:
         endpoint: "https://keycontrol.my-org.com"    # Use your KeyControl instance endpoint.
         vault_id: ""                                 # The Vault ID - e.g: "e30497c1-bff7-4e81-beb7-fb35c4b7410c".
         box_id:   ""                                 # The Box name or ID - e.g: "tenant-1".
         credentials:
           username: ""                               # KeyControl username - e.g: "kes-tenant-1@my-org.com".
           password: ""                               # Password of KeyControl user

启动 KES 服务器

使用您创建的 YAML 文件启动 KES 服务器实例。

kes server --config config.yml --auth off

Linux Swap Protection

在 Linux 环境中，KES 可以使用mlocksyscall 防止操作系统将内存中的数据写入磁盘（交换）。这可以防止敏感数据泄露。

使用以下命令允许 KES 使用mlock未以运行权限进行的系统调用rootprivileges:

sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))

启动一个具有内存保护功能的 KES 服务器实例：

kes server --config config.yml --auth off --mlock

KES CLI 访问

设置KES_SERVEREndpoint.

以下环境变量指定了 KES CLI 应连接的服务器：
```
$ export KES_SERVER=https://127.0.0.1:7373
```
定义客户端凭据。

以下环境变量设置客户端与 KES 服务器通信时使用的访问凭证：
```
$ export KES_CLIENT_CERT=client.crt
```
```
$ export KES_CLIENT_KEY=client.key
```

测试配置。

执行KES服务器配置文件中定义的策略所允许的任何API操作。

例如，创建一个密钥：

$ kes key create my-key-1

使用密钥生成新的数据加密密钥：

$ kes key dek my-key-1
{
  plaintext : UGgcVBgyQYwxKzve7UJNV5x8aTiPJFoR+s828reNjh0=
  ciphertext: eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaWQiOiIxMTc1ZjJjNDMyMjNjNjNmNjY1MDk5ZDExNmU3Yzc4NCIsIml2IjoiVHBtbHpWTDh5a2t4VVREV1RSTU5Tdz09Iiwibm9uY2UiOiJkeGl0R3A3bFB6S21rTE5HIiwiYnl0ZXMiOiJaaWdobEZrTUFuVVBWSG0wZDhSYUNBY3pnRWRsQzJqWFhCK1YxaWl2MXdnYjhBRytuTWx0Y3BGK0RtV1VoNkZaIn0=
}

使用 KES 与 MinIO 服务器

MinIO Server 需要 KES 来启用服务器端数据加密。

查看MinIO KES 操作指南有关将新的 KES 服务器与 MinIO 服务器配合使用所需的额外步骤。

配置参考

以下部分介绍了使用 Entrust KeyControl 作为根 KMS 存储外部密钥的 Key Encryption Service (KES) 配置设置，例如用于 MinIO 服务器端加密的密钥。

MinIO Server 需要扩展权限

从MinIO Server RELEASE.2023-02-17T17-52-43ZMinIO 需要扩展的 KES 权限才能实现功能。本节中的示例配置包含所有必需的权限。

YAML 概述

带有${<STRING>}使用匹配的环境变量<STRING>值。您可以使用此功能设置凭据，而无需将其写入配置文件。

YAML 假设 MinIO 部署访问 KES 时具有最小权限集。作为替代方案，您可以省略policy.minio-serversection 并改为设置${MINIO_IDENTITY}hash 作为${ROOT_IDENTITY}.

address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}

tls:
  key: kes-server.key
  cert: kes-server.cert

api:
  /v1/ready:
    skip_auth: false
    timeout:   15s

policy:
  minio-server:
    allow:
    - /v1/key/create/*
    - /v1/key/generate/*
    - /v1/key/decrypt/*
    - /v1/key/bulk/decrypt
    - /v1/key/list/*
    - /v1/status
    - /v1/metrics
    - /v1/log/audit
    - /v1/log/error
    deny:
    - /v1/key/generate/my-app-internal*
    - /v1/key/decrypt/my-app-internal*
    identities:
    - ${MINIO_IDENTITY}

    my-app:
    allow:
    - /v1/key/create/my-app*
    - /v1/key/generate/my-app*
    - /v1/key/decrypt/my-app*
    deny:
    - /v1/key/generate/my-app-internal*
    - /v1/key/decrypt/my-app-internal*
    identities:
    - df7281ca3fed4ef7d06297eb7cb9d590a4edc863b4425f4762bb2afaebfd3258
    - c0ecd5962eaf937422268b80a93dde4786dc9783fb2480ddea0f3e5fe471a731

keys:
  - name: "minio-encryption-key-alpha"
  - name: "minio-encryption-key-baker"
  - name: "minio-encryption-key-charlie"

cache:
  expiry:
    any: 5m0s
    unused: 20s
    offline: 0s

log:

  # Log error events to STDERR. Valid values are "on" or "off". 
  # Default is "on".
  error: on

  # Log audit events to STDOUT. Valid values are "on" and "off". 
  # Default is "off".
  audit: off

keystore:
  entrust:
    # https://www.entrust.com/digital-security/key-management/keycontrol
    keycontrol:
      endpoint: "" 
      vault_id: "" 
      box_id:   "" 
      credentials:
        username: ""  
        password: ""  
      tls:
        ca: ""

参考

有关完整文档，请参阅配置页面.

Key	描述
`address`	KES服务器启动时监听的网络地址和端口。默认端口为`7373`在所有主机网络接口上。
`root`	KES超级用户的身份（`root`) 身份。使用TLS证书连接的客户端，其哈希值(`kes identity of client.cert`) 匹配此值的实体有权访问所有 KES API 操作。指定`disabled`移除根身份并仅依赖于`policy`用于控制 KES 身份和访问管理的配置。
`tls`	KES 用于建立 TLS 安全通信的 TLS 私钥和证书。请同时指定私钥和证书的完整路径。`.key`和公共`.cert`到`key`和`cert`字段，分别。
`policy`	指定一个或多个策略用于控制对 KES 服务器的访问。MinIO SSE 需要访问以下 KES 加密 API： `/v1/key/create/` `/v1/key/generate/` `/v1/key/decrypt/` 指定额外的密钥不会扩展 MinIO SSE 功能，且可能违反关于向客户端提供不必要的加密密钥操作访问权限的安全最佳实践。您可以通过在 MinIO 创建密钥名称前指定前缀来限制其执行 SSE 时的密钥名称范围`.`例如，`minio-sse-*`仅授予访问权限`create`, `generate`或`decrypt`使用密钥`minio-sse-`prefix. KES 使用 mTLS 对连接客户端进行授权，通过将 TLS 证书的哈希值与`identities`每个已配置策略的。使用`kes identity of`命令用于计算 MinIO mTLS 证书的身份并将其添加到`policy.<NAME>.identities`将数组关联到 MinIO`<NAME>`policy.
`keys`	指定一个键的数组必须必须存在于根 KMS 上，KES 才能成功启动。如果这些密钥不存在，KES 会尝试创建它们；如果未能创建一个或多个密钥，则会退出并报错。在完成对所有指定密钥的验证之前，KES 不会接受任何客户端请求。
`cache`	指定缓存密钥的过期时间`#d#h#m#s`格式。在 KMS 暂时不可用的情况下，可以使用未过期的密钥。条目可以设置为`any`key,`unused`键，或`offline`keys. 如果未设置，KES将使用以下值：`5m`对于所有键，`20s`对于未使用的密钥，`0s`对于离线密钥。
`log`	启用或禁用输出`error`和`audit`将日志事件输出到控制台。
`keystore.entrust.keycontrol.endpoint`	KeyControl 端点。例如，`https://keycontrol.my-org.com`.
`keystore.entrust.keycontrol.vault_id`	The Vault ID. 例如，`e30497c1-bff7-4e81-beb7-fb35c4b7410c`.
`keystore.entrust.keycontrol.box_id`	Box 名称或 ID。例如，`tenant-1`.
`keystore.entrust.keycontrol.credentials.username`	能够访问Vault和Box的用户名。
`keystore.entrust.keycontrol.credentials.password`	用户密码。
`keystore.entrust.keycontrol.tls.ca`	用于验证 KeyControl TLS 证书的一个或多个 PEM 编码 CA 证书的路径。

KES Documentation

Entrust KeyControl

前提条件

设置 Entrust KeyControl

创建一个新的保险库

访问新的 Vault

创建一个新的 Box

附加 'Vault User' 角色策略

KES Server Setup

生成 KES 服务器私钥和证书

生成一个新的API密钥

配置 KES 服务器

启动 KES 服务器

KES CLI 访问

使用 KES 与 MinIO 服务器

配置参考

参考文献