Azure Key Vault

本教程介绍如何设置 KES 服务器Azure Key Vault作为持久密钥存储：

Azure Key Vault

Azure Key Vault 是一种托管式 KMS 服务，它提供了一个可供 KES 使用的密钥存储库。

作为外部应用程序，您必须注册 KESAzure Active Directory并拥有客户端凭据，用于在 Azure Key Vault 中存储和访问机密。

Active Directory 服务
- Navigate toAzure Active Directory并选择应用注册.
- 选择新注册
注册 KES 应用

给应用程序命名，例如KES-Demo，并注册它。完成后，Azure 将显示有关新注册应用程序的一些详细信息。

请记下以下字段以备后用：
- 应用程序（客户端）ID
- 目录（租户）ID
这些字段包含通用唯一标识符（UUID），类似于c3b7badf-cd2b-4297-bece-4de5f2e575f6.
创建客户端密钥
- 选择添加证书或密钥
- 指定一个名称，例如KES-Demo
- 选择过期时间
Azure 使用选定的描述和过期时间创建一个新的密钥。 KES 需要使用此密钥向 Azure Key Vault 进行身份验证。

请务必复制该密钥值。它可能不会再次显示。
应用摘要

导航回应用程序概览，并检查 Azure 是否显示该应用程序有一个密钥。

您应具备以下信息：
- 应用程序（客户端）ID
  
  在我们的示例图像中，c3b7badf-cd2b-4297-bece-4de5f2e575f6.
- 目录（租户）ID
  
  在我们的示例图像中，41a37d4e-b3c4-49f4-b330-1114fb0271c8.
- 新创建的密钥的值
  
  在我们的示例图像中，-.j4XP6Sa7E39.KWn-SL~Dgbz~H-H-TPxT.
添加 Key Vault 策略

导航到 Key Vault访问策略选项卡和选择添加访问策略Create Key Vault policies.

定义 KES 服务器可以执行的 Key Vault 操作。选择以下五个Secret permissions:
- 获取
- 列表
- Set
- 删除
- 清除
为主体分配策略

选择一个主体或已授权的应用程序。

如果应用程序本身是主体，则无需授权应用程序。或者，选择用户或组作为主体，并选择新注册的KES Azure应用程序作为授权应用程序。

对于本教程，我们将主体设置为我们添加的密钥。搜索应用程序的名称（KES-Demo) 或添加应用程序 ID。
策略摘要

Azure 显示与我们的已注册 KES 应用程序关联的新访问策略。

确保你保存在导航到其他位置之前。

KES Server Setup

生成 KES 服务器私钥和证书

KES服务器需要TLS私钥和证书。 KES服务器是一个默认安全并且只能通过 TLS 运行。本教程为简化起见使用自签名证书。

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

  Private key:  private.key
  Certificate:  public.crt
  Identity:     2e897f99a779cf5dd147e58de0fe55a494f546f4dcae8bc9e5426d2b5cd35680
```
如果你已经有来自 WebPKI 或内部 CA 的 TLS 私钥和证书，你可以使用它们代替。记得调整tls配置部分。

生成客户端凭据

使用以下命令为客户端应用程序生成新的 TLS 私钥/公钥对，用于访问 KES 服务器：

$ kes identity new --key=client.key --cert=client.crt MyApp

  Private key:  client.key
  Certificate:  client.crt
  Identity:     02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b

身份02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b是公钥的唯一指纹client.crt您可以随时重新计算指纹：

$ kes identity of client.crt

  Identity:  02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b

配置 KES 服务器

创建 KES服务器配置文件: config.yml确保策略部分中的身份信息与您的相符client.crt身份。

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:
    - 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b # Use the identity of your client.crt

keystore:
     azure:
       keyvault:
         endpoint: "https://kes-test-1.vault.azure.net"    # Use your KeyVault instance endpoint.
         credentials:
           tenant_id: ""      # The ID of the tenant the client belongs to - e.g: "41a37d4e-b3c4-49f4-b330-1114fb0271c8".
           client_id: ""      # The ID of the client                       - e.g: "c3b7badf-cd2b-4297-bece-4de5f2e575f6".
           client_secret: ""  # The value of the client secret             - e.g: "-.j4XP6Sa7E39.KWn-SL~Dgbz~H-H-TPxT".

启动 KES 服务器

Linux

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

容器

以下说明使用Podmanto manage the containers. 你也可以使用 Docker。

根据您的部署需求修改地址和文件路径。

sudo podman pod create  \
  -p 9000:9000 -p 9001:9001 -p 7373:7373  \
  -v ~/minio-kes-azure/certs:/certs  \
  -v ~/minio-kes-azure/minio:/mnt/minio  \
  -v ~/minio-kes-azure/config:/etc/default/  \
  -n minio-kes-azure

sudo podman run -dt  \
  --cap-add IPC_LOCK  \
  --name kes-server  \
  --pod "minio-kes-azure"  \
  -e KES_SERVER=https://127.0.0.1:7373  \
  -e KES_CLIENT_KEY=/certs/kes-server.key  \
  -e KES_CLIENT_CERT=/certs/kes-server.cert  \
  quay.io/minio/kes:2024-01-11T13-09-29Z server  \
    --auth  \
    --config=/etc/default/kes-config.yaml  \

sudo podman run -dt  \
  --name minio-server  \
  --pod "minio-kes-azure"  \
  -e "MINIO_CONFIG_ENV_FILE=/etc/default/minio"  \
  quay.io/minio/minio:RELEASE.2024-01-31T20-20-33Z server  \
    --console-address ":9001"

您可以使用以下命令验证容器的状态。该命令应显示三个 Pod，一个用于 Pod，一个用于 KES，一个用于 MinIO。

sudo podman container list

KES CLI 访问

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

测试配置

执行我们上面分配的策略允许的任何 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 服务器配合使用所需的额外步骤。

配置参考

以下部分介绍了使用 Azure Key Vault 作为根 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:
  azure:
    # See: https://azure.microsoft.com/services/key-vault
    keyvault:
      endpoint: "" 
      credentials:
        tenant_id: "" 
        client_id: "" 
        client_secret: "" 
      managed_identity:
        client_id: ""

参考

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

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.azure.keyvault.endpoint`	密钥保管库终结点。例如，`https://my-instance.vault.azure.net`.
`keystore.azure.keyvault.credentials.tenant_id`	客户端所属租户的 ID (UUID)，用于向 KeyVault 进行身份验证。
`keystore.azure.keyvault.credentials.client_id`	用于向 KeyVault 进行身份验证的客户端 ID (UUID)。
`keystore.azure.keyvault.credentials.client_secret`	客户端密钥的值。
`keystore.azure.keyvault.managed_identity.client_id`	客户端的 Azure 托管标识（UUID）。

KES Documentation

Azure Key Vault

Azure Key Vault

KES Server Setup

KES CLI 访问

使用 KES 与 MinIO 服务器

配置参考

参考文献