啟用密鑰加密

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

總覽

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

下表說明 Apigee 專用私有雲資料的加密選項：

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

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

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

本文件會說明這些工作。

關於金鑰加密功能的相關資訊

本文的步驟說明如何啟用 KEK 功能，讓 Apigee 在將開發人員應用程式消費者密鑰儲存在 Cassandra 資料庫的靜態狀態時，加密用於加密這些密鑰的密鑰。

根據預設，資料庫中的任何現有值都不會變更 (以純文字形式)，並會繼續正常運作。

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

保護金鑰安全

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

啟用金鑰加密功能

請按照下列步驟進行消費者密鑰加密：

必要條件

您必須符合下列條件，才能執行本文件中的步驟：

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

步驟 1：產生 KeyStore

請按照下列步驟建立金鑰庫，以便儲存金鑰加密金鑰 (KEK)：

  1. 執行下列指令，產生 KeyStore，用來儲存用於加密 KEK 的金鑰。完整輸入指令，(您可以提供任何所需的 KeyStore 名稱)：
    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

針對支援 FIPS 的作業系統使用 BCFKS KeyStore

如果您在支援 FIPS 的作業系統上使用 Edge for Private Cloud，應產生 BCFKS 類型的 KeyStore。這類 KeyStore 可在非 FIPS 機器上產生，然後轉移至符合 FIPS 的機器。如要產生 KeyStore，請使用下列指令：

keytool -genseckey -alias <KEYSTORE_NAME> -keyalg AES -keysize 256 \
-storetype BCFKS -keystore keystore.bcfks \
-providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-keypass keystorepass -storepass keystorepass

您可能需要在產生此 KeyStore 的電腦上執行其他 Java 設定。您可能需要編輯機器的 Java 安全性檔案 (通常位於 /usr/lib/jvm/jre/lib/security/java.security)。在這個檔案中，請尋找並編輯下列屬性：

# Don't rely on /dev/random for generating random numbers
securerandom.source=file:/dev/urandom
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS

步驟 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

    請注意，KEK_PASSWORD 可能與 KEYSTORE_PASSWORD 相同，具體取決於用於產生 KeyStore 的工具。

  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 鍵值匣路徑。 請參閱「步驟 2：設定管理伺服器」和「步驟 3：設定訊息處理工具」。
conf_keymanagement_kmscred.encryption.kek.alias 無 在 KeyStore 中儲存 KEK 的別名。
conf_keymanagement_kmscred.encryption.keystore.pass 無 如果您使用環境變數設定這些屬性，則可省略此步驟。另請參閱「使用設定屬性的環境變數」。
conf_keymanagement_kmscred.encryption.kek.pass 無 如果您使用環境變數設定這些屬性，則可省略此步驟。另請參閱「使用設定屬性的環境變數」。