使用 Edge UI 建立 KeyStore 和 TrustStore

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

本文說明如何建立、修改及刪除 Edge 的 KeyStore 和信任儲存庫 。

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

為 Edge Cloud 建立 KeyStore/truststore 的程序需要您遵循 虛擬主機的使用規則以 Cloud 中的虛擬主機為例：

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

瞭解詳情：

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

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

在 Edge 中，KeyStore 和 Truststore 都以 Keystore 實體表示 包含一或多個別名。也就是說，和執行方式不會有差異。 和 Edge 上的 KeyStore 之間

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， 不要指定特定別名KeyStore 中的每個別名都含有一個憑證或憑證鏈結 用於傳輸層安全標準 (TLS) 握手程序中。

支援的憑證格式

格式 支援 API 和 UI 上傳功能 支援北方邊界 已驗證
PEM 是 是 是
* PKCS12 是 是 是
附註：Apigee 內部會將
PKCS12 轉換為 PEM。
* 客層 否 否 是
* PKCS7 否 否 否

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

關於實作別名

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

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

在 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 格式相容，供您在 KeyStore 或 不必轉換為 PEM 檔案

關於憑證鏈結

如果憑證是鏈結的一部分，處理憑證的方式會根據憑證是否用於 KeyStore 或信任儲存庫中：

  • Keystore：如果憑證是鏈結的一部分，您必須建立包含所有憑證的單一檔案 取得鏈結中的憑證憑證必須依序排列，且最後一個憑證必須是根憑證 或由根憑證簽署的中繼憑證。
  • TruststoreTruststore：如果憑證是鏈結的一部分，您必須建立單一檔案 並將該檔案上傳到別名，或上傳鏈結中的所有憑證 使用不同的別名，將各個憑證單獨用於信任存放區。如果上傳 這類憑證，憑證必須依序排列，且最後一個憑證必須是根憑證，或者 由根憑證簽署的中繼憑證。
  • 如果建立包含多個憑證的單一檔案，您必須插入空白行 之間的關聯

舉例來說，您可以將所有憑證合併為一個 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 驗證 失敗。

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

按照下方說明存取「TLS KeyStore」頁面。

Edge

如何使用 Edge UI 存取 TLS KeyStore 頁面：

  1. 以機構管理員身分登入 https://apigee.com/edge。
  2. 選取您的機構。
  3. 依序選取「管理員」>環境 >傳輸層安全標準 (TLS) KeyStore。

傳統版 Edge (Private Cloud)

如何使用傳統版 Edge UI 存取 TLS KeyStore 頁面：

  1. 以機構組織管理員的身分登入 http://ms-ip:9000 (ms-ip 必須成為 Management Server 節點的 IP 位址或 DNS 名稱。
  2. 選取您的機構。
  3. 依序選取「管理員」>環境設定 >傳輸層安全標準 (TLS) KeyStore。

系統會顯示 TLS KeyStore 頁面：

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

，瞭解如何調查及移除這項存取權。

查看別名

如何查看別名：

  1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
  2. 選取環境 (通常是 prod 或 test)。
  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) 或只將憑證 (truststore) 上傳至別名。

如何建立 KeyStore：

  1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
  2. 選取環境 (通常是 prod 或 test)。
  3. 按一下「+ KeyStore」。
  4. 指定 KeyStore 名稱。這個名稱只能包含英數字元。
  5. 按一下「新增 KeyStore」。清單中會顯示新的 KeyStore。
  6. 按照下列任一程序新增別名。其他參考資訊 支援的憑證檔案格式。

透過憑證 (truststore) 建立別名 )

如何透過憑證建立別名：

  1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
  2. 將遊標移到 KeyStore 上，以顯示動作選單並按一下 +。
  3. 指定「別名名稱」。
  4. 在「Certificate details」(憑證詳細資料) 之下，於 [Type] (類型) 下拉式選單中選取 [Certificate Only] (僅限憑證)。
  5. 按一下「憑證檔案」旁邊的 [選擇檔案]，前往 含有憑證的 PEM 檔案，然後點選「Open」。
  6. 根據預設，API 會檢查並確認憑證尚未過期。視需要選取 選取 [允許過期憑證] 即可略過驗證步驟。
  7. 選取「儲存」，上傳憑證並建立別名。

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

如何從 JAR 檔案建立別名：

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

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

如何透過憑證和金鑰建立別名：

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

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

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

  1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
  2. 將遊標移到 KeyStore 上，以顯示動作選單並按一下 +。
  3. 指定「別名名稱」。
  4. 在「Certificate details」(憑證詳細資料) 底下的「Type」(類型) 下拉式選單中選取 [PKCS12/PFX]。
  5. 按一下「PKCS12/PFX」旁的「選擇檔案」，前往 檔案，然後按一下「Open」。
  6. 如果金鑰設有密碼，請指定 PKCS12/PFX 檔案的「密碼」。 如果金鑰沒有密碼，請將此欄位留空。
  7. 根據預設，API 會檢查並確認憑證尚未過期。視需要選取 選取 [允許過期憑證] 即可略過驗證步驟。
  8. 選取「儲存」，上傳檔案並建立別名。

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

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

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

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

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

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

下表說明表單欄位：

表單欄位 說明 預設 必填
別名名稱 別名名稱。長度上限為 128 個半形字元。 不適用 是
金鑰大小 金鑰的大小，以位元為單位。預設值與最大值為 2048 位元。 2048 否
簽名演算法 產生私密金鑰的簽章演算法。有效值為「SHA512withRSA」、 「SHA384withRSA」以及「SHA256withRSA」(預設)。 SHA256 和 RSA 否
憑證有效期限 (天) 憑證的有效期，以天為單位。可接受非零值。 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 中測試 Truststore 和 KeyStore，確認已設定完成 正確做法。測試 Ui 會驗證從 Edge 到後端服務的 TLS 要求。後端服務 您可以設定為支援單向或雙向 TLS

如何測試單向 TLS：

  1. 存取傳輸層安全標準 (TLS) KeyStore 頁面。
  2. 選取環境 (通常是 prod 或 test)。
  3. 將遊標移至要測試的 TLS KeyStore 上以顯示動作選單，然後按一下「測試」。下列對話方塊 畫面上會出現信任存放區名稱的方塊：
  4. 輸入後端服務的主機名稱。
  5. 輸入 TLS 通訊埠號碼 (通常為 443)。
  6. 視需要指定任何通訊協定或加密。
  7. 選取「測試」。

如何測試雙向 TLS：

  1. 針對所需的信任存放區，選取「Test」(測試) 按鈕。
  2. 在對話方塊中，選取「SSL 測試類型」的「雙向」。 系統隨即會顯示以下對話方塊：
  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. 針對參照舊舊版本的所有 API Proxy 更新 TargetEndpoint 設定 用來參照新的 KeyStore 和金鑰別名的 KeyStore 和金鑰別名。如果您的目標端點 參照 TargetServer，請更新 TargetServer 定義，以參照新的 KeyStore 以及金鑰別名
    2. 如果系統直接從 TargetEndpoint 參照 KeyStore 和信任儲存庫 定義，您就必須重新部署 Proxy。如果 TargetEndpoint 參照 TargetServer 定義，而 TargetServer 定義會參照 KeyStore 並 則不需要重新部署 Proxy。
  4. 確認您的 API Proxy 可正常運作。
  5. 刪除 KeyStore/truststore 或別名。

刪除 KeyStore

如要刪除 KeyStore 或信任儲存庫，請將遊標移到清單中的 KeyStore 或信任存放區，即可顯示動作 並點選「」。刪除正在存取的 KeyStore 或信任存放區 透過虛擬主機使用的所有 API 呼叫 否則目標端點/目標伺服器就會失敗

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

刪除別名

如要刪除別名，請將遊標移到清單中的別名上，即可顯示動作 並點選「」。如果您要刪除虛擬主機正在使用的別名，或是 目標端點/目標伺服器、所有透過虛擬主機或目標端點/目標進行的 API 呼叫 伺服器故障。

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