Thales CipherTrust Manager（前身为 Gemalto KeySecure）

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

本指南假设您已有一个正在运行的CipherTrust Manager实例。该指南已通过CipherTrust Manager测试验证。k170v版本2.0.0和 Gemalto KeySecurek170v版本1.9.1和1.10.0.

CipherTrust Manager 设置

要连接到您的 CipherTrust Manager 实例，请通过ksctlCLI 你需要一个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
```
为群组创建新用户

这会打印一个包含 a 的 JSON 对象user_id后续步骤所需。如果您已有现有用户想要分配给KES-Servicegroup，跳过此步骤并继续执行 3。
```
ksctl users create --name <username> --pword '<password>'
```
将用户分配到KES-Service在步骤1中创建的组
```
ksctl groups adduser --name KES-Service --userid "<user-ID>"
```
用户ID在创建用户时显示。否则，请通过以下方式获取ID：ksctl users list命令。

用户ID类似于：local|8791ce13-2766-4948-a828-71bac67131c9.
制定一项关于KES-Servicegroup

创建一个名为的文本文件kes-policy.json授予成员KES-Servicegroup创建, 读取和删除权限。文件内容应类似于以下内容：
```
{                                                                                          
  "allow": true,
  "name": "kes-policy",
  "actions":[
      "CreateKey",
      "ExportKey",
      "ReadKey",
      "DeleteKey"
  ],
  "resources": [
      "kylo:kylo:vault:secrets:*"
  ]
}
```
This policy allows KES to create, fetch and delete master keys. If you want to prevent KES from e.g. deleting master keys omit the删除键动作。

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

使用以下命令通过上面创建的文件来创建策略。
```
ksctl policy create --jsonfile kes-policy.json
```

将策略附加到KES-Servicegroup

创建一个名为kes-attachment.json根据策略附件规范：

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

使用以下命令来附加kes-policy到KES-Servicegroup:

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-Servicegroup.

该命令输出一个类似于以下内容的刷新令牌：
```
CEvk5cdHLG7si05LReIeDbXE3PKD082YdUFAnxX75md3jzV0BnyHyAmPPJiA0
```

KES Server Setup

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 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 identity new --key=app.key --cert=app.cert app

你可以计算app随时更改身份。

kes 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 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 实例将提供一个既没有通用名称（主题）也没有主题备用名称（SAN）的 TLS 证书。此类证书是无效的。请更新您的 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 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 Server 需要 KES 来启用服务器端数据加密。

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

配置参考

以下部分介绍了使用泰雷兹 CipherTrust Manager（前身为 Gemalto KeySecure）作为根 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:
  gemalto:
    keysecure:
      endpoint: ""   
      credentials:   
        token: ""    
        domain: ""   
        retry: 15s   
      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.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 证书路径。