Hashicorp Vault Keystore

本教程展示如何设置一个使用KES服务器Vault的K/V引擎作为持久且安全的密钥存储：

要启动开发服务器或使用 Vault CLI 与 Vault 交互，请下载Vault binary.

KES需要Vault K/V引擎v1 or v2以及以下任一凭证AppRole或 Kubernetes 认证方法。

如果您没有现有的 Vault 集群可用，请执行以下操作之一：

1. FollowHashicorp Vault 安装指南创建新集群
2. 创建一个单节点开发实例

以下文档讨论了如何使用单节点开发实例进行开发设置AppRole认证方法。

以下命令以开发模式启动 Vault 服务器：

vault server -dev

==> Vault server configuration:

Administrative Namespace:
             Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
   Environment Variables: 
              Go Version: go1.21.8
              Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", disable_request_limiter: "false", max_request_duration: "
1m30s", max_request_size: "33554432", tls: "disabled")
               Log Level:
                   Mlock: supported: false, enabled: false
           Recovery Mode: false
                 Storage: inmem
                 Version: Vault v1.16.1, built 2024-04-03T12:35:53Z
             Version Sha: 6b5986790d7748100de77f7f127119c4a0f78946

==> Vault server started! Log data will stream in below:

...

WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variables:

    export VAULT_ADDR='http://127.0.0.1:8200'

The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.

Unseal Key: g+epWYiEy2vj+7UP3c+YXRhoOjUMCC9PoihIzqSgB84=
Root Token: hvs.O6QNQB33ksXtMxtlRKlRZL0R

Development mode should NOT be used in production installations!

1. SetVAULT_ADDR端点

   Vault CLI 需要知道 Vault 端点：

   export VAULT_ADDR='https://127.0.0.1:8200'
   

2. SetVAULT_TOKEN

   Vault CLI 需要身份验证令牌才能执行操作。

   export VAULT_TOKEN=hvs.O6QNQB33ksXtMxtlRKlRZL0R
   

   将令牌值替换为您自己的 Vault 访问令牌，例如Root token在输出中提供的vault server -dev命令。

3. 启用K/V后端

   KES将密钥存储在Vault K/V后端。 Vault提供两种K/V引擎, v1和v2.

   MinIO 推荐使用 K/Vv1engine.

   K/V v1

   以下命令启用 K/Vv1secret engine:

   vault secrets enable -version=1 kv
   

   K/V v2

   以下命令启用 K/Vv2secret engine:

   vault secrets enable -version=2 kv
   

   The Vault policy for KES depends on the chosen K/V engine version. A policy designed for K/Vv1将无法与 K/V 配合使用v2engine. 同样，为 K/V 设计的策略v2将无法与 K/V 配合使用v1engine.

   有关从迁移的更多信息v1 to v2请参考Hashicorp 关于从 v1 升级的文档.

1. 创建 Vault 策略

   The Vault policy defines the API paths the KES server can access. 创建一个名为的文本文件kes-policy.hcl.

   策略的具体内容因所使用的K/V引擎而异。

   K/V v1

   使用以下内容kes-policy.hclK/V 策略v1后端：

   path "kv/*" {
      capabilities = [ "create", "read", "delete", "list" ]
   }
   

   K/V v2

   使用以下内容kes-policy.hclK/V 策略v2后端：

   path "kv/data/*" {
      capabilities = [ "create", "read" ]
   }
   path "kv/metadata/*" {
      capabilities = [ "list", "delete" ]       
   }
   

2. 将策略写入 Vault

   以下命令在 Vault 中创建策略：

   vault policy write kes-policy kes-policy.hcl
   

3. 启用身份验证

   This step allows the KES server to authenticate to Vault. For this tutorial, we use the此步骤允许 KES 服务器向 Vault 进行身份验证。 在本教程中，我们使用AppRole认证方法。

   vault auth enable approle
   

4. 创建 KES 角色

   以下命令添加一个名为kes-server在 Vault：

   vault write auth/approle/role/kes-server token_num_uses=0  secret_id_num_uses=0  period=5m
   

5. 将策略绑定到角色

   以下命令绑定kes-server将角色分配给kes-policy:

   vault write auth/approle/role/kes-server policies=kes-policy
   

6. 生成 AppRole ID

   为 KES 服务器请求 AppRole ID：

   vault read auth/approle/role/kes-server/role-id 
   

7. 生成 AppRole 密钥

   为 KES 服务器请求 AppRole 密钥：

   vault write -f auth/approle/role/kes-server/secret-id 
   

   AppRole 密钥显示为secret_id你可以忽略secret_id_accessor.

1. 生成 KES 服务器私钥和证书

   以下命令生成一个新的TLS私钥server.key以及一个自签名的 X.509 证书server.cert对于该IP127.0.0.1和 DNS 名称localhost(as SAN)。 如果您想使用其他IP或DNS名称（例如10.1.2.3 or https://kes.example.net, 调整--ip和/或--dns相应地调整参数。

   kes identity new --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"
   

2. 生成一个API密钥

   以下命令生成一个新的KES API密钥。

   kes identity new
   

   输出类似于以下内容：

   Your API key:
   
      kes:v1:ABfa1xsnIV0lltXQC8tHXic8lte7J6hT7EoGv6+s5QCW
   
   This is the only time it is shown. Keep it secret and secure!
   
   Your Identity:
   
      cf6c535e738c1dd47a1d746366fde7f0309d1e0a8471b9f6e909833906afbbfa
   
   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:ABfa1xsnIV0lltXQC8tHXic8lte7J6hT7EoGv6+s5QCW   
   

   生成的identity is NOT一个密钥，可以公开共享。 它将在稍后的 KES 配置文件中用作管理员身份或分配给策略。

   TheAPI key本身is一个秘密，不应共享。 您始终可以重新计算 API 密钥的身份。

3. 配置 KES 服务器

   创建 KES 服务器配置文件：config.yml.

   确保策略部分中的身份信息与client.crt身份。 添加 approlerole_id和secret_id之前获得的。

   admin:
     # Use the identity generated above by 'kes identity new'.
     identity: "" # For example: cf6c535e738c1dd47a1d746366fde7f0309d1e0a8471b9f6e909833906afbbfa
   
   tls:
     key: private.key    # The KES server TLS private key
     cert: public.crt    # The KES server TLS certificate
   
   keystore:
      vault:
        endpoint: https://127.0.0.1:8200
        version:  v1 # The K/V engine version - either "v1" or "v2".
        engine:   kv # The engine path of the K/V engine. The default is "kv".
        approle:
          id:     "" # Your AppRole ID
          secret: "" # Your AppRole Secret
   

4. 启动 KES 服务器

   Linux

   kes server --config config.yml
   

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

   使用以下命令允许 KES 使用mlock未以运行权限进行的系统调用rootprivileges:

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

   容器

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

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

   sudo podman pod create  \
     -p 9000:9000 -p 9001:9001 -p 7373:7373  \
     -v ~/minio-kes-vault/certs:/certs  \
     -v ~/minio-kes-vault/minio:/mnt/minio  \
     -v ~/minio-kes-vault/config:/etc/default/  \
     -n minio-kes-vault
   
   sudo podman run -dt  \
     --cap-add IPC_LOCK  \
     --name kes-server  \
     --pod "minio-kes-vault"  \
     -e KES_SERVER=https://127.0.0.1:7373  \
     quay.io/minio/kes:2024-01-11T13-09-29Z server  \
       --config=/etc/default/kes-config.yaml 
   

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

   sudo podman container list
   

1. SetKES_SERVER端点

   以下环境变量指定了 KES CLI 应该连接的 KES 服务器：

   export KES_SERVER=https://127.0.0.1:7373
   

2. 定义CLI访问凭据

   以下环境变量设置客户端与 KES 服务器通信时使用的密钥：

   export KES_API_KEY=kes:v1:ABfa1xsnIV0lltXQC8tHXic8lte7J6hT7EoGv6+s5QCW
   

   将值替换为您服务器的 API 密钥。 启动服务器时，服务器的 API 密钥将显示在输出中。

3. 测试配置

   例如，检查服务器状态：

   kes status -k
   

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

   kes key dek my-key-1 -k
   

   命令输出类似于以下内容：

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

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

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

以下部分介绍了使用 Hashicorp Vault Keystore 作为根 KMS 存储外部密钥的 Key Encryption Service (KES) 配置设置，例如用于 MinIO 服务器端加密的密钥。

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:
  vault:
    endpoint: ""  
    engine: ""    
    version: ""   
    namespace: "" 
    prefix: ""    
    transit:      
      engine: ""  
      key: ""     
    approle:    
      namespace: "" 
      engine: ""    
      id: ""        
      secret: ""    
    kubernetes: 
      namespace: "" 
      engine: ""    
      role: ""      
      jwt:  ""      
    tls:        
      key: ""   
      cert: ""  
      ca: ""    
    status:     
      ping: 10s 

这些额外的配置步骤可能解决特定问题。

Vault 可以作为多个隔离的 KES 租户的后端。 每个 KES 租户可以包含Nreplicas. 可以有M连接到同一 Vault 服务器/集群的 KES 租户。

这意味着N × MKES服务器实例可以连接到单个Vault。

在这些配置中，每个KES租户在K/V密钥引擎中都有独立的前缀。 每个KES租户都必须有对应的Vault策略。

• 对于 K/Vv1:

  path "kv/<tenant-name>/*" {
     capabilities = [ "create", "read", "delete" ]
  }
  

• 对于 K/Vv2:

  path "kv/data/<tenant-name>/*" {
    capabilities = [ "create", "read" ]
  }
  path "kv/metadata/<tenant-name>/*" {
    capabilities = [ "list", "delete" ]       
  }
  

为每个 KES 租户创建独立的配置文件。 该文件包含租户要使用的 Vault K/V 前缀。

keystore:
   vault:
     endpoint: https://127.0.0.1:8200
     prefix: <tenant-name>
     approle:
       id:     "" # Your AppRole ID
       secret: "" # Your AppRole Secret
       retry:  15s
     status:
       ping: 10s
     tls:
       ca: vault.crt # Manually trust the vault certificate since we use self-signed certificates

Vault可以作为多个隔离的KES租户的后端。 每个KES租户可以包含Nreplicas. 可以有M连接到同一 Vault 服务器/集群的 KES 租户。

这意味着N × MKES服务器实例可以连接到单个Vault。

因此，每个 KES 租户在 K/V 密钥引擎中都有独立的前缀。 每个 KES 租户都必须有对应的 Vault 策略。

• 对于 K/Vv1:

  path "kv/<tenant-name>/*" {
     capabilities = [ "create", "read", "delete" ]
  }
  

• 对于 K/Vv2:

  path "kv/data/<tenant-name>/*" {
     capabilities = [ "create", "read" ]
  }
  path "kv/metadata/<tenant-name>/*" {
     capabilities = [ "list", "delete" ]       
  }
  

为每个 KES 租户使用不同的配置文件。 该文件包含 KES 租户应使用的 Vault 命名空间。

keystore:
   vault:
     endpoint: https://127.0.0.1:8200
     namespace: <vault-namespace>
     approle:
       id:     "" # Your AppRole ID
       secret: "" # Your AppRole Secret
       retry:  15s
     status:
       ping: 10s
     tls:
       ca: vault.crt # Manually trust the vault certificate since we use self-signed certificates

Hashicorp’s中转该功能提供了一种加密和解密存储在保险库中的密钥的方法。 这提供了额外的加密层，在特定情况下可能很有用。

启用后，Hashicorp会在Vault中存储一个密钥，用于加密或解密存储在保险库中的其他密钥。 随后，KES使用这个由保险库管理的密钥来存储或从Vault中检索密钥。

要配置 Transit，请将以下部分添加到 KES 配置 YAML 中keystore.vaultsection:

keystore:
  vault:
    transit:      # Optionally encrypt keys stored on the K/V engine with a Vault-managed key.
      engine: ""  # The path of the transit engine - e.g. "my-transit". If empty, defaults to: transit (Vault default)
      key: ""     # The key name that should be used to encrypt entries stored on the K/V engine.

• Server API 文档
• Go SDK 文档