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

版本 9.0

8.4 目前
8.0

8.0 日文

MySQL 9.0 參考手冊 / ... / 使用 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 外掛程式需要透過 HTTPS 通訊協定與 HashiCorp Vault 伺服器建立安全連線。典型的設定包括一組憑證和金鑰檔案。

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_store_path`	是
授權路徑	`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 路由都以協定版本作為前綴（您可以在前面的範例中看到 keyring_hashicorp_store_path 和 keyring_hashicorp_auth_path 值中的 /v1/）。如果 HashiCorp 開發新的協定版本，則可能需要在您的組態中將 /v1/ 更改為其他值。

MySQL 伺服器使用 AppRole 驗證對 HashiCorp Vault 進行驗證。成功的驗證需要向 Vault 提供兩個秘密，一個角色 ID 和一個秘密 ID，它們在概念上類似於使用者名稱和密碼。要使用的角色 ID 和秘密 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 節「外掛程式特定的金鑰環金鑰管理函式」。