啟用密鑰加密

本文件說明如何加密儲存在 Cassandra 資料庫中的開發人員應用程式消費者密鑰 (用戶端憑證)。

總覽

傳統上，Apigee Edge for Private Cloud 可以為金鑰值對應 (KVM) 資料和 OAuth 存取權杖提供選用的加密功能。

下表說明適用於私有雲的 Apigee 中靜態資料加密選項：

實體 預設啟用加密功能 可視需要加密 相關說明文件
KVM 否 是 請參閱「關於已加密的 KVM」。
OAuth 存取權杖 否 是 請參閱「加強安全性的雜湊權杖」一文。
開發人員應用程式消費者密鑰 否 是 如要啟用，請執行本文件中的設定步驟。

如要啟用用戶端憑證加密功能，您必須對所有訊息處理工具和管理伺服器節點執行下列工作：

  • 建立 KeyStore 以儲存金鑰加密金鑰 (KEK)。Apigee 會使用這個加密金鑰來加密加密資料所需的密鑰。
  • 可編輯所有管理伺服器和訊息處理器節點的設定屬性。
  • 建立開發人員應用程式以觸發金鑰建立作業。
  • 重新啟動節點。

本文件說明這些工作。

金鑰加密功能須知

本文件中的步驟說明如何啟用 KEK 功能，讓 Apigee 加密用於加密開發人員應用程式用戶端密鑰 (靜態儲存於 Cassandra 資料庫中) 的密鑰。

根據預設，資料庫中的任何現有值都將維持不變 (純文字值)，並會繼續照常運作。

對未加密的實體執行任何寫入作業時，系統會在儲存作業時進行加密。舉例來說，如果您在撤銷未加密的權杖，稍後又核准該權杖，系統就會加密新核准的權杖。

保護金鑰

請務必將金鑰庫副本儲存在安全的位置。建議您利用自己的安全機制儲存 KeyStore 副本。如同本文件中的操作說明，您必須將 KeyStore 放置在每個訊息處理器和管理伺服器節點中，本機設定檔才能參照該節點。另外，請務必將 KeyStore 副本儲存在其他位置，以便妥善保存，並當做備份。

啟用金鑰加密功能

請按照下列步驟用戶端密鑰加密：

必要條件

您必須符合以下要求，才能執行本文件的步驟：

  • 您必須安裝或升級至適用於私有 Cloud 4.50.00.10 以上版本的 Apigee Edge。
  • 您必須是 Private Cloud 適用的 Apigee Edge 管理員。

步驟 1：產生 KeyStore

請按照下列步驟建立 KeyStore 以存放金鑰加密金鑰 (KEK)：

  1. 執行以下指令，產生 KeyStore，以儲存將用於加密 KEK 的金鑰。完整輸入指令，如下所示。(您可以視需要提供任何 KeyStore 名稱)：
    keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
-keystore kekstore.p12 -storetype PKCS12

    系統出現提示時，請輸入密碼。您在設定管理伺服器和訊息處理器時會使用這組密碼。

    這個指令會產生 kekstore.p12 KeyStore 檔案，當中包含名為 KEYSTORE_NAME 的金鑰。

  2. (選用) 確認已使用下列指令產生檔案。如果檔案正確無誤，指令會傳回具有 KEYSTORE_NAME 別名的金鑰： 
    keytool -list -keystore kekstore.p12

步驟 2：設定管理伺服器

接下來，請設定管理伺服器。如果您在多個節點上安裝管理伺服器，就必須在每個節點上重複執行這些步驟。

  1. 您在步驟 1 產生的 KeyStore 檔案，複製到管理伺服器節點的目錄，例如 /opt/apigee/customer/application。例如： 
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. 確保 apigee 使用者可以讀取檔案： 
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
    chmod 400 /opt/apigee/customer/application/kekstore.p12
  3. 在 /opt/apigee/customer/application/management-server.properties 中新增下列屬性。如果檔案不存在，請建立一個。另請參閱屬性檔案參考資料。
    conf_keymanagement_kmscred.encryption.enabled=true

# Fallback is true to ensure your existing plaintext credentials continue to work
conf_keymanagement_kmscred.encryption.allowFallback=true

conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME

# These could alternately be set as environment variables. These variables should be
# accessible to Apigee user during bootup of the Java process. If environment
# variables are specified, you can skip the password configs below.
# KMSCRED_ENCRYPTION_KEYSTORE_PASS=
# KMSCRED_ENCRYPTION_KEK_PASS=
See also Using environment variables for configuration properties.

conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    請注意，視用來產生 KeyStore 的工具而定，KEK_PASSWORD 可能與 KEYSTORE_PASSWORD 相同。

  4. 使用下列指令重新啟動管理伺服器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server wait_for_ready

    wait_for_ready 指令會在管理伺服器準備就緒時傳回下列訊息：

    Checking if management-server is up: management-server is up.
  5. 如果您已將管理伺服器安裝在多個節點上，請在每個管理伺服器節點上重複執行上述步驟 1 到 4。

步驟 3：建立開發人員應用程式

管理伺服器現已更新完畢，您必須建立開發人員應用程式，以便觸發系統產生用於加密用戶端憑證資料金鑰的金鑰：

  1. 建立開發人員應用程式，以便觸發資料加密金鑰 (KEK) 的建立作業。如需相關步驟，請參閱「註冊應用程式」一文。
  2. 如有需要，請刪除開發人員應用程式。您不需要在產生加密金鑰後加以保存。

步驟 4：設定訊息處理器

如未在訊息處理器中啟用加密功能，執行階段要求就無法處理任何已加密的憑證。

  1. 將步驟 1 產生的 KeyStore 檔案複製到訊息處理工具節點上的目錄，例如 /opt/apigee/customer/application。例如： 
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. 確保 apigee 使用者可以讀取檔案： 
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
  3. 在 /opt/apigee/customer/application/message-processor.properties 中新增下列屬性。如果檔案不存在，請建立一個。另請參閱屬性檔案參考資料。
    conf_keymanagement_kmscred.encryption.enabled=true

# Fallback is true to ensure your existing plaintext credentials continue to work
conf_keymanagement_kmscred.encryption.allowFallback=true

conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME

# These could alternately be set as environment variables. These variables should be
# accessible to Apigee user during bootup of the Java process. If environment
# variables are specified, you can skip the password configs below.
# KMSCRED_ENCRYPTION_KEYSTORE_PASS=
# KMSCRED_ENCRYPTION_KEK_PASS=
See also Using environment variables for configuration properties.


conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    請注意，視用來產生 KeyStore 的工具而定，KEK_PASSWORD 可能與 KEYSTORE_PASSWORD 相同。

  4. 使用下列指令重新啟動訊息處理器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor wait_for_ready

    當訊息處理工具準備好處理訊息時，wait_for_ready 指令會傳回下列訊息：

    Checking if message-processor is up: message-processor is up.
  5. 如果您在多個節點上安裝訊息處理器，請在每個訊息處理器節點上重複執行步驟 1 至 4。

摘要

從現在起，如果您建立的所有開發人員應用程式，憑證密鑰在 Cassandra 資料庫中進行靜態加密。

針對設定屬性使用環境變數

您也可以使用環境變數，設定下列訊息處理工具和管理伺服器設定屬性。設定之後，環境變數會覆寫訊息處理工具或管理伺服器設定檔中設定的屬性。

conf_keymanagement_kmscred.encryption.keystore.pass=
conf_keymanagement_kmscred.encryption.kek.pass=

對應的環境變數如下： 

export KMSCRED_ENCRYPTION_KEYSTORE_PASS=KEYSTORE_PASSWORD
export KMSCRED_ENCRYPTION_KEK_PASS=KEK_PASSWORD

如果您設定了這些環境變數，可以在訊息處理工具和管理伺服器節點的設定檔中省略這些設定屬性，因為系統會忽略這些設定：

conf_keymanagement_kmscred.encryption.keystore.pass
conf_keymanagement_kmscred.encryption.kek.pass

屬性檔案參考資料

本節將說明，所有訊息處理器和管理伺服器節點必須設定的屬性，詳情請參閱本文先前提供的說明。

資源 預設 說明
conf_keymanagement_kmscred.encryption.enabled false 必須設為 true 才能啟用金鑰加密。
conf_keymanagement_kmscred.encryption.allowFallback false 將 allowFallback 設為 true，即可確保現有的明文憑證能繼續運作。
conf_keymanagement_kmscred.encryption.keystore.path 無 提供訊息處理工具或管理伺服器節點中的 KEK KeyStore 路徑。請參閱「步驟 2：設定管理伺服器」和「步驟 3：設定訊息處理器」。
conf_keymanagement_kmscred.encryption.kek.alias 無 在 KeyStore 中儲存 KEK 的別名。
conf_keymanagement_kmscred.encryption.keystore.pass 無 如果您使用環境變數設定這些屬性，則為選用欄位。另請參閱「針對設定屬性使用環境變數」。
conf_keymanagement_kmscred.encryption.kek.pass 無 如果您使用環境變數設定這些屬性，則為選用欄位。另請參閱「針對設定屬性使用環境變數」。