使用 Edge UI 建立 KeyStore 和 TrustStore

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

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

關於 Edge Cloud 的 KeyStore/truststore 和虛擬主機

為 Edge Cloud 建立金鑰庫/信任庫時，您必須遵循使用虛擬主機的所有規則。以 Cloud 中的虛擬主機為例：

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

瞭解詳情：

• 關於 TLS/SSL
• 在 Edge 中使用 TLS
• 設定虛擬主機常見問題
• 虛擬主機簡介

在 Kubernetes 中實作 KeyStore 和信任儲存庫 邊緣

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

在 Edge 中，KeyStore 和 Truststore 都以 Keystore 實體表示 包含一或多個別名。也就是說，Edge 上的 KeyStore 和 TrustStore 之間沒有實作差異。

KeyStore 和 Truststore 之間的差異是根據其自身的項目種類得出 包含以及它們在 TLS 握手中的用途：

• KeyStore - 包含一或多個 Keystore 實體 aliases，其中每個別名都含有憑證/金鑰組。
• 信任儲存庫 - 包含一或多個 Keystore 實體 aliases，其中每個別名都只包含一個憑證。

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

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

在這個範例中，您可以指定虛擬主機使用的 KeyStore 名稱和別名 其 TLS 金鑰庫您可以使用參照指定 KeyStore 名稱，以便變更 KeyStore 名稱 待憑證到期時再進行說明別名包含憑證/金鑰組，用於向存取虛擬主機的 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 握手程序。

支援的憑證格式

* 我們建議盡可能使用 PEM。

將 PKCS12 KeyStore 與 Edge for Private Cloud 4.53.00 以上版本搭配使用

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

關於實作別名

在 Edge 上，Keystore 包含一或多個別名，其中每個 別名包含：

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

在 Edge 上，truststore 包含一或多個別名，其中 每個別名都包含：

• 使用 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 驗證期間，當伺服器 client_cert_1 傳送至用戶端，以用於 TLS 握手程序。

或者，您擁有第二個憑證 (client_cert_2)，透過同一個憑證簽署。 ca_cert。不過，您不會將 client_cert_2 上傳至信任存放區。信任存放區仍只包含 client_cert_1 和 ca_cert。

當伺服器在 TLS 握手程序中傳遞 client_cert_2 時，該要求 成功。這是因為 Edge 允許在 client_cert_2 啟用 TLS 驗證功能 不存在於信任儲存庫中，但是以信任儲存庫裡的憑證簽署。如果您從信任存放區中移除 CA 憑證 ca_cert，TLS 驗證就會失敗。

FIPS 考量事項

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

瀏覽傳輸層安全標準 (TLS) KeyStore 頁面

系統會顯示 TLS KeyStore 頁面：

如上圖所示，TLS KeyStore 頁面可讓您執行下列操作：

• 選取一個環境
• 建立 KeyStore 和別名
• 測試及刪除 KeyStore
• 查看和刪除別名

查看別名

如何查看別名：

1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
2. 選取環境 (通常是 prod 或 test)。
3. 按一下與要查看的別名相關聯的資料列。

   系統會顯示別名憑證和金鑰的詳細資料。
   
   您可以查看別名的所有資訊，包括到期日。

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

建立 KeyStore/TrustStore 和別名

您可以建立 KeyStore，做為傳輸層安全標準 (TLS) KeyStore 或 TLS 信任儲存庫。金鑰庫是貴機構特定環境 (例如測試或生產環境) 的專屬項目。因此，如果您想在將金鑰庫部署至正式環境前，先在測試環境中測試金鑰庫，就必須在兩個環境中建立金鑰庫。

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

如何建立 KeyStore：

1. 前往「TLS Keystores」頁面。
2. 選取環境 (通常為 prod 或 test)。
3. 按一下「+ Keystore」。
4. 指定 KeyStore 名稱。名稱只能包含英數字元。
5. 按一下「新增 Keystore」。清單中會顯示新的 KeyStore。
6. 按照下列任一程序新增別名。其他參考資訊 支援的憑證檔案格式。
   • 透過憑證建立別名 (僅限 Ruststore)。
   • 從 JAR 檔案建立別名 (僅限金鑰庫)
   • 建立別名 從憑證和金鑰 (僅限 KeyStore)
   • 透過以下管道建立別名： PKCS12/PFX 檔案 (僅限 KeyStore)
   • 建立 自行簽署憑證中的別名 (僅限 KeyStore)

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

如何使用憑證建立別名：

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

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

如何從 JAR 檔案建立別名：

1. 前往「TLS Keystores」頁面。
2. 將遊標移到 KeyStore 上，以顯示動作選單並按一下 +。
3. 指定「別名名稱」。
4. 在「Certificate details」(憑證詳細資料) 之下，於 [Type] (類型) 下拉式選單中選取 [JAR File] (JAR 檔案)。
5. 按一下「JAR File」旁邊的「選擇檔案」，前往包含憑證和金鑰的 JAR 檔案，然後按一下「開啟」。
6. 如果金鑰設有密碼，請指定「密碼」。如果鍵沒有 請將此欄位留空。
7. 根據預設，API 會檢查憑證是否已過期。視需要選取 選取 [允許過期憑證] 即可略過驗證步驟。
8. 選取「儲存」即可上傳金鑰和憑證，並建立別名。

透過憑證建立別名 key (僅限 KeyStore)

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

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

透過 PKCS12/PFX 檔案 (僅限 KeyStore)

如要從包含憑證和金鑰的 PKCS12 檔案中建立別名，請按照下列指示操作：

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

透過 自行簽署的憑證 (僅限 KeyStore)

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

如何透過自行簽署的憑證建立別名：

1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
2. 將遊標移到 KeyStore 上，以顯示動作選單並按一下 +。
3. 指定「別名名稱」。
4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「自簽憑證」。
5. 請根據下表填寫表單。
6. 選取「Save」，建立憑證和私密金鑰組，並上傳至別名。

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

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

下表說明表單欄位：

測試 KeyStore 或 TrustStore

您可以在 Edge UI 中測試 Truststore 和 KeyStore，確認已設定完成 正確做法。測試 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. 按照上方說明，將新憑證上傳至信任存放區 透過憑證建立別名 (僅限 truststore)。

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

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

刪除 KeyStore/truststore 或別名

刪除 KeyStore/truststore 或別名時請務必謹慎。刪除 KeyStore 之後 由虛擬主機、目標端點或目標伺服器使用的 Truststore 或別名 無法透過虛擬主機或目標端點/目標伺服器進行 API 呼叫。

一般而言，刪除 KeyStore/truststore 或別名的程序如下：

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 Proxy 可正常運作。
5. 刪除 KeyStore/TrustStore 或別名。

刪除 KeyStore

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

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

刪除別名

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

注意：在您轉換虛擬帳號之前，請勿刪除別名 主機和目標端點/目標伺服器，即可使用新的 KeyStore 和別名。