使用 Cloud HSM 金鑰提供 Apache 流量

本指南提供設定 Apache 伺服器的操作說明，讓伺服器可在 Debian 11 (Bullseye) 上使用 Cloud HSM 金鑰進行 TLS 簽署。您可能需要修改這些指令，才能與 OS 或 Linux 發行版本搭配使用。

您可以在 kms-solutions GitHub 存放區中，找到以 Terraform 為基礎的藍圖版本教學課程。

事前準備

請先完成 OpenSSL 設定一文中說明的設定。

完成 OpenSSL 設定後，請確認已安裝最新版本的 Apache：

sudo apt-get update
sudo apt-get install apache2

設定

建立由 Cloud KMS 代管的簽署金鑰

在Google Cloud 專案中，使用先前為 OpenSSL 設定的金鑰環，建立 Cloud KMS EC-P256-SHA256 簽署金鑰：

gcloud kms keys create "KEY_NAME" --keyring "KEY_RING" \
  --project "PROJECT_ID" --location "LOCATION" \
  --purpose "asymmetric-signing" --default-algorithm "ec-sign-p256-sha256" \
  --protection-level "hsm"

使用 OpenSSL 建立自行簽署的憑證

使用 Cloud KMS 代管的簽署金鑰產生自行簽署的憑證。您可以使用 OpenSSL 使用 PKCS #11 URI 而非檔案路徑，並透過標籤識別金鑰。在 Cloud KMS PKCS #11 程式庫中，金鑰標籤就是加密編譯金鑰名稱。

openssl req -new -x509 -days 3650 -subj '/CN=CERTIFICATE_NAME/' \
  DIGEST_FLAG -engine pkcs11 -keyform engine \
  -key PKCS_KEY_TYPE=KEY_IDENTIFIER > PATH_TO_CERTIFICATE

更改下列內容：

  • CERTIFICATE_NAME：憑證的名稱。
  • DIGEST_FLAG：非對稱式簽署金鑰使用的摘要演算法。視鍵而定，使用 -sha256、-sha384 或 -sha512。
  • PKCS_KEY_TYPE：用於識別金鑰的 ID 類型。如要使用最新的金鑰版本，請使用 pkcs11:object 搭配金鑰名稱。如要使用特定金鑰版本，請使用 pkcs11:id 搭配金鑰版本的完整資源 ID。
  • KEY_IDENTIFIER：鍵的 ID。如果您使用 pkcs11:object，請使用金鑰名稱，例如 KEY_NAME。如果您使用 pkcs11:id，請使用金鑰或金鑰版本的完整資源 ID，例如 projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION。
  • PATH_TO_CERTIFICATE：要儲存憑證檔案的路徑。

如果這項指令失敗，表示 PKCS11_MODULE_PATH 可能設定不正確，或是您可能沒有使用 Cloud KMS 簽署金鑰的權限。

您現在應該會看到類似下方的證書：

-----BEGIN CERTIFICATE-----
...
...
...
-----END CERTIFICATE-----

設定 Apache 伺服器

  1. 在 /etc/apache2 中建立目錄，用於儲存自行簽署的憑證：

    sudo mkdir /etc/apache2/ssl
sudo mv ca.cert /etc/apache2/ssl

  2. 編輯位於 /etc/apache2/sites-available 中的 000-default.conf 虛擬主機設定檔，提供憑證檔案路徑，並確認 SSLEngine 已開啟。

    以下是監聽通訊埠 443 的設定範例：

      <VirtualHost *:443>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/ca.cert
        SSLCertificateKeyFile "PKCS_KEY_TYPE=KEY_IDENTIFIER"
  </VirtualHost>

  3. 請使用所選文字編輯器，將環境變數新增至 /etc/apache2/envvars 檔案，確保 Apache 能正確匯出環境變數。您可能需要使用 sudo 以 root 權限編輯檔案。在檔案末端加入下列幾行：

    export PKCS11_MODULE_PATH="<var>PATH_TO_LIBKMSP11</var>"
export KMS_PKCS11_CONFIG="<var>PATH_TO_PKCS11_CONFIG</var>"
export GRPC_ENABLE_FORK_SUPPORT=1

    更改下列內容：

    • PATH_TO_LIBKMSP11：libkmsp11.so 的路徑。
    • PATH_TO_PKCS11_CONFIG：pkcs11-config.yaml 的路徑。

    GRPC_ENABLE_FORK_SUPPORT 是 gRPC 納入分支支援所需的項目，可確實在 Apache 伺服器中執行 Cloud KMS PKCS #11 程式庫。

    如果您想使用服務帳戶金鑰進行驗證，還必須為 GOOGLE_APPLICATION_CREDENTIALS 環境變數匯出值。

執行伺服器

啟用 Apache SSL 模組、啟用虛擬主機設定，並在 DocumentRoot 資料夾中新增測試網頁：

sudo a2enmod ssl
sudo a2ensite 000-default.conf
echo '<!doctype html><html><body><h1>Hello World!</h1></body></html>' | \
  sudo tee /var/www/html/index.html

重新啟動 Apache 伺服器，並使用 curl 測試設定是否正常運作。如要忽略自行簽署的憑證檢查，就必須使用 --insecure 旗標。

sudo systemctl restart apache2
curl -v --insecure https://127.0.0.1

如果遇到任何錯誤，Apache 錯誤記錄是查看錯誤所在的好地方。驗證問題是錯誤的常見原因。如果您看到 PERMISSION_DENIED 錯誤，請確認您已完成驗證，且憑證檔案具備適當權限。為確保您已完成驗證，請執行下列指令：

gcloud auth application-default login

如要確認驗證是否成功，輸出內容應包含 Credentials saved to file: [/path/to/credentials.json] 行。