使用 Edge UI 建立 KeyStore 和 TrustStore

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件
資訊

本文說明如何建立、修改及刪除 Edge 適用 Cloud 和 Edge 適用的 KeyStore 和信任存放區 (適用於 4.18.01 以上版本)。

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

在建立 Edge Cloud 專用 KeyStore/truststore 的過程中,您必須遵循使用虛擬主機的所有規則。舉例來說,在 Cloud 中的虛擬主機:

  • 虛擬主機必須使用傳輸層安全標準 (TLS)。
  • 虛擬主機只能使用通訊埠 443。
  • 請務必使用已簽署的傳輸層安全標準 (TLS) 憑證。未簽署的憑證不得與雲端中的虛擬主機搭配使用。
  • TLS 憑證指定的網域名稱必須與虛擬主機的主機別名相符。

瞭解詳情:

在 Edge 中實作 KeyStore 和信任儲存庫

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

在 Edge 中,KeyStore 和信任儲存庫都是以包含一或多個 aliasKeystore 實體表示。也就是說,KeyStore 和 Edge 上的信任儲存庫之間並無差異。

KeyStore 和信任儲存庫之間的差異,在於這些金鑰包含的項目種類,以及在 TLS 手勢中使用的方式:

  • KeyStore - 包含一或多個「別名」的「Keystore」實體,每個別名都包含一個憑證/金鑰組。
  • 信任儲存庫 - 包含一或多個「別名」的「Keystore」實體,每個別名都僅包含一個憑證。

為虛擬主機或目標端點設定 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>

在此範例中,您要指定虛擬主機在 TLS KeyStore 中使用的 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,不會指定特定別名。KeyStore 中的每個別名都包含憑證或憑證鏈,做為 TLS 執行程序的一部分。

支援的憑證格式

形式 支援 API 和 UI 上傳功能 支援北行 已驗證
PEM
* PKCS12
附註:Apigee 會在內部將
PKCS12 轉換為 PEM。
* 客層
* PKCS7

* 我們建議盡量採用 PEM。

關於實作別名

在 Edge 上,「Keystore」包含一或多個「別名」,其中每個別名都包含:

  • 做為 PEM 或 PKCS12/PFX 檔案的傳輸層安全標準 (TLS) 憑證:由憑證授權單位 (CA) 簽署的憑證。這個檔案包含憑證鏈結,其中最後一個憑證是由 CA 或自行簽署的憑證。
  • 做為 PEM 或 PKCS12/PFX 檔案的私密金鑰。Edge 支援的金鑰大小上限為 2048 位元。通關密語為選用項目。

在 Edge 上,「truststore」包含一或多個「別名」,其中每個別名都包含:

  • 做為 PEM 檔案的傳輸層安全標準 (TLS) 憑證:由憑證授權單位 (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 格式相容,您可以在 KeyStore 或信任存放區中使用,不必將這類檔案轉換為 PEM 檔案。

憑證鏈結簡介

如果憑證是鏈結的一部分,您處理憑證的方式會依憑證是在 KeyStore 或信任儲存庫中使用:

  • KeyStore:如果憑證屬於鏈結的一部分,您必須建立一個包含鏈結所有憑證的單一檔案。憑證必須依序執行,最後一個憑證必須是根憑證,或是由根憑證簽署的中繼憑證。
  • 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 實作程序時,用戶端驗證作業就會成功。

或者,您也可以用同一個憑證 (ca_cert) 簽署第二個憑證 (client_cert_2)。但不會將 client_cert_2 上傳至信任儲存庫。信任儲存庫仍然只包含 client_cert_1ca_cert

當伺服器以 TLS 手動的方式傳遞 client_cert_2 時,要求就會成功。這是因為如果信任儲存庫中不存在 client_cert_2,但是由信任儲存庫中的憑證簽署,Edge 允許傳輸層安全標準 (TLS) 驗證作業成功。如果移除 CA 憑證 (ca_cert),就會從信任儲存庫中移除,傳輸層安全標準 (TLS) 驗證作業就會失敗。

探索 TLS KeyStore 頁面

存取「TLS KeyStore」頁面,如下所述。

Edge

如何使用 Edge UI 存取「TLS KeyStore」頁面:

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

傳統版邊緣 (Private Cloud)

如何使用傳統版 Edge UI 存取「TLS KeyStore」頁面:

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

系統會隨即顯示「TLS KeyStore」頁面:

如上圖所示,「TLS KeyStore」頁面可讓您:

查看別名

如何查看別名:

  1. 存取 TLS KeyStore 頁面
  2. 選取環境 (通常是 prodtest)。
  3. 按一下您要查看的別名所屬資料列。

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

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

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

建立 KeyStore/truststore 和別名

您可以建立 KeyStore,並將其做為傳輸層安全標準 (TLS) KeyStore 或傳輸層安全標準 (TLS) 信任儲存庫。KeyStore 專屬於貴機構的環境,例如測試或實際工作環境。因此,如要先在測試環境中測試 KeyStore,再將 KeyStore 部署至實際工作環境,您必須先在這兩種環境中建立 KeyStore。

如要在環境中建立 KeyStore,只需指定 KeyStore 名稱即可。在環境中建立已命名的 KeyStore 後,即可建立別名並上傳憑證/金鑰組 (Keystore),或只將憑證 (信任存放區) 上傳至別名。

如何建立 KeyStore:

  1. 存取 TLS KeyStore 頁面
  2. 選取環境 (通常是 prodtest)。
  3. 按一下「+ KeyStore」
  4. 指定 KeyStore 名稱。(名稱只能包含英數字元)。
  5. 按一下「Add KeyStore」。新的 KeyStore 會顯示在清單中。
  6. 按照下列其中一種程序新增別名。另請參閱支援的憑證檔案格式

從憑證建立別名 (僅限 truststore)

如何從憑證建立別名:

  1. 存取 TLS KeyStore 頁面
  2. 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+
  3. 指定「Alias Name」
  4. 在「憑證詳細資料」下方的「類型」下拉式選單中,選取「僅限憑證」
  5. 按一下「憑證檔案」旁邊的「選擇檔案」,前往含有憑證的 PEM 檔案,然後點選「開啟」
  6. 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
  7. 選取「儲存」以上傳憑證並建立別名。

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

如要從 JAR 檔案建立別名:

  1. 存取 TLS KeyStore 頁面
  2. 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+
  3. 指定「Alias Name」
  4. 在「Certificate details」(憑證詳細資料) 下方的「Type」(類型) 下拉式選單中,選取「JAR File」(JAR 檔案)
  5. 按一下「JAR File」旁邊的「Choose File」,找到含有憑證和金鑰的 JAR 檔案,然後按一下「Open」
  6. 如果金鑰設有密碼,請指定「密碼」。如果金鑰沒有密碼,請將這個欄位留空。
  7. 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
  8. 選取「儲存」,上傳金鑰和憑證並建立別名。

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

如何根據憑證和金鑰建立別名:

  1. 存取 TLS KeyStore 頁面
  2. 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+
  3. 指定「Alias Name」
  4. 在「憑證詳細資料」下方的「類型」下拉式選單中,選取「憑證和金鑰」
  5. 按一下「憑證檔案」旁邊的「選擇檔案」,找到含有憑證的 PEM 檔案,然後點選「開啟」
  6. 如果金鑰設有密碼,請指定金鑰密碼。如果金鑰沒有密碼,請將這個欄位留空。
  7. 按一下「金鑰檔案」旁邊的「選擇檔案」,找到含有金鑰的 PEM 檔案,然後點選「開啟」
  8. 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
  9. 選取「儲存」,上傳金鑰和憑證並建立別名。

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

如何透過包含憑證和金鑰的 PKCS12 檔案建立別名:

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

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

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

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

  1. 存取 TLS KeyStore 頁面
  2. 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+
  3. 指定「Alias Name」
  4. 在「憑證詳細資料」下方的「類型」下拉式選單中選取「自簽署憑證」
  5. 請使用下表填寫表單。
  6. 選取 [儲存] 以建立憑證和私密金鑰組,並上傳到別名。

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

  • 核發者
    簽署及核發憑證的實體。如果是自行簽署的憑證,這就是您在建立憑證時指定的 CN。
  • 有效期限
    憑證有效期,以兩個日期表示:憑證有效期間的開始日期,以及憑證有效期限的結束日期。兩者皆可編碼為 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 個半形字元。 不適用
國家/地區 雙字母國家/地區代碼。範例:IN 代表印度,美國代表美國。 不適用
替代名稱 替代主機名稱的清單。允許將其他身分繫結至憑證主體。定義的選項包括網際網路電子郵件位址、DNS 名稱、IP 位址和統一資源 ID (URI)。

每個值的字元數上限為 255 個字元。您可以使用半形逗號分隔名稱,或是在每個名稱後面按下 Enter 鍵。

不適用

測試 KeyStore 或信任儲存庫

您可以在 Edge UI 中測試信任儲存庫和 KeyStore,確認兩者的設定正確無誤。測試 Ui 會驗證從 Edge 到後端服務的 TLS 要求。您可以將後端服務設為支援單向或雙向傳輸層安全標準 (TLS)。

如何測試單向傳輸層安全標準 (TLS):

  1. 存取 TLS KeyStore 頁面
  2. 選取環境 (通常是 prodtest)。
  3. 將遊標移到要測試的 TLS KeyStore 上,即可顯示動作選單,然後按一下「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、信任存放區或別名,所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。

一般來說,刪除 KeyStore/truststore 或別名的程序如下:

  1. 按照上述說明建立新的 KeyStore/truststore 或別名。
  2. 針對「傳入連線」(也就是向 Edge 發出的 API 要求),請更新虛擬主機設定,以參照新的 KeyStore 和金鑰別名。
  3. 針對「傳出連線」,也就是從 Apigee 到後端伺服器:
    1. 針對參照舊 KeyStore 和金鑰別名的所有 API Proxy,更新 TargetEndpoint 設定,以參照新 KeyStore 和金鑰別名。如果您的 TargetEndpoint 會參照 TargetServer,請更新 TargetServer 定義以參照新的 KeyStore 和金鑰別名。
    2. 如果直接從 TargetEndpoint 定義參照 KeyStore 和信任儲存庫,您就必須重新部署 Proxy。如果 TargetEndpoint 參照 TargetServer 定義,且 TargetServer 定義參照了 KeyStore 和 Truststore,則無需重新部署 Proxy。
  4. 確認 API Proxy 運作正常。
  5. 刪除 KeyStore/truststore 或別名。

刪除 KeyStore

如要刪除 KeyStore 或信任儲存庫,請將遊標移至 KeyStore 或信任項目上,以顯示動作選單,然後按一下 。如果刪除虛擬主機或目標端點/目標伺服器正在使用的 KeyStore 或信任儲存庫,所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。

注意:您必須先轉換虛擬主機和目標端點/目標伺服器,才能使用新的 KeyStore,否則請勿刪除 KeyStore。

刪除別名

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

注意:您必須先轉換虛擬主機和目標端點/目標伺服器,才能使用新的 KeyStore 和別名,否則請勿刪除別名。