Thales CipherTrust Manager（前身為 Gemalto KeySecure）

本教學將說明如何設定 KES 伺服器，以使用 Thales CipherTrust Manager 執行個體（前身為 Gemalto KeySecure）作為持久且安全的金鑰儲存庫。

本指南假設您已執行 CipherTrust Manager 執行個體。它已在 CipherTrust Manager k170v 版本 2.0.0 和 Gemalto KeySecure k170v 版本 1.9.1 和 1.10.0 上進行測試。

CipherTrust Manager 設定

若要透過 ksctl CLI 連線到您的 CipherTrust Manager 執行個體，您需要類似以下的 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
```
為該群組建立一個新使用者

這會列印出一個 JSON 物件，其中包含後續步驟所需的 user_id。如果您已經有想要指派給 KES-Service 群組的現有使用者，請跳過此步驟並繼續進行 3。
```
ksctl users create --name <username> --pword '<password>'
```
將使用者指派給步驟 1 中建立的 KES-Service 群組
```
ksctl groups adduser --name KES-Service --userid "<user-ID>"
```
建立使用者時會印出使用者 ID。否則，請使用 ksctl users list 命令取得 ID。

使用者 ID 類似於：local|8791ce13-2766-4948-a828-71bac67131c9。

為 KES-Service 群組建立原則

建立名為 kes-policy.json 的文字檔案，該檔案授予 KES-Service 群組成員建立、讀取和刪除權限。檔案內容應類似於以下內容

{                                                                                          
  "allow": true,
  "name": "kes-policy",
  "actions":[
      "CreateKey",
      "ExportKey",
      "ReadKey",
      "DeleteKey"
  ],
  "resources": [
      "kylo:kylo:vault:secrets:*"
  ]
}

此原則允許 KES 建立、提取和刪除主金鑰。如果您想阻止 KES 執行例如刪除主金鑰的操作，請省略 DeleteKey 動作。

同樣地，您可以透過 resources 定義來限制 KES 可以存取的主金鑰。

使用以下命令，利用上面建立的檔案來建立原則。

ksctl policy create --jsonfile kes-policy.json

將原則附加至 KES-Service 群組

建立一個名為 kes-attachment.json 的檔案，其中包含原則附加規格

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

使用以下命令將 kes-policy 附加至 KES-Service 群組

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-Service 群組成員的使用者憑證。

此命令會輸出類似以下的刷新令牌
```
CEvk5cdHLG7si05LReIeDbXE3PKD082YdUFAnxX75md3jzV0BnyHyAmPPJiA0
```

KES 伺服器設定

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

您可以隨時計算 app 身分。

kes tool 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 tool 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 實例提供的 TLS 憑證既沒有通用名稱（主體）也沒有主體別名 (SAN)。此類憑證無效。請更新您的 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 tool 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>

搭配 MinIO 伺服器使用 KES

MinIO 伺服器需要 KES 來啟用伺服器端資料加密。

請參閱KES for MinIO 指導指南，以了解搭配 MinIO 伺服器使用新 KES 伺服器所需的其他步驟。

設定參考

以下章節說明金鑰加密服務 (KES) 設定，以使用 Thales CipherTrust Manager（先前稱為 Gemalto KeySecure）作為根 KMS，以儲存外部金鑰，例如在 MinIO 伺服器上用於伺服器端加密的金鑰。

MinIO 伺服器需要擴展權限

從MinIO 伺服器 RELEASE.2023-02-17T17-52-43Z 開始，MinIO 需要擴展的 KES 權限才能運作。本章節中的範例設定包含所有必要的權限。

YAML 概觀

具有 ${<STRING>} 的欄位使用與 <STRING> 值相符的環境變數。您可以使用此功能來設定憑證，而無需將其寫入設定檔。

YAML 假設 MinIO 部署存取 KES 的一組最小權限。作為替代方案，您可以省略 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:
  gemalto:
    keysecure:
      endpoint: ""   
      credentials:   
        token: ""    
        domain: ""   
        retry: 15s   
      tls:           
        ca: ""

參考

如需完整文件，請參閱設定頁面。

金鑰	描述
`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-*` 只授予使用 `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.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 憑證的路徑。