啟用密鑰加密

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

總覽

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

下表說明 Apigee for Private Cloud 中靜態資料的加密選項：

實體 預設啟用加密功能 可選擇是否加密 相關說明文件
KVM 否 是 請參閱「關於加密 KVM」。
OAuth 存取權杖 否 是 請參閱「雜湊權杖以提高安全性」。
開發人員應用程式用戶端密鑰 否 是 如要啟用，請按照本文中的設定步驟操作。

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

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

本文將說明這些工作。

金鑰加密功能須知

本文說明如何啟用 KEK 功能，讓 Apigee 加密用於加密開發人員應用程式消費者密鑰的密鑰，並將其儲存在 Cassandra 資料庫中。

根據預設，資料庫中的任何現有值都會維持不變 (以純文字形式)，並繼續像以前一樣運作。

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

保護金鑰安全

請務必將儲存 KEK 的 KeyStore 副本存放在安全的位置。建議您使用自己的安全機制儲存 KeyStore 副本。如本文件中的操作說明所述，每個訊息處理器和管理伺服器節點都必須放置一個 KeyStore，以便本機設定檔參照。不過，請務必將 KeyStore 副本存放在其他位置，以便妥善保管及備份。

啟用金鑰加密

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

必要條件

執行本文件中的步驟前，請務必符合下列規定：

  • 您必須安裝或升級至 Apigee Edge for Private Cloud 4.50.00.10 以上版本。
  • 您必須是 Apigee Edge for Private Cloud 管理員。

步驟 1：產生 KeyStore

請按照下列步驟建立金鑰庫，用於保存金鑰加密金鑰 (KEK)：

  1. 執行下列指令，產生 KeyStore 來儲存用於加密 KEK 的金鑰。請輸入與畫面顯示完全一致的指令。(您可以提供任何金鑰儲存庫名稱)：
    keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
-keystore kekstore.p12 -storetype PKCS12

    系統提示時，請輸入密碼。您會在後續章節中，使用這個密碼設定管理伺服器和訊息處理器。

    這個指令會產生 kekstore.p12 鍵盤儲存庫檔案，其中包含別名為 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 N/A 提供訊息處理器或管理伺服器節點上的 KEK 鍵盤路徑。請參閱「步驟 2：設定管理伺服器」和「步驟 3：設定訊息處理器」。
conf_keymanagement_kmscred.encryption.kek.alias N/A KEK 儲存在金鑰儲存庫中的別名。
conf_keymanagement_kmscred.encryption.keystore.pass N/A 如果您使用環境變數設定這些屬性，則可選擇是否提供。另請參閱「使用環境變數設定屬性」。
conf_keymanagement_kmscred.encryption.kek.pass N/A 如果您使用環境變數設定這些屬性，則可選擇是否提供。另請參閱「使用環境變數設定屬性」。