Entrust KeyControl

Entrust KeyControl 是 KES 支持用于存储密钥的专有 KMS。

先决条件

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

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

设置 Entrust KeyControl

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

创建新的 Vault

使用具有根级权限的用户（例如，secroot）登录您的 KeyControl 集群，并创建一个新的 **PASM** vault。

填写类似于以下内容的条目

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

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

注意：KeyControl 会向此电子邮件地址发送一次性密码，用于访问 Vault。您需要在下一步使用此密码。

根据 KeyControl 或您自己的指南填写其他必填条目。您可以将名称和描述设置为更具体地反映您的 MinIO 部署或根据您自己的指南设置。

访问新的 Vault

访问 Vault URL。

此 URL 应包含在包含一次性密码的电子邮件中。您也可以在 KeyControl 的 Vault 选项卡中找到此 URL。
使用管理员用户名和电子邮件发送的一次性密码访问 Vault。

创建新的 Box

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

按照提示进行操作，并进行类似于以下内容的条目

名称: Box 的描述性名称，例如 MinIO 租户名称。
描述: 关于 Box 中密钥的可选附加信息。
密钥过期: 保持空白。
密钥签出时长: 保持空白。
密钥轮换时长: 保持空白。

根据 KeyControl 或您自己的指南进行其他必需的条目。

附加“Vault 用户”角色策略

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

按照提示进行操作，并进行类似于以下内容的条目

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

根据 KeyControl 或您自己的指南进行其他必需的条目。

KES 服务器设置

在 KeyControl 中创建新的 Vault、Vault 中的 Box 以及用户访问策略后，您可以设置 KES 服务器。

生成 KES 服务器私钥和证书

为您的 KES 服务器生成 TLS 私钥和证书。如果您已经拥有要用于 KES 服务器的 TLS 证书，或者您有一个有效的 KES 服务器，则可以跳过此步骤。

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

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 交换空间保护

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

使用以下命令允许 KES 使用mlock 系统调用，而无需以root 权限运行

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

启动带有内存保护的 KES 服务器实例

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

KES CLI 访问

设置KES_SERVER 端点。

以下环境变量指定 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 服务器需要 KES 来启用服务器端数据加密。

请参阅 KES for MinIO 指导指南，了解将新的 KES 服务器与 MinIO 服务器一起使用所需的额外步骤。

配置参考

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

MinIO 服务器需要扩展的权限

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

YAML 概述

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

YAML 假设访问 KES 的 MinIO 部署的权限集最小。作为替代方案，您可以省略policy.minio-server 部分，而是将${MINIO_IDENTITY} 哈希设置为${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: ""

参考

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

键	描述
`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 可以创建的密钥名称范围。例如，`minio-sse-*` 仅授予使用`minio-sse-` 前缀的`create`、`generate` 或`decrypt` 密钥的访问权限。 KES 使用 mTLS 通过将 TLS 证书的哈希与每个配置的策略的`identities` 进行比较来授权连接的客户端。使用`kes identity of` 命令计算 MinIO mTLS 证书的标识，并将其添加到`policy.<NAME>.identities` 数组以将 MinIO 关联到`<NAME>` 策略。
`keys`	指定一个密钥数组，这些密钥必须存在于根 KMS 上才能使 KES 成功启动。如果密钥不存在，KES 会尝试创建它们，如果创建失败，则会退出并显示错误。在完成所有指定密钥的验证之前，KES 不会接受任何客户端请求。
`缓存`	以 `#d#h#m#s` 格式指定缓存密钥的过期时间。如果 KMS 暂时不可用，可以使用未过期的密钥。可以为 `任何` 密钥、`未使用` 密钥或 `脱机` 密钥设置条目。如果未设置，KES 将为所有密钥使用 `5m` 值，为未使用密钥使用 `20s` 值，为脱机密钥使用 `0s` 值。
`日志`	启用或禁用将 `错误` 和 `审核` 类型的日志事件输出到控制台。
`keystore.entrust.keycontrol.endpoint`	KeyControl 端点。例如，`https://keycontrol.my-org.com`。
`keystore.entrust.keycontrol.vault_id`	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 证书的路径。

Entrust KeyControl

先决条件

设置 Entrust KeyControl

创建新的 Vault

访问新的 Vault

创建新的 Box

附加“Vault 用户”角色策略

KES 服务器设置

生成 KES 服务器私钥和证书

生成新的 API 密钥

配置 KES 服务器

启动 KES 服务器

KES CLI 访问

将 KES 与 MinIO 服务器一起使用

配置参考

参考资料