使用 Edge UI 建立 KeyStore 和 TrustStore

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本文說明如何為 Edge for Cloud 和 Edge for Private Cloud 版本 4.18.01 以上版本建立、修改及刪除金鑰儲存庫和信任儲存庫。

關於 Edge Cloud 的 Keystore/Truststore 和虛擬主機

為 Edge Cloud 建立金鑰庫/信任庫時，您必須遵循使用虛擬主機的所有規則。舉例來說，如果在雲端使用虛擬主機：

  • 虛擬主機必須使用 TLS。
  • 虛擬主機只能使用通訊埠 443。
  • 您必須使用已簽署的 TLS 憑證。未簽署的憑證不得用於 Cloud 中的虛擬主機。
  • TLS 憑證指定的網域名稱必須與虛擬主機的主機別名相符。

瞭解詳情：

在 Edge 中實作 KeyStore 和 TrustStore

如要設定仰賴公用金鑰基礎架構的功能 (例如 TLS)，您必須建立金鑰庫和信任庫，其中包含必要的金鑰和數位憑證。

在 Edge 中，金鑰匣和信任匣都由「金鑰匣」實體表示，其中包含一或多個「別名」。也就是說，Edge 上的 KeyStore 和 TrustStore 之間沒有實作差異。

金鑰庫和信任存放區的差異取決於它們所包含的項目類型，以及在 TLS 握手中如何使用：

  • 金鑰庫：包含一或多個金鑰庫實體的實體，每個別名都包含一組憑證/金鑰。
  • truststore：包含一或多個金鑰庫實體的別名，每個別名只包含一個憑證。

為虛擬主機或目標端點設定 TLS 時，金鑰庫和信任庫會在 TLS 握手程序中提供不同的角色。設定虛擬主機或目標端點時，請在 <SSLInfo> 標記中分別指定金鑰庫和信任庫，如下所示虛擬主機：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

在本例中，您會指定虛擬主機用於 TLS 金鑰庫的金鑰庫名稱和別名。您可以使用參照指定金鑰庫名稱，以便日後在憑證到期時變更。別名包含憑證/金鑰組，用於向存取虛擬主機的 TLS 用戶端識別虛擬主機。在本例中，您不需要信任存放區。

如果需要信任存放區 (例如雙向 TLS 設定)，請使用 <TrustStore> 標記指定信任存放區：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

在這個範例中，<TrustStore> 標記只會參照 KeyStore，不會指定特定別名。金鑰庫中的每個別名都包含一個憑證或憑證鏈結，用於 TLS 握手程序。

支援的憑證格式

格式 支援 API 和 UI 上傳 支援北向 已驗證
PEM 是 是 是
* PKCS12 是 是 是。
注意：Apigee 會在內部將
PKCS12 轉換為 PEM。
* DER 否 否 是
* PKCS7 否 否 否

* 建議您盡可能使用 PEM。

搭配使用 PKCS12 金鑰庫與 Private Cloud 適用的 Edge 4.53.00 以上版本

如果您使用的是 Edge for Private Cloud 4.53.00 以上版本，請只使用 PKCS12 金鑰庫將金鑰和相關憑證上傳至 Apigee。如需將現有金鑰和憑證轉換為 PKCS12/PFX 格式的相關說明，請參閱「將憑證轉換為支援的格式」。

關於實作別名

在 Edge 上，KeyStore 包含一或多個別名，每個別名都包含：

  • TLS 憑證為 PEM 或 PKCS12/PFX 檔案 - 由憑證授權單位 (CA) 簽署的憑證、包含憑證鏈結的檔案 (最後一個憑證由 CA 簽署)，或自行簽署的憑證。
  • 私密金鑰為 PEM 或 PKCS12/PFX 檔案。Edge 支援的金鑰大小上限為 2048 位元。通關密語為選用項目。

在 Edge 上，信任存放區包含一或多個別名，每個別名都包含以下項目：

  • TLS 憑證為 PEM 檔案 - 憑證授權單位 (CA) 簽署的憑證、憑證鏈 (最後一張憑證由 CA 簽署)，或是自行簽署的憑證。

Edge 提供 UI 和 API，可用於建立 KeyStore、建立別名、上傳憑證/金鑰組合，以及更新憑證。您用來建立信任存放區的 UI 和 API，與用來建立 KeyStore 的相同。差異在於建立信任存放區時，您會建立只包含憑證的別名。

關於憑證和金鑰檔案的格式

您可以將憑證和金鑰表示為 PEM 檔案或 PKCS12/PFX 檔案。PEM 檔案符合 X.509 格式。如果您的憑證或私密金鑰並未使用 PEM 檔案定義，您可以使用 openssl 等公用程式將其轉換為 PEM 檔案。

不過，許多 .crt 檔案和 .key 檔案都已採用 PEM 格式。如果這些檔案是文字檔案，且位於以下位置：

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

或是：

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

這樣一來，檔案就會與 PEM 格式相容，您可以在金鑰庫或信任金鑰庫中使用這些檔案，而無須將檔案轉換為 PEM 檔案。

關於憑證鏈結

如果憑證是鏈結的一部分，您可以根據憑證是在金鑰庫或信任存放區中使用，採取不同的處理方式：

  • Keystore：如果憑證是鏈結的一部分，則必須建立單一檔案，其中包含鏈結中的所有憑證。憑證必須依序排列，且最後一個憑證必須是根憑證或由根憑證簽署的中繼憑證。
  • Truststore：如果憑證是鏈結的一部分，您必須建立包含所有憑證的單一檔案，並將該檔案上傳至別名，或者為每個憑證使用不同的別名，將鏈結中的所有憑證分別上傳至 Truststore。如果您上傳單一憑證，憑證必須依序排列，且最後一個憑證必須是根憑證，或是由根憑證簽署的中繼憑證。
  • 如果您建立的單一檔案包含多個憑證，則必須在每個憑證之間插入空白行。

舉例來說，您可以將所有憑證合併成一個 PEM 檔案。憑證必須依序排列，且最後一個憑證必須是根憑證，或由根憑證簽署的中繼憑證：

-----BEGIN CERTIFICATE----- 
(Your Primary TLS certificate) 
-----END CERTIFICATE----- 

-----BEGIN CERTIFICATE----- 
(Intermediate certificate) 
-----END CERTIFICATE-----
 
-----BEGIN CERTIFICATE----- 
(Root certificate or intermediate certificate signed by a root certificate) 
-----END CERTIFICATE-----

如果憑證以 PKCS12/PFX 檔案呈現，您可以使用 openssl 指令，從憑證鏈結建立 PKCS12/PFX 檔案，如下所示：

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

使用信任存放區中的憑證鏈結時，不一定需要上傳鏈結中的所有憑證。舉例來說，您上傳用戶端憑證 client_cert_1，以及用戶端憑證核發者的憑證 ca_cert。

在雙向 TLS 驗證期間，如果伺服器在 TLS 握手程序中將 client_cert_1 傳送至用戶端，則用戶端驗證會成功。

或者，您可以使用由同一個憑證 ca_cert 簽署的第二個憑證 client_cert_2。不過，您不會將 client_cert_2 上傳至信任存放區。信任存放區仍只包含 client_cert_1 和 ca_cert。

當伺服器在 TLS 握手期間傳遞 client_cert_2 時，要求就會成功。這是因為 Edge 允許 TLS 驗證成功，即使 client_cert_2 不在信任存放區中，但已由信任存放區中的憑證簽署。如果從信任存放區移除 CA 憑證 ca_cert，TLS 驗證就會失敗。

FIPS 考量事項

如果您在支援 FIPS 的作業系統上使用 Edge for Private Cloud 4.53.00 以上版本，請僅使用 PKCS12 金鑰庫將金鑰和相關憑證上傳至 Apigee。

探索「TLS 金鑰庫」頁面

請參閱下文，瞭解如何存取 TLS 金鑰庫頁面。

Edge

如要使用 Edge UI 存取 TLS 金鑰存放區頁面，請按照下列步驟操作：

  1. 以機構組織管理員身分登入 https://apigee.com/edge。
  2. 選取您的機構。
  3. 依序選取「Admin」>「Environment」>「TLS Keystores」。

Classic Edge (Private Cloud)

如要使用 Edge 傳統版 UI 存取 TLS 金鑰存放區頁面，請按照下列步驟操作：

  1. 以機構管理員身分登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 選取您的機構。
  3. 依序選取「Admin」>「Environment Configuration」>「TLS Keystores」。

系統會顯示「TLS Keystores」頁面：

如上圖所示，您可以在 TLS 金鑰存放區頁面中執行以下操作：

查看別名

如要查看別名：

  1. 前往「TLS Keystores」頁面。
  2. 選取環境 (通常為 prod 或 test)。
  3. 按一下與要查看的別名相關聯的資料列。

    系統會顯示別名憑證和金鑰的詳細資料。

    您可以查看別名的所有資訊，包括到期日。

  4. 使用頁面頂端的按鈕管理憑證，以便執行下列操作：
    • 將憑證下載為 PEM 檔案。
    • 產生 CSR。如果您有過期憑證並想續約，可以下載憑證簽署要求 (CSR)。接著，您可以將 CSR 傳送至 CA，取得新的憑證。
    • 更新憑證。注意：如果您更新的憑證目前由虛擬主機或目標伺服器/目標端點使用，則必須聯絡 Apigee Edge 支援團隊，重新啟動路由器和訊息處理器。更新憑證的建議做法如下：
      1. 建立新的 KeyStore 或 TrustStore。
      2. 將新的憑證新增至新的 KeyStore 或 TrustStore。
      3. 將虛擬主機或目標伺服器/目標端點中的參照更新為 KeyStore 或 TrustStore。詳情請參閱「 更新 Cloud 的 TLS 憑證」。
      4. 刪除別名。注意：如果您刪除別名，而該別名目前由虛擬主機或目標端點使用，則虛擬主機或目標端點會失敗。

建立 KeyStore/TrustStore 和別名

您可以建立金鑰庫，用於做為 TLS 金鑰庫或 TLS 信任庫。金鑰庫是貴機構特定環境 (例如測試或生產環境) 的專屬項目。因此，如果您想在測試環境中測試 KeyStore，然後再部署至正式環境，就必須在兩個環境中建立 KeyStore。

如要在環境中建立 KeyStore，您只需指定 KeyStore 名稱即可。在環境中建立命名 KeyStore 後，您可以建立別名，並上傳憑證/金鑰組合 (KeyStore)，或只上傳憑證 (TrustStore) 到別名。

如要建立 KeyStore，請按照下列步驟操作：

  1. 前往「TLS Keystores」頁面。
  2. 選取環境 (通常為 prod 或 test)。
  3. 按一下「+ Keystore」。
  4. 指定 KeyStore 名稱。名稱只能包含英數字元。
  5. 按一下「新增 Keystore」。清單中會顯示新的 KeyStore。
  6. 請使用下列任一程序新增別名。另請參閱「支援的憑證檔案格式」。

從憑證建立別名 (僅限信任儲存庫)

如何使用憑證建立別名：

  1. 前往「TLS Keystores」頁面。
  2. 將滑鼠游標移至 KeyStore 上，即可顯示操作選單，然後按一下「+」。
  3. 指定「別名名稱」。
  4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「僅憑證」。
  5. 按一下「Certificate File」旁的「Choose File」，前往包含憑證的 PEM 檔案，然後按一下「Open」。
  6. 根據預設，API 會檢查憑證是否已過期。您可以選取「允許已過期憑證」來略過驗證程序。
  7. 選取「儲存」即可上傳憑證並建立別名。

從 JAR 檔案建立別名 (僅限 KeyStore)

如何從 JAR 檔案建立別名：

  1. 前往「TLS Keystores」頁面。
  2. 將滑鼠游標移至 KeyStore 上，即可顯示操作選單，然後按一下「+」。
  3. 指定「別名名稱」。
  4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「JAR 檔案」。
  5. 點選「JAR 檔案」旁的「選擇檔案」，前往包含憑證和金鑰的 JAR 檔案，然後點選「開啟」。
  6. 如果金鑰有密碼，請指定「密碼」。如果金鑰沒有密碼，請將這個欄位留空。
  7. 根據預設，API 會檢查憑證是否已過期。您可以選取「允許已過期憑證」來略過驗證程序。
  8. 選取「儲存」即可上傳金鑰和憑證，並建立別名。

使用憑證和金鑰建立別名 (僅限 KeyStore)

如何使用憑證和金鑰建立別名：

  1. 前往「TLS Keystores」頁面。
  2. 將滑鼠游標移至 KeyStore 上，即可顯示操作選單，然後按一下「+」。
  3. 指定「別名名稱」。
  4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「憑證和金鑰」。
  5. 按一下「Certificate File」旁的「Choose File」，前往包含憑證的 PEM 檔案，然後按一下「Open」。
  6. 如果金鑰有密碼，請指定「金鑰密碼」。如果金鑰沒有密碼，請將這個欄位留空。
  7. 按一下「Key File」旁的「Choose File」，前往包含金鑰的 PEM 檔案，然後點選「Open」。
  8. 根據預設，API 會檢查憑證是否已過期。您可以選取「允許已過期憑證」，略過驗證程序。
  9. 選取「儲存」即可上傳金鑰和憑證，並建立別名。

從 PKCS12/PFX 檔案建立別名 (僅限 KeyStore)

如要從內含憑證和金鑰的 PKCS12 檔案建立別名，請按照下列步驟操作：

  1. 前往「TLS Keystores」頁面。
  2. 將滑鼠游標移至 KeyStore 上，即可顯示操作選單，然後按一下「+」。
  3. 指定「別名名稱」。
  4. 在「Certificate details」(憑證詳細資料) 下方，從「Type」(類型) 下拉式選單中選取「PKCS12/PFX」。
  5. 按一下「PKCS12/PFX」旁的「選擇檔案」，前往包含金鑰和憑證的檔案，然後按一下「開啟」。
  6. 如果金鑰有密碼，請指定 PKCS12/PFX 檔案的密碼。 如果金鑰沒有密碼，請將這個欄位留空。
  7. 根據預設，API 會檢查憑證是否已過期。您可以選取「允許已過期憑證」，略過驗證程序。
  8. 選取「儲存」即可上傳檔案並建立別名。

從自行簽署的憑證建立別名 (僅限 KeyStore)

如要建立使用自行簽署憑證的別名，請填寫表單，並提供建立憑證所需的必要資訊。Edge 接著會建立憑證和私密金鑰組，並上傳至別名。

如何使用自行簽署的憑證建立別名：

  1. 前往「TLS Keystores」頁面。
  2. 將滑鼠游標移至 KeyStore 上，即可顯示操作選單，然後按一下「+」。
  3. 指定「別名名稱」。
  4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「自簽憑證」。
  5. 請根據下表填寫表單。
  6. 選取「Save」，建立憑證和私密金鑰組，並上傳至別名。

在產生的憑證中，您會看到下列額外欄位：

  • 核發者
    簽署並核發憑證的實體。對於自行簽署的憑證，這是您在建立憑證時指定的 CN。
  • Validity
    憑證有效期限以兩個日期表示：憑證有效期限開始日期和憑證有效期限結束日期。兩者皆可編碼為 UTCTime 或 GeneralizedTime 值。

下表說明表單欄位：

表單欄位 說明 預設 必填
別名名稱 別名名稱。長度上限為 128 個半形字元。 不適用 是
索引鍵大小 金鑰大小 (以位元為單位)。預設值和上限為 2048 位元。 2048 否
簽名演算法 用於產生私密金鑰的簽章演算法。有效值包括「SHA512withRSA」、「SHA384withRSA」和「SHA256withRSA」(預設值)。 SHA256withRSA 否
憑證有效期限 (以天為單位) 憑證有效期限 (以天為單位)。接受正值 (非零值)。 365 否
共用名稱 機構的一般名稱 (CN) 會標示與憑證相關聯的完整網域名稱。通常由主機和網域名稱組成。例如 api.enterprise.apigee.com、www.apigee.com 等，長度上限為 64 個字元。

視憑證類型而定，CN 可以是屬於同一個網域 (例如 example.com、www.example.com) 的一或多個主機名稱、萬用字元名稱 (例如 *.example.com) 或網域清單。請勿加入任何通訊協定 (http:// 或 https://)、通訊埠號碼或資源路徑。

只有在要求主機名稱與至少一個憑證通用名稱相符時，憑證才有效。

 不適用 是
電子郵件 電子郵件地址。長度上限為 255 個半形字元。 不適用 否
機構單位名稱 機構團隊名稱。長度上限為 64 個半形字元。 不適用 否
機構名稱 機構名稱。長度上限為 64 個半形字元。 不適用 否
縣市 城市/鄉鎮名稱。長度上限為 128 個半形字元。 不適用 否
州/省 州/省名稱。長度上限為 128 個半形字元。 不適用 否
國家/地區 國家/地區代碼 (由 2 個英文字母組成)。例如 IN 代表印度，US 代表美國。 不適用 否
其他名稱 替代主機名稱清單。允許將其他身分繫結至憑證的主體。已定義的選項包括網際網路電子郵件地址、DNS 名稱、IP 位址和統一資源識別碼 (URI)。

每個值的長度上限為 255 個半形字元。您可以使用半形逗號分隔名稱，也可以在輸入每個名稱後按下 Enter 鍵。

 不適用 否

測試 KeyStore 或 TrustStore

您可以在 Edge UI 中測試信任存放區和金鑰存放區，確認設定是否正確無誤。測試 UI 會驗證 Edge 傳送至後端服務的 TLS 要求。後端服務可設定為支援單向或雙向 TLS。

如要測試單向 TLS，請按照下列步驟操作：

  1. 前往「TLS Keystores」頁面。
  2. 選取環境 (通常為 prod 或 test)。
  3. 將滑鼠游標移至要測試的 TLS 金鑰庫，以便顯示動作選單，然後按一下「Test」。系統會顯示下列對話方塊，顯示信任存放區的名稱：
  4. 輸入後端服務的主機名稱。
  5. 輸入 TLS 通訊埠編號 (通常為 443)。
  6. 視需要指定任何通訊協定或加密法。
  7. 選取「測試」。

如要測試雙向 TLS，請按照下列步驟操作：

  1. 針對所需信任存放區，選取「Test」按鈕。
  2. 在對話方塊中，選取「SSL Test Type」的「Two Way」。 系統會顯示下列對話方塊：
  3. 指定在雙向 TLS 中使用的 KeyStore 名稱。
  4. 在包含憑證和金鑰的 KeyStore 中指定別名名稱。
  5. 輸入後端服務的主機名稱。
  6. 輸入 TLS 通訊埠編號 (通常為 443)。
  7. 視需要指定任何通訊協定或加密法。
  8. 選取「測試」。

為雙向 TLS 將憑證新增至信任存放區

當您使用雙向 TLS 進行傳入連線 (也就是向 Edge 提出 API 要求) 時，信任存放區會為每個可向 Edge 提出要求的用戶端包含憑證或 CA 鏈結。

初次設定信任存放區時，您可以為已知用戶端新增所有憑證。不過，隨著時間的推移，您可能會在新增用戶端時，將其他憑證新增至信任存放區。

如要將新的憑證新增至用於雙向 TLS 的信任存放區，請按照下列步驟操作：

  1. 請確認您使用的是虛擬主機中的信任存放區參照。
  2. 如上文「從憑證建立別名 (僅限信任存放區)」一節所述，將新的憑證上傳至信任存放區。

  3. 更新信任存放區參照，將其設為相同的值。 這項更新會導致 Edge 重新載入信任存放區和新憑證。

    詳情請參閱「修改參照」。

刪除 KeyStore/TrustStore 或別名

刪除 KeyStore/TrustStore 或別名時，請務必謹慎行事。如果您刪除虛擬主機、目標端點或目標伺服器使用的金鑰庫、信任存放區或別名，則透過虛擬主機或目標端點/目標伺服器發出的所有 API 呼叫都會失敗。

通常，刪除金鑰庫/信任庫或別名的程序如下：

  1. 如上所述，建立新的 KeyStore/TrustStore 或別名。
  2. 針對傳入連線 (也就是 Edge 中的 API 要求)，請更新虛擬主機設定，以便參照新的 KeyStore 和金鑰別名。
  3. 外連連線 (從 Apigee 連往後端伺服器)：
    1. 請為參照舊 KeyStore 和金鑰別名的所有 API 代理程式，更新 TargetEndpoint 設定，以便參照新的 KeyStore 和金鑰別名。如果 TargetEndpoint 參照 TargetServer，請更新 TargetServer 定義，以便參照新的 KeyStore 和鍵別名。
    2. 如果金鑰庫和信任庫是直接從 TargetEndpoint 定義參照，則必須重新部署 Proxy。如果 TargetEndpoint 參照 TargetServer 定義，而 TargetServer 定義參照 KeyStore 和 TrustStore，就不需要重新部署 Proxy。
  4. 確認 API 代理是否正常運作。
  5. 刪除 KeyStore/TrustStore 或別名。

刪除 KeyStore

如要刪除 KeyStore 或 TrustStore，請將游標移至清單中的 KeyStore 或 TrustStore，以便顯示動作選單，然後按一下 。如果您刪除虛擬主機或目標端點/目標伺服器使用的 KeyStore 或 TrustStore，透過虛擬主機或目標端點/目標伺服器的所有 API 呼叫都會失敗。

注意：請先將虛擬主機和目標端點/目標伺服器轉換為使用新的 KeyStore，再刪除 KeyStore。

刪除別名

如要刪除別名，請將游標移至清單中的別名，以便顯示動作選單，然後按一下 。如果您刪除虛擬主機或目標端點/目標伺服器使用的別名，透過虛擬主機或目標端點/目標伺服器的所有 API 呼叫都會失敗。

注意：請先將虛擬主機和目標端點/目標伺服器轉換為使用新的 KeyStore 和別名，再刪除別名。