Thales CipherTrust Manager（前身为 Gemalto KeySecure）

本教程演示如何设置 KES 服务器，该服务器使用 Thales CipherTrust Manager 实例（以前称为 Gemalto KeySecure）作为持久且安全的密钥存储。

本指南假定您已有一个正在运行的 CipherTrust Manager 实例。它已在 CipherTrust Manager k170v 版本 2.0.0 和 Gemalto KeySecure k170v 版本 1.9.1 和 1.10.0 上进行了测试。

CipherTrust Manager 设置

要通过 ksctl CLI 连接到您的 CipherTrust Manager 实例，您需要一个类似于以下内容的 config.yaml 文件

KSCTL_URL: <your-keysecure-endpoint>
KSCTL_USERNAME: <your-user/admin-name>
KSCTL_PASSWORD: <your-user/admin-password>
KSCTL_VERBOSITY: false
KSCTL_RESP: json
KSCTL_NOSSLVERIFY: true
KSCTL_TIMEOUT: 30

请确保使用 KSCTL_URL、KSCTL_USERNAME 和 KSCTL_PASSWORD 的正确值。如果您的 CipherTrust Manager 实例已使用您的机器信任的 TLS 证书进行配置，那么您也可以设置 KSCTL_NOSSLVERIFY: false。

为 KES 创建一个新组
```
ksctl groups create --name KES-Service
```
为该组创建一个新用户

这将打印一个包含 user_id 的 JSON 对象，该对象在后面的步骤中需要。如果您已经有要分配给 KES-Service 组的现有用户，请跳过此步骤，继续进行步骤 3。
```
ksctl users create --name <username> --pword '<password>'
```
将用户分配给步骤 1 中创建的 KES-Service 组
```
ksctl groups adduser --name KES-Service --userid "<user-ID>"
```
创建用户时会打印用户 ID。否则，使用 ksctl users list 命令获取 ID。

用户 ID 类似于：local|8791ce13-2766-4948-a828-71bac67131c9。

为 KES-Service 组创建一个策略

创建一个名为 kes-policy.json 的文本文件，该文件授予 KES-Service 组成员创建、读取和删除权限。该文件的内容应类似于以下内容

{                                                                                          
  "allow": true,
  "name": "kes-policy",
  "actions":[
      "CreateKey",
      "ExportKey",
      "ReadKey",
      "DeleteKey"
  ],
  "resources": [
      "kylo:kylo:vault:secrets:*"
  ]
}

此策略允许 KES 创建、获取和删除主密钥。如果您想阻止 KES 删除主密钥（例如），请省略 DeleteKey 操作。

同样，您可以通过 resources 定义来限制 KES 可以访问的主密钥。

使用以下命令，使用上面创建的文件创建策略。

ksctl policy create --jsonfile kes-policy.json

将策略附加到 KES-Service 组

创建一个名为 kes-attachment.json 的文件，其中包含策略附加规范

{                                                                                          
   "cust": {
      "groups": ["KES-Service"]
   }
}

使用以下命令将 kes-policy 附加到 KES-Service 组

ksctl polattach create -p kes-policy -g kes-attachment.json

为 KES 服务器创建一个刷新令牌，用于获取短期身份验证令牌。

以下命令将返回一个新的刷新令牌
```
ksctl tokens create --user <username> --password '<password>' --issue-rt | jq -r .refresh_token
```
将<username>和<password>替换为KES-Service组成员用户的凭据。

该命令输出类似于以下的刷新令牌
```
CEvk5cdHLG7si05LReIeDbXE3PKD082YdUFAnxX75md3jzV0BnyHyAmPPJiA0
```

KES 服务器设置

KES 服务器需要一个 TLS 私钥和证书。

KES 服务器是默认安全的，只能在 TLS 模式下运行。本教程使用自签名证书以简化操作。

对于生产环境，我们强烈建议使用由受信任的证书颁发机构签名的证书。这可以是您的内部 CA 或者公共 CA，例如Let's Encrypt。

为 KES 服务器生成一个 TLS 私钥和证书

以下命令生成一个新的 TLS 私钥server.key和一个自签名的 X.509 证书server.cert，该证书为 IP 127.0.0.1 和 DNS 名称localhost（作为 SAN）颁发。根据您的设置自定义该命令。
```
kes tool identity new --server --key server.key --cert server.cert --ip "127.0.0.1" --dns localhost
```
任何其他 X.509 证书生成工具都可以使用。例如，您可以使用openssl
```
openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key

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"
```

为应用程序创建私钥和证书

kes tool identity new --key=app.key --cert=app.cert app

您可以随时计算app身份。

kes tool identity of app.cert

创建配置文件 server-config.yml

address: 0.0.0.0:7373
root:    disabled  # We disable the root identity since we don't need it in this guide 

tls:
  key:  server.key
  cert: server.cert

policy:    
  my-app: 
    allow:
    - /v1/key/create/my-app*
    - /v1/key/generate/my-app*
    - /v1/key/decrypt/my-app*
    identities:
    - ${APP_IDENTITY}

keystore:
  gemalto:
    keysecure:
      endpoint: ""  # The REST API endpoint of your KeySecure instance - e.g. https://127.0.0.1
      credentials:
        token:  ""  # Your refresh token
        domain: ""  # Your domain. If empty, defaults to root domain.
        retry:  15s
      tls:
        ca: "" # Optionally, specify the certificate of the CA that issued the KeySecure TLS certificate.

使用您的刷新令牌。

在新窗口/标签页中启动 KES 服务器
```
export APP_IDENTITY=$(kes tool identity of app.cert)

kes server --config=server-config.yml --auth=off
```
该命令使用--auth=off，因为我们的root.cert和app.cert证书是自签名的。

如果启动服务器失败并出现类似以下的错误消息
```
x509: certificate is not valid for any names, but wanted to match <your-endpoint>
```
那么您的 CipherTrust Manager 实例提供的 TLS 证书既没有通用名（主体）也没有主体备用名称（SAN）。这样的证书是无效的。更新您的 CipherTrust Manager 实例的 TLS 证书。

您可以使用以下命令分析证书：openssl x509 -text -noout <certificate>

在另一个窗口或标签页中，连接到服务器

export KES_CLIENT_CERT=app.cert
export KES_CLIENT_KEY=app.key
kes key create -k my-app-key

export APP_IDENTITY=$(kes tool identity of app.cert)

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

该命令使用--auth=off，因为我们的root.cert和app.cert证书是自签名的。

从之前创建的my-app-key中派生和解密数据密钥

kes key derive -k my-app-key
{
  plaintext : ...
  ciphertext: ...
}

kes key decrypt -k my-app-key <base64-ciphertext>

使用 KES 与 MinIO 服务器

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

有关将新 KES 服务器与 MinIO 服务器一起使用所需的额外步骤，请参阅用于 MinIO 的 KES 指令指南。

配置参考

以下部分描述了使用 Thales CipherTrust Manager（前身为 Gemalto KeySecure）作为根 KMS 来存储外部密钥（例如用于 MinIO 服务器上的服务器端加密的密钥）的密钥加密服务 (KES) 配置设置。

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:
  gemalto:
    keysecure:
      endpoint: ""   
      credentials:   
        token: ""    
        domain: ""   
        retry: 15s   
      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-`前缀创建、生成或解密密钥的访问权限。 KES 使用 mTLS 通过将 TLS 证书的哈希与每个配置策略的`identities`进行比较来授权连接的客户端。使用`kes identity of`命令计算 MinIO mTLS 证书的标识，并将其添加到`policy.<NAME>.identities`数组中，以将 MinIO 关联到`<NAME>`策略。
`keys`	指定一个密钥数组，这些密钥必须存在于根 KMS 上，才能使 KES 成功启动。如果密钥不存在，KES 会尝试创建密钥，如果无法创建其中一个或多个密钥，则会退出并显示错误。在完成对所有指定密钥的验证之前，KES 不会接受任何客户端请求。
`cache`	指定以`#d#h#m#s`格式缓存的密钥的过期时间。如果 KMS 暂时不可用，则可以使用未过期的密钥。可以为`any`密钥、`unused`密钥或`offline`密钥设置条目。如果未设置，KES 将对所有密钥使用`5m`的值，对未使用密钥使用`20s`的值，对离线密钥使用`0s`的值。
`log`	启用或禁用将`error`和`audit`类型日志事件输出到控制台。
`keystore.gemalto.keysecure.endpoint`	KeySecure 端点，例如`https://127.0.0.1`
`keystore.gemalto.keysecure.credentials`	访问 KeySecure 实例的身份验证。
`keystore.gemalto.keysecure.credentials.token`	用于获取新的短期身份验证令牌的刷新令牌。
`keystore.gemalto.keysecure.credentials.domain`	刷新令牌有效的 KeySecure 域。如果为空，则默认为根域。
`keystore.gemalto.keysecure.credentials.retry`	KES 服务器在连接丢失后尝试重新身份验证之前等待的时间。例如，`15s`。
`keystore.gemalto.keysecure.tls`	KeySecure 客户端 TLS 配置
`keystore.gemalto.keysecure.tls.ca`	用于验证 KeySecure TLS 证书的一个或多个 PEM 编码 CA 证书的路径。