Hashicorp Vault 金鑰儲存庫

本教學說明如何設定 KES 伺服器，該伺服器使用 Vault 的 K/V 引擎作為持久且安全的金鑰儲存庫

若要啟動開發伺服器或使用 Vault CLI 與 Vault 互動，請下載 Vault 二進位檔。

KES 需要 Vault K/V 引擎 v1 或 v2，以及 AppRole 或 Kubernetes 驗證方法的憑證。

如果您沒有現有的 Vault 叢集可用，請執行下列其中一項

1. 依照 Hashicorp 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. 設定 VAULT_ADDR 端點

   Vault CLI 需要知道 Vault 端點

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

2. 設定 VAULT_TOKEN

   Vault CLI 需要驗證權杖才能執行操作。

   export VAULT_TOKEN=hvs.O6QNQB33ksXtMxtlRKlRZL0R
   

   將權杖值取代為您自己的 Vault 存取權杖，例如 vault server -dev 命令輸出中提供的 Root token。

3. 啟用 K/V 後端

   KES 會將金鑰儲存在 Vault K/V 後端。Vault 提供兩個 K/V 引擎，v1 和 v2。

   MinIO 建議使用 K/V v1 引擎。

   K/V v1

   以下命令會啟用 K/V v1 機密引擎

   vault secrets enable -version=1 kv
   

   K/V v2

   以下命令會啟用 K/V v2 機密引擎

   vault secrets enable -version=2 kv
   

   KES 的 Vault 政策取決於所選的 K/V 引擎版本。為 K/V v1 設計的政策不適用於 K/V v2 引擎。同樣地，為 K/V v2 設計的政策不適用於 K/V v1 引擎。

   如需有關從 v1 移轉至 v2 的詳細資訊，請參閱 Hashicorp 文件，關於從 v1 升級。

1. 建立 Vault 政策

   Vault 政策定義 KES 伺服器可以存取的 API 路徑。建立名為 kes-policy.hcl 的文字檔。

   政策的內容會因使用的 K/V 引擎而異。

   K/V v1

   針對 K/V v1 後端使用以下 kes-policy.hcl 政策

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

   K/V v2

   針對 K/V v2 後端使用以下 kes-policy.hcl 政策

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

2. 將政策寫入 Vault

   以下命令會在 Vault 中建立政策

   vault policy write kes-policy kes-policy.hcl
   

3. 啟用驗證

   此步驟允許 KES 伺服器向 Vault 驗證。在本教學中，我們使用 AppRole 驗證方法。

   vault auth enable approle
   

4. 建立 KES 角色

   以下命令會在 Vault 中新增一個名為 kes-server 的新角色

   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 伺服器私密金鑰和憑證

   以下命令會為 IP 127.0.0.1 和 DNS 名稱 localhost (作為 SAN) 產生新的 TLS 私密金鑰 server.key 和自我簽署的 X.509 憑證 server.cert。如果您想要使用另一個 IP 或 DNS 名稱 (例如 10.1.2.3 或 https://kes.example.net) 來參照您的 KES 伺服器，請相應調整 --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 不是 機密，可以公開分享。它稍後會在 KES 組態檔中用作管理員身分或指派給政策。

   API 金鑰 本身是機密，不應分享。您可以隨時重新計算 API 金鑰的身分。

3. 設定 KES 伺服器

   建立 KES 伺服器組態檔：config.yml。

   請確保 policy 區段中的身分符合 client.crt 身分。新增先前取得的 approle role_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 可以使用 mlock syscall 來防止 OS 將記憶體中的資料寫入磁碟 (交換)。這可以防止洩漏敏感資料。

   使用以下命令允許 KES 使用 mlock syscall 而無需以 root 權限執行

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

   容器

   以下指示使用 Podman 來管理容器。您也可以使用 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. 設定 KES_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 伺服器需要 KES 才能啟用伺服器端資料加密。

請參閱 KES for MinIO 指示指南，以取得使用您的新 KES 伺服器與 MinIO 伺服器所需的其他步驟。

以下章節說明金鑰加密服務 (KES) 組態設定，以使用 Hashicorp Vault 金鑰儲存區作為根 KMS，以儲存外部金鑰，例如用於 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 租戶可以由 N 個副本組成。可以有 M 個 KES 租戶連接到同一個 Vault 伺服器/叢集。

這表示 N × M 個 KES 伺服器實例可以連接到單個 Vault。

在這些配置中，每個 KES 租戶在 K/V 密鑰引擎上都有一個單獨的前綴。對於每個 KES 租戶，必須有對應的 Vault 政策。

• 對於 K/V v1

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

• 對於 K/V v2

  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 租戶可以由 N 個副本組成。可以有 M 個 KES 租戶連接到同一個 Vault 伺服器/叢集。

這表示 N × M 個 KES 伺服器實例可以連接到單個 Vault。

因此，每個 KES 租戶在 K/V 密鑰引擎上都有一個單獨的前綴。對於每個 KES 租戶，都必須有對應的 Vault 政策。

• 對於 K/V v1

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

• 對於 K/V v2

  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 的 Transit 功能提供了一種加密和解密儲存在 Vault 中的金鑰的方法。這提供了一個額外的加密層，在特定情況下可能會很有用。

啟用後，Hashicorp 會在 Vault 中儲存一個金鑰，以加密或解密儲存在 Vault 中的其他金鑰。然後，KES 使用 Vault 管理的金鑰來儲存或從 Vault 檢索金鑰。

要設定 Transit，請將以下區段新增至 KES 設定 YAML 的 keystore.vault 區段

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.

• 伺服器 API 文件
• Go SDK 文件