MySQL :: MySQL 8.4 參考手冊 :: 8.4.4.8 使用 HashiCorp Vault 金鑰環外掛程式

版本 8.4

9.0
8.0

8.0 日文

MySQL 8.4 參考手冊 / ... / 使用 HashiCorp Vault 金鑰環外掛程式

8.4.4.8 使用 HashiCorp Vault 金鑰環外掛程式

注意

keyring_hashicorp 外掛程式是包含在 MySQL 企業版中的擴充功能，這是一個商業產品。若要深入瞭解商業產品，請參閱 https://mysql.dev.org.tw/products/。

keyring_hashicorp 金鑰環外掛程式會與 HashiCorp Vault 通訊以進行後端儲存。此外掛程式支援 HashiCorp Vault AppRole 驗證。金鑰資訊不會永久儲存在 MySQL 伺服器本機儲存中。（選擇性的記憶體中金鑰快取可以用作中間儲存。）隨機金鑰產生會在 MySQL 伺服器端執行，而金鑰隨後會儲存到 Hashicorp Vault。

keyring_hashicorp 外掛程式支援構成標準 MySQL 金鑰環服務介面的函式。這些函式執行的金鑰環作業可以在兩個層級存取

SQL 介面：在 SQL 陳述式中，呼叫第 8.4.4.12 節，「通用金鑰環金鑰管理函式」中描述的函式。
C 介面：在 C 語言程式碼中，呼叫第 7.6.9.2 節，「金鑰環服務」中描述的金鑰環服務函式。

範例（使用 SQL 介面）

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

如需有關 keyring_hashicorp 允許的金鑰值特性的資訊，請參閱第 8.4.4.10 節，「支援的金鑰環金鑰類型和長度」。

若要安裝 keyring_hashicorp，請使用第 8.4.4.3 節，「金鑰環外掛程式安裝」中找到的一般指示，以及此處找到的 keyring_hashicorp 專用設定資訊。外掛程式專用設定包括準備連線到 HashiCorp Vault 所需的憑證和金鑰檔案，以及設定 HashiCorp Vault 本身。以下章節提供必要的指示。

憑證和金鑰準備

keyring_hashicorp 外掛程式需要與 HashiCorp Vault 伺服器的安全連線，並採用 HTTPS 通訊協定。典型的設定包括一組憑證和金鑰檔案

company.crt：屬於組織的自訂 CA 憑證。此檔案由 HashiCorp Vault 伺服器和 keyring_hashicorp 外掛程式使用。
vault.key：HashiCorp Vault 伺服器執行個體的私密金鑰。此檔案由 HashiCorp Vault 伺服器使用。
vault.crt：HashiCorp Vault 伺服器執行個體的憑證。此檔案必須由組織 CA 憑證簽署。

以下指示說明如何使用 OpenSSL 建立憑證和金鑰檔案。（如果您已經有這些檔案，請繼續前往 HashiCorp Vault 設定。）如顯示的指示適用於 Linux 平台，並且可能需要針對其他平台進行調整。

重要

這些指示產生的憑證是自我簽署的，安全性可能不高。在您取得使用這些檔案的經驗之後，請考慮從已註冊的憑證授權單位取得憑證/金鑰材料。

準備公司和 HashiCorp Vault 伺服器金鑰。
使用下列命令來產生金鑰檔案
```
openssl genrsa -aes256 -out company.key 4096
openssl genrsa -aes256 -out vault.key 2048
```
這些指令會產生包含公司私鑰 (company.key) 和 Vault 伺服器私鑰 (vault.key) 的檔案。這些金鑰分別是隨機產生的 4,096 位元和 2,048 位元 RSA 金鑰。
每個指令都會提示輸入密碼。為了測試目的，密碼並非必要。若要停用密碼，請省略 -aes256 引數。
金鑰檔案包含敏感資訊，應儲存在安全的位置。密碼（也是敏感資訊）稍後會用到，因此請寫下來並儲存在安全的位置。
(選用) 若要檢查金鑰檔案內容和有效性，請使用以下指令
```
openssl rsa -in company.key -check
openssl rsa -in vault.key -check
```
建立公司 CA 憑證。
使用以下指令來建立一個名為 company.crt 的公司 CA 憑證檔案，該檔案有效期為 365 天（請在一行輸入此指令）
```
openssl req -x509 -new -nodes -key company.key
  -sha256 -days 365 -out company.crt
```
如果您在金鑰產生期間使用 -aes256 引數來執行金鑰加密，系統會在建立 CA 憑證期間提示您輸入公司金鑰密碼。系統也會提示您輸入關於憑證持有者（也就是您或您的公司）的資訊，如下所示
```
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:
```
請使用適當的值回答提示。
建立憑證簽署請求。
若要建立 HashiCorp Vault 伺服器憑證，必須為新建立的伺服器金鑰準備憑證簽署請求 (CSR)。建立一個名為 request.conf 的組態檔，其中包含以下幾行。如果 HashiCorp Vault 伺服器不在本機主機上執行，請替換適當的 CN 和 IP 值，並進行任何其他必要的變更。
```
[req]
distinguished_name = vault
x509_entensions = v3_req
prompt = no

[vault]
C = US
ST = CA
L = RWC
O = Company
CN = 127.0.0.1

[v3_req]
subjectAltName = @alternatives
authorityKeyIdentifier = keyid,issuer
basicConstraints = CA:TRUE

[alternatives]
IP = 127.0.0.1
```
使用此指令來建立簽署請求
```
openssl req -new -key vault.key -config request.conf -out request.csr
```
輸出檔案 (request.csr) 是一個中間檔案，作為建立伺服器憑證的輸入。
建立 HashiCorp Vault 伺服器憑證。
使用公司憑證 (company.crt) 簽署 HashiCorp Vault 伺服器金鑰 (vault.key) 和 CSR (request.csr) 中的組合資訊，以建立 HashiCorp Vault 伺服器憑證 (vault.crt)。請使用以下指令來執行此操作（請在一行輸入此指令）
```
openssl x509 -req -in request.csr
  -CA company.crt -CAkey company.key -CAcreateserial
  -out vault.crt -days 365 -sha256
```
若要讓 vault.crt 伺服器憑證有用，請將 company.crt 公司憑證的內容附加到其中。這是必要步驟，以便公司憑證與伺服器憑證一同在請求中傳遞。
```
cat company.crt >> vault.crt
```
如果您顯示 vault.crt 檔案的內容，它應該看起來像這樣
```
-----BEGIN CERTIFICATE-----
... content of HashiCorp Vault server certificate ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... content of company certificate ...
-----END CERTIFICATE-----
```

HashiCorp Vault 設定

以下說明描述如何建立 HashiCorp Vault 設定，以方便測試 keyring_hashicorp 外掛程式。

重要

測試設定與生產設定類似，但 HashiCorp Vault 的生產使用需要額外的安全性考量，例如使用非自我簽署憑證，以及將公司憑證儲存在系統信任儲存區中。您必須實施任何額外的安全步驟，以滿足您的作業需求。

這些說明假設您可以使用在憑證和金鑰準備中建立的憑證和金鑰檔案。如果您沒有這些檔案，請參閱該章節。

擷取 HashiCorp Vault 二進位檔。
從 https://www.vaultproject.io/downloads.html 下載適用於您平台的 HashiCorp Vault 二進位檔。
解壓縮封存的內容，以產生可執行 vault 指令，該指令用於執行 HashiCorp Vault 作業。如有必要，請將安裝該指令的目錄新增至系統路徑。
(選用) HashiCorp Vault 支援自動完成選項，讓使用起來更輕鬆。如需詳細資訊，請參閱 https://learn.hashicorp.com/vault/getting-started/install#command-completion。

建立 HashiCorp Vault 伺服器組態檔。

準備一個名為 config.hcl 的組態檔，其中包含以下內容。對於 tls_cert_file、tls_key_file 和 path 值，請替換適用於您系統的路徑名稱。

listener "tcp" {
  address="127.0.0.1:8200"
  tls_cert_file="/home/username/certificates/vault.crt"
  tls_key_file="/home/username/certificates/vault.key"
}

storage "file" {
  path = "/home/username/vaultstorage/storage"
}

ui = true

啟動 HashiCorp Vault 伺服器。
若要啟動 Vault 伺服器，請使用以下指令，其中 -config 選項指定剛建立的組態檔的路徑
```
vault server -config=config.hcl
```
在此步驟中，系統可能會提示您輸入儲存在 vault.key 檔案中的 Vault 伺服器私鑰密碼。
伺服器應該會啟動，並在主控台上顯示一些資訊（IP、連接埠等）。
為了讓您可以輸入剩餘的指令，請將 vault server 指令放入背景或開啟另一個終端機，然後再繼續。
初始化 HashiCorp Vault 伺服器。

注意

此步驟中描述的作業僅在第一次啟動 Vault 時才需要，目的是取得解除密封金鑰和根權杖。後續 Vault 執行個體重新啟動僅需要使用解除密封金鑰來解除密封。

發出以下指令（假設使用 Bourne shell 語法）
```
export VAULT_SKIP_VERIFY=1
vault operator init -n 1 -t 1
```
第一個指令讓 vault 指令暫時忽略尚未將公司憑證新增至系統信任儲存區的事實。它可以補償我們自我簽署的 CA 未新增至該儲存區的事實。（對於生產用途，應該新增此類憑證。）
第二個指令建立一個解除密封金鑰，要求必須存在一個解除密封金鑰才能解除密封。（對於生產用途，一個執行個體會有多個解除密封金鑰，最多需要輸入那麼多金鑰才能解除密封。解除密封金鑰應傳遞給公司內部的金鑰保管人。使用單一金鑰可能被視為安全問題，因為這允許單一金鑰保管人解除密封 vault。）
Vault 應回覆關於解除密封金鑰和根權杖的資訊，以及一些其他文字（實際的解除密封金鑰和根權杖值與此處顯示的不同）
```
...
Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS+JybL39BjcOE=
Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
...
```
將解除密封金鑰和根權杖儲存在安全的位置。
解除密封 HashiCorp Vault 伺服器。
使用此指令來解除密封 Vault 伺服器
```
vault operator unseal
```
當系統提示您輸入解除密封金鑰時，請使用先前在 Vault 初始化期間取得的金鑰。
Vault 應產生輸出，指示設定已完成且 vault 已解除密封。
登入 HashiCorp Vault 伺服器並驗證其狀態。
準備以根使用者身分登入所需的環境變數
```
vault login s.vTvXeo3tPEYehfcd9WH7oUKz
```
對於該指令中的權杖值，請替換先前在 Vault 初始化期間取得的根權杖內容。
驗證 Vault 伺服器狀態
```
vault status
```
輸出應包含以下幾行（以及其他內容）
```
...
Initialized     true
Sealed          false
...
```
設定 HashiCorp Vault 驗證和儲存。

注意

此步驟中描述的作業僅在第一次執行 Vault 執行個體時才需要。之後無需重複。

啟用 AppRole 驗證方法，並驗證它是否在驗證方法清單中
```
vault auth enable approle
vault auth list
```
啟用 Vault KeyValue 儲存引擎
```
vault secrets enable -version=1 kv
```
建立並設定一個供 keyring_hashicorp 外掛程式使用的角色（請在一行輸入此指令）
```
vault write auth/approle/role/mysql token_num_uses=0
  token_ttl=20m token_max_ttl=30m secret_id_num_uses=0
```
新增 AppRole 安全性原則。

注意

此步驟中描述的作業僅在第一次執行 Vault 執行個體時才需要。之後無需重複。

準備一個原則，允許先前建立的角色存取適當的機密。建立一個名為 mysql.hcl 的新檔案，其中包含以下內容
```
path "kv/mysql/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
```
注意

此範例中的 kv/mysql/ 可能需要根據您的本機安裝原則和安全性需求進行調整。如果需要，請在這些說明中其他出現 kv/mysql/ 的地方進行相同的調整。

將原則檔案匯入 Vault 伺服器以建立一個名為 mysql-policy 的原則，然後將該原則指派給新角色
```
vault policy write mysql-policy mysql.hcl
vault write auth/approle/role/mysql policies=mysql-policy
```
取得新建立的角色 ID，並將其儲存在安全的位置
```
vault read auth/approle/role/mysql/role-id
```
為該角色產生一個機密 ID，並將其儲存在安全的位置
```
vault write -f auth/approle/role/mysql/secret-id
```
在產生這些 AppRole 角色 ID 和機密 ID 憑證後，它們應保持有效，直到無限期。它們不需要再次產生，而且可以使用它們來配置 keyring_hashicorp 外掛程式，以便持續使用。如需有關 AuthRole 驗證的詳細資訊，請造訪 https://www.vaultproject.io/docs/auth/approle.html。

keyring_hashicorp 組態

外掛程式程式庫檔案包含 keyring_hashicorp 外掛程式和可載入的函式 keyring_hashicorp_update_config()。當外掛程式初始化和終止時，它會自動載入和卸載該函式。無需手動載入和卸載該函式。

keyring_hashicorp 外掛程式支援下表所示的組態參數。若要指定這些參數，請將值指派給對應的系統變數。

組態參數	系統變數	必要
HashiCorp 伺服器 URL	`keyring_hashicorp_server_url`	否
AppRole 角色 ID	`keyring_hashicorp_role_id`	是
AppRole 機密 ID	`keyring_hashicorp_secret_id`	是
是	`儲存路徑`	是
授權路徑	`keyring_hashicorp_auth_path`	否
CA 憑證檔案路徑	`keyring_hashicorp_ca_path`	否
快取控制	`keyring_hashicorp_caching`	否

為了在伺服器啟動過程中可以使用，必須使用 --early-plugin-load 選項來載入 keyring_hashicorp。如上表所示，有幾個與外掛程式相關的系統變數是必要的，也必須設定。例如，在伺服器 my.cnf 檔案中使用以下幾行，並根據您的平台調整 .so 後綴和檔案位置

[mysqld]
early-plugin-load=keyring_hashicorp.so
keyring_hashicorp_role_id='ee3b495c-d0c9-11e9-8881-8444c71c32aa'
keyring_hashicorp_secret_id='0512af29-d0ca-11e9-95ee-0010e00dd718'
keyring_hashicorp_store_path='/v1/kv/mysql'
keyring_hashicorp_auth_path='/v1/auth/approle/login'

注意

根據 HashiCorp 文件，所有 API 路由都以通訊協定版本為首碼（您可以在先前的範例中看到 /v1/ 作為 keyring_hashicorp_store_path 和 keyring_hashicorp_auth_path 值）。如果 HashiCorp 開發了新的通訊協定版本，可能需要在組態中將 /v1/ 變更為其他內容。

MySQL 伺服器使用 AppRole 驗證機制向 HashiCorp Vault 進行驗證。成功驗證需要向 Vault 提供兩個機密，即 role ID 和 secret ID，它們的概念類似於使用者名稱和密碼。要使用的 role ID 和 secret ID 值是在先前執行的 HashiCorp Vault 設定程序中取得的。若要指定這兩個 ID，請將它們各自的值指派給 keyring_hashicorp_role_id 和 keyring_hashicorp_secret_id 系統變數。設定程序也會產生一個儲存路徑 /v1/kv/mysql，此為要指派給 keyring_hashicorp_commit_store_path 的值。

在外掛程式初始化時，keyring_hashicorp 會嘗試使用組態值連線至 HashiCorp Vault 伺服器。如果連線成功，外掛程式會將這些值儲存在名稱中包含 _commit_ 的對應系統變數中。例如，連線成功後，外掛程式會將 keyring_hashicorp_role_id 和 keyring_hashicorp_store_path 的值儲存在 keyring_hashicorp_commit_role_id 和 keyring_hashicorp_commit_store_path 中。

可以使用 keyring_hashicorp_update_config() 函數來執行執行階段的重新組態。

使用 SET 陳述式將所需的新值指派給上表中顯示的組態系統變數。這些指派本身對正在進行的外掛程式操作沒有影響。
呼叫 keyring_hashicorp_update_config()，使外掛程式重新組態並使用新的變數值重新連線至 HashiCorp Vault 伺服器。
如果連線成功，外掛程式會將更新的組態值儲存在名稱中包含 _commit_ 的對應系統變數中。

例如，如果您已重新組態 HashiCorp Vault 以監聽連接埠 8201，而非預設的 8200，請像這樣重新組態 keyring_hashicorp。

mysql> SET GLOBAL keyring_hashicorp_server_url = 'https://127.0.0.1:8201';
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT keyring_hashicorp_update_config();
+--------------------------------------+
| keyring_hashicorp_update_config()    |
+--------------------------------------+
| Configuration update was successful. |
+--------------------------------------+
1 row in set (0.03 sec)

如果外掛程式在初始化或重新組態期間無法連線至 HashiCorp Vault，且沒有現有的連線，則字串值變數的 _commit_ 系統變數會設定為 'Not committed'，布林值變數則會設定為 OFF。如果外掛程式無法連線，但有現有的連線，則該連線會保持作用中，且 _commit_ 變數會反映用於該連線的值。

注意

如果您在伺服器啟動時未設定強制系統變數，或發生其他外掛程式初始化錯誤，則初始化會失敗。在此情況下，您可以使用執行階段重新組態程序來初始化外掛程式，而無需重新啟動伺服器。

如需有關 keyring_hashicorp 外掛程式特定系統變數和函數的詳細資訊，請參閱第 8.4.4.16 節「金鑰環系統變數」，以及第 8.4.4.13 節「外掛程式特定的金鑰環金鑰管理函數」。