使用 Edge UI 建立 KeyStore 和 TrustStore

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

Edge Cloud 的金鑰儲存區/信任儲存區和虛擬主機簡介

為 Edge Cloud 建立金鑰儲存區/信任儲存區的程序，需要您遵守所有使用虛擬主機的規則。舉例來說，在雲端使用虛擬主機時：

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

瞭解詳情：

• 關於 TLS/SSL
• 透過 Edge 使用 TLS
• 設定虛擬主機常見問題
• 關於虛擬主機

在 Edge 中實作 KeyStore 和 TrustStore

如要設定依賴公用金鑰基礎架構的功能 (例如 TLS)，您需要建立包含必要金鑰和數位憑證的金鑰儲存區和信任儲存區。

在 Edge 中，金鑰儲存區和信任儲存區都以 keystore 實體表示，其中包含一或多個別名。也就是說，Edge 上的金鑰儲存區和信任儲存區在實作上沒有差異。

金鑰儲存區和信任儲存區的差異，在於所含的項目類型，以及在 TLS 交握程序中的使用方式：

• KeyStore：包含一或多個「別名」的「KeyStore」實體，每個別名都包含憑證/金鑰組合。
• 信任儲存庫：金鑰儲存庫實體，包含一或多個別名，每個別名只包含憑證。

為虛擬主機或目標端點設定 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> 標記只會參照金鑰儲存區，不會指定特定別名。金鑰儲存區中的每個別名都包含一個或一連串的憑證，這些憑證會用於 TLS 交握程序。

支援的憑證格式

* 建議盡可能使用 PEM。

搭配使用 PKCS12 金鑰儲存區與 Edge for Private Cloud 4.53.00 以上版本

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

關於實作別名

在 Edge 中，金鑰儲存區包含一或多個別名，每個別名包含：

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

在 Edge 中，「信任儲存區」包含一或多個「別名」，每個別名都包含：

• PEM 檔案格式的 TLS 憑證，可以是憑證授權單位 (CA) 簽署的憑證、最後一個憑證由 CA 簽署的憑證鏈，或是自行簽署的憑證。

Edge 提供 UI 和 API，可供您建立 KeyStore、別名、上傳憑證/金鑰配對，以及更新憑證。您用來建立信任儲存區的 UI 和 API，與建立金鑰儲存區的 UI 和 API 相同。不同之處在於建立信任儲存庫時，您建立的別名只包含憑證。

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

您可以將憑證和金鑰表示為 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 檔案。

關於憑證鏈結

如果憑證屬於鏈結，您必須根據憑證是在金鑰儲存區還是信任儲存區中使用，採取不同的處理方式：

• 金鑰儲存區 - 如果憑證屬於鏈結，則必須建立單一檔案，其中包含鏈結中的所有憑證。憑證必須依序排列，最後一個憑證必須是根憑證，或是由根憑證簽署的中繼憑證。
• 信任儲存庫 - 如果憑證屬於鏈結，您必須建立包含所有憑證的單一檔案，並將該檔案上傳至別名，或是使用不同別名將鏈結中的所有憑證分別上傳至信任儲存庫。如果將憑證上傳為單一憑證，憑證必須依序排列，最後一個憑證必須是根憑證，或是由根憑證簽署的中繼憑證。
• 如果建立的單一檔案包含多個憑證，則每個憑證之間必須插入空白行。

舉例來說，您可以將所有憑證合併為單一 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 傳送至用戶端時，用戶端驗證就會成功。

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

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

FIPS 注意事項

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

探索「TLS 金鑰儲存庫」頁面

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

如上圖所示，您可以在「TLS Keystores」(傳輸層安全標準金鑰儲存區) 頁面執行下列操作：

• 選取一個環境
• 建立 KeyStore 和別名
• 測試和刪除金鑰儲存區
• 查看和刪除別名

查看別名

如要查看別名：

1. 存取「TLS Keystores」(傳輸層安全標準金鑰儲存區) 頁面。
2. 選取環境 (通常為 prod 或 test)。
3. 找出要查看的別名，然後按一下對應的資料列。

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

4. 使用頁面頂端的按鈕管理憑證：
   • 將憑證下載為 PEM 檔案。
   • 產生 CSR。如果憑證已過期，但您想續約，可以下載憑證簽署要求 (CSR)。然後將 CSR 傳送給 CA，以取得新憑證。
   • 更新憑證。注意：如果更新虛擬主機或目標伺服器/目標端點目前使用的憑證，請務必與 Apigee Edge 支援團隊聯絡，重新啟動路由器和訊息處理器。建議您採取下列做法更新憑證：
     1. 建立新的金鑰儲存區或信任儲存庫。
     2. 將新憑證新增至新的金鑰儲存區或信任儲存庫。
     3. 在虛擬主機或目標伺服器/目標端點中，將參照更新為金鑰儲存區或信任儲存區。詳情請參閱「 更新 Cloud 的傳輸層安全標準 (TLS) 憑證」。
     4. 刪除別名。注意：如果刪除別名，且虛擬主機或目標端點目前正在使用該別名，虛擬主機或目標端點就會失敗。

建立金鑰儲存庫/信任儲存庫和別名

您可以建立 KeyStore，做為 TLS KeyStore 或 TLS 信任儲存庫 使用。金鑰存放區是貴機構環境專屬的項目，例如測試或正式環境。因此，如要在測試環境中測試金鑰儲存區，再將其部署至正式環境，您必須在這兩個環境中建立金鑰儲存區。

如要在環境中建立 KeyStore，只需指定 KeyStore 名稱即可。在環境中建立具名 KeyStore 後，您就可以建立別名，並將憑證/金鑰組 (KeyStore) 上傳至別名，或只上傳憑證 (信任儲存區)。

如何建立金鑰儲存區：

1. 存取「TLS Keystores」(TLS 金鑰儲存庫) 頁面。
2. 選取環境 (通常為 prod 或 test)。
3. 按一下「+ Keystore」。
4. 指定 KeyStore 名稱。名稱只能包含英數字元。
5. 按一下「新增金鑰儲存區」。清單中會顯示新的金鑰儲存區。
6. 請使用下列其中一個程序新增別名。另請參閱 支援的憑證檔案格式。
   • 從憑證建立別名 (僅限信任儲存區)
   • 從 JAR 檔案建立別名 (僅限金鑰庫)
   • 建立別名 從憑證和金鑰 (僅限金鑰儲存庫)
   • 從 PKCS12/PFX 檔案建立別名 (僅限金鑰儲存庫)
   • 從自行簽署的憑證建立別名 (僅限金鑰儲存區)

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

如何從憑證建立別名：

1. 存取「TLS Keystores」(TLS 金鑰儲存庫) 頁面。
2. 將游標懸停在金鑰存放區上，顯示動作選單，然後按一下「+」。
3. 指定「別名」。
4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「僅限憑證」。
5. 按一下「憑證檔案」旁的「選擇檔案」，然後選取含有憑證的 PEM 檔案，並按一下「開啟」。
6. 根據預設，API 會檢查憑證是否過期。視需要選取「允許過期的憑證」，略過驗證。
7. 選取「儲存」，即可上傳憑證並建立別名。

從 JAR 檔案建立別名 (僅限金鑰庫)

如要從 JAR 檔案建立別名，請按照下列步驟操作：

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

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

如要從憑證和金鑰建立別名，請執行下列操作：

1. 存取「TLS Keystores」(TLS 金鑰儲存庫) 頁面。
2. 將游標移至金鑰存放區上，顯示動作選單，然後點選「+」。
3. 指定「別名」。
4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「憑證和金鑰」。
5. 按一下「憑證檔案」旁的「選擇檔案」，然後選取含有憑證的 PEM 檔案，並點選「開啟」。
6. 如果金鑰設有密碼，請指定「金鑰密碼」。如果金鑰沒有密碼，請將這個欄位留空。
7. 按一下「金鑰檔案」旁的「選擇檔案」，然後選取含有金鑰的 PEM 檔案，再點選「開啟」。
8. 根據預設，API 會檢查憑證是否過期。視需要選取「允許過期的憑證」，略過驗證。
9. 選取「儲存」，上傳金鑰和憑證，並建立別名。

從 PKCS12/PFX 檔案建立別名 (僅限金鑰儲存區)

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

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

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

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

如要透過自行簽署的憑證建立別名，請按照下列步驟操作：

1. 存取「TLS Keystores」(TLS 金鑰儲存庫) 頁面。
2. 將游標移至金鑰存放區上，顯示動作選單，然後點選「+」。
3. 指定「別名」。
4. 在「憑證詳細資料」下方，從「類型」下拉式選單中選取「自簽憑證」。
5. 請參考下表填寫表單。
6. 選取「儲存」，建立憑證和私密金鑰組，並上傳至別名。

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

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

下表說明表單欄位：

測試金鑰儲存區或信任儲存庫

您可以在 Edge 使用者介面中測試信任儲存區和金鑰儲存區，確認設定正確無誤。測試 UI 會驗證從 Edge 到後端服務的 TLS 要求。後端服務可設定為支援單向或雙向 TLS。

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

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

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

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

將憑證新增至雙向 TLS 的信任儲存區

使用雙向 TLS 進行連入連線 (也就是對 Edge 發出的 API 要求) 時，信任儲存區會包含允許對 Edge 提出要求的每個用戶端的憑證或 CA 鏈結。

首次設定信任儲存區時，您可以新增已知用戶端的所有憑證。不過，隨著您新增用戶端，可能需要將其他憑證新增至信任儲存庫。

如要將新憑證新增至雙向傳輸層安全標準：TLS 使用的信任儲存庫，請按照下列步驟操作：

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

3. 更新信任儲存區參照，將其設為相同值。 更新後，Edge 會重新載入信任儲存區和新憑證。

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

刪除金鑰儲存庫/信任儲存庫或別名

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

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

1. 按照上述方式建立新的 KeyStore/TrustStore 或別名。
2. 如果是連入連線 (也就是傳送至 Edge 的 API 要求)，請更新虛擬主機設定，以參照新的金鑰儲存區和金鑰別名。
3. 如果是輸出連線，也就是從 Apigee 連線至後端伺服器：
   1. 更新參照舊金鑰儲存區和金鑰別名的所有 API Proxy 的 TargetEndpoint 設定，以參照新的金鑰儲存區和金鑰別名。如果 TargetEndpoint 參照 TargetServer，請更新 TargetServer 定義，參照新的金鑰儲存區和金鑰別名。
   2. 如果直接從 TargetEndpoint 定義參照金鑰儲存區和信任儲存區，則必須重新部署 Proxy。如果 TargetEndpoint 參照 TargetServer 定義，且 TargetServer 定義參照金鑰儲存區和信任儲存區，則不必重新部署 Proxy。
4. 確認 API Proxy 運作正常。
5. 刪除金鑰儲存區/信任儲存區或別名。

刪除金鑰儲存庫

如要刪除金鑰儲存區或信任儲存區，請將游標懸停在清單中的金鑰儲存區或信任儲存區上，顯示動作選單，然後按一下 。如果刪除虛擬主機或目標端點/目標伺服器使用的金鑰儲存區或信任儲存區，透過虛擬主機或目標端點/目標伺服器發出的所有 API 呼叫都會失敗。

注意：您應先轉換虛擬主機和目標端點/目標伺服器，改用新的金鑰儲存區，再刪除金鑰儲存區。

刪除別名

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

注意：請勿刪除別名，直到您已轉換虛擬主機和目標端點/目標伺服器，改用新的金鑰儲存區和別名為止。