Azure Key Vault

本教程说明如何设置 KES 服务器以使用 Azure Key Vault 作为持久密钥存储

Azure Key Vault

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

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

Active Directory 服务
- 导航到 **Azure 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 的 **访问策略** 选项卡，然后选择 **添加访问策略** 以创建 Key Vault 策略。

定义 KES 服务器可以执行哪些 Key Vault 操作。选择以下五个 密钥权限
- 获取
- 列出
- 设置
- 删除
- 清除
将策略分配给主体

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

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

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

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

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

KES 服务器设置

生成 KES 服务器私钥和证书

KES 服务器需要 TLS 私钥和证书。KES 服务器是默认安全的，只能在 TLS 下运行。本教程出于简单起见使用自签名证书。

以下命令生成新的 TLS 私钥（private.key）和为 IP 127.0.0.1 和 DNS 名称 localhost 发行的新自签名 X.509 证书（public.crt）
```
$ 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 交换空间保护

在 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

容器

以下说明使用Podman管理容器。您也可以使用 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 访问

设置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
```

测试配置

执行上面分配的策略允许的任何 API 操作。

例如，创建密钥

kes key create my-key-1

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

kes key dek my-key-1

结果类似于以下内容

{
  plaintext : UGgcVBgyQYwxKzve7UJNV5x8aTiPJFoR+s828reNjh0=
  ciphertext: eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaWQiOiIxMTc1ZjJjNDMyMjNjNjNmNjY1MDk5ZDExNmU3Yzc4NCIsIml2IjoiVHBtbHpWTDh5a2t4VVREV1RSTU5Tdz09Iiwibm9uY2UiOiJkeGl0R3A3bFB6S21rTE5HIiwiYnl0ZXMiOiJaaWdobEZrTUFuVVBWSG0wZDhSYUNBY3pnRWRsQzJqWFhCK1YxaWl2MXdnYjhBRytuTWx0Y3BGK0RtV1VoNkZaIn0=
}

将 KES 与 MinIO 服务器一起使用

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

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

配置参考

以下部分描述了密钥加密服务 (KES) 配置设置，以使用 Azure Key Vault 作为根 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:
  azure:
    # See: https://azure.microsoft.com/services/key-vault
    keyvault:
      endpoint: "" 
      credentials:
        tenant_id: "" 
        client_id: "" 
        client_secret: "" 
      managed_identity:
        client_id: ""

参考

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

密钥	描述
`address`	KES 服务器在启动时侦听的网络地址和端口。默认为所有主机网络接口上的端口`7373`。
`root`	KES 超级用户 (`root`) 身份的身份。使用其哈希 (`kes identity of client.cert`) 与此值匹配的 TLS 证书连接的客户端可以访问所有 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-*`仅授予使用`minio-sse-`前缀的`create`、`generate`或`decrypt`密钥的访问权限。 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.azure.keyvault.endpoint`	KeyVault 端点。例如，`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)。