您正在查看 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 和信任儲存庫都是以包含一或多個 alias 的 Keystore 實體表示。也就是說,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_1
和 ca_cert
。
當伺服器以 TLS 手動的方式傳遞 client_cert_2
時,要求就會成功。這是因為如果信任儲存庫中不存在 client_cert_2
,但是由信任儲存庫中的憑證簽署,Edge 允許傳輸層安全標準 (TLS) 驗證作業成功。如果移除 CA 憑證 (ca_cert
),就會從信任儲存庫中移除,傳輸層安全標準 (TLS) 驗證作業就會失敗。
探索 TLS KeyStore 頁面
存取「TLS KeyStore」頁面,如下所述。Edge
如何使用 Edge UI 存取「TLS KeyStore」頁面:
- 以機構組織管理員的身分登入 https://apigee.com/edge。
- 選取您的機構。
- 依序選取「Admin」>「Environment」>「TLS KeyStores」。
傳統版邊緣 (Private Cloud)
如何使用傳統版 Edge UI 存取「TLS KeyStore」頁面:
- 以機構管理員身分登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 選取您的機構。
- 依序選取「Admin」>「Environment Configuration」>「TLS KeyStores」。
系統會隨即顯示「TLS KeyStore」頁面:
如上圖所示,「TLS KeyStore」頁面可讓您:
- 選取一個環境
- 建立 KeyStore 和別名
- 測試及刪除 KeyStore
- 查看及刪除別名
查看別名
如何查看別名:
- 存取 TLS KeyStore 頁面。
- 選取環境 (通常是
prod
或test
)。 - 按一下您要查看的別名所屬資料列。
系統顯示別名憑證和金鑰的詳細資料。
您可以查看別名的所有相關資訊,包括到期日。 - 使用頁面頂端的按鈕即可管理憑證,包括:
- 將憑證下載為 PEM 檔案。
- 產生 CSR。如果您的憑證已過期,如要更新憑證,可以下載憑證簽署要求 (CSR)。然後將 CSR 傳送至 CA 以取得新的憑證。
- 更新憑證。注意:如果您要更新目前由虛擬主機或目標伺服器/目標端點使用的憑證,就必須與 Apigee Edge 支援團隊聯絡,才能重新啟動路由器和訊息處理器。如要更新憑證,建議採取下列做法:
- 建立新的 KeyStore 或信任儲存庫。
- 將新憑證新增至新的 KeyStore 或信任儲存庫。
- 將虛擬主機或目標伺服器/目標端點中的參照更新為 KeyStore 或信任儲存庫。詳情請參閱「 更新雲端的傳輸層安全標準 (TLS) 憑證」。
- 刪除別名。注意:如果刪除別名,且目前有虛擬主機或目標端點正在使用別名,虛擬主機或目標端點就會失敗。
建立 KeyStore/truststore 和別名
您可以建立 KeyStore,並將其做為傳輸層安全標準 (TLS) KeyStore 或傳輸層安全標準 (TLS) 信任儲存庫。KeyStore 專屬於貴機構的環境,例如測試或實際工作環境。因此,如要先在測試環境中測試 KeyStore,再將 KeyStore 部署至實際工作環境,您必須先在這兩種環境中建立 KeyStore。
如要在環境中建立 KeyStore,只需指定 KeyStore 名稱即可。在環境中建立已命名的 KeyStore 後,即可建立別名並上傳憑證/金鑰組 (Keystore),或只將憑證 (信任存放區) 上傳至別名。
如何建立 KeyStore:
- 存取 TLS KeyStore 頁面。
- 選取環境 (通常是
prod
或test
)。 - 按一下「+ KeyStore」。
- 指定 KeyStore 名稱。(名稱只能包含英數字元)。
- 按一下「Add KeyStore」。新的 KeyStore 會顯示在清單中。
- 按照下列其中一種程序新增別名。另請參閱支援的憑證檔案格式。
從憑證建立別名 (僅限 truststore)
如何從憑證建立別名:
- 存取 TLS KeyStore 頁面。
- 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+。
- 指定「Alias Name」。
- 在「憑證詳細資料」下方的「類型」下拉式選單中,選取「僅限憑證」。
- 按一下「憑證檔案」旁邊的「選擇檔案」,前往含有憑證的 PEM 檔案,然後點選「開啟」。
- 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
- 選取「儲存」以上傳憑證並建立別名。
從 JAR 檔案建立別名 (僅限 KeyStore)
如要從 JAR 檔案建立別名:
- 存取 TLS KeyStore 頁面。
- 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+。
- 指定「Alias Name」。
- 在「Certificate details」(憑證詳細資料) 下方的「Type」(類型) 下拉式選單中,選取「JAR File」(JAR 檔案)。
- 按一下「JAR File」旁邊的「Choose File」,找到含有憑證和金鑰的 JAR 檔案,然後按一下「Open」。
- 如果金鑰設有密碼,請指定「密碼」。如果金鑰沒有密碼,請將這個欄位留空。
- 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
- 選取「儲存」,上傳金鑰和憑證並建立別名。
使用憑證和金鑰建立別名 (僅限 KeyStore)
如何根據憑證和金鑰建立別名:
- 存取 TLS KeyStore 頁面。
- 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+。
- 指定「Alias Name」。
- 在「憑證詳細資料」下方的「類型」下拉式選單中,選取「憑證和金鑰」。
- 按一下「憑證檔案」旁邊的「選擇檔案」,找到含有憑證的 PEM 檔案,然後點選「開啟」。
- 如果金鑰設有密碼,請指定金鑰密碼。如果金鑰沒有密碼,請將這個欄位留空。
- 按一下「金鑰檔案」旁邊的「選擇檔案」,找到含有金鑰的 PEM 檔案,然後點選「開啟」。
- 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
- 選取「儲存」,上傳金鑰和憑證並建立別名。
從 PKCS12/PFX 檔案建立別名 (僅限 KeyStore)
如何透過包含憑證和金鑰的 PKCS12 檔案建立別名:
- 存取 TLS KeyStore 頁面。
- 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+。
- 指定「Alias Name」。
- 在「憑證詳細資料」下方的「類型」下拉式選單中,選取「PKCS12/PFX」。
- 按一下「PKCS12/PFX」旁邊的「選擇檔案」,前往包含金鑰和憑證的檔案,然後按一下「開啟」。
- 如果金鑰內有密碼,請指定 PKCS12/PFX 檔案的密碼。 如果金鑰沒有密碼,請將這個欄位留白。
- 根據預設,API 會檢查憑證是否尚未過期。您可以選取「Allow Expired Certificate」(允許過期憑證),以略過驗證程序。
- 選取「Save」(儲存),上傳檔案並建立別名。
使用自行簽署的憑證建立別名 (僅限 KeyStore)
如要建立使用自行簽署憑證的別名,請在表單中填寫建立憑證所需的必要資訊。接著,Edge 接著會建立憑證和私密金鑰組,並上傳至別名。
如何透過自行簽署的憑證建立別名:
- 存取 TLS KeyStore 頁面。
- 將遊標移到 KeyStore 上,即可顯示動作選單,然後按一下「+」+。
- 指定「Alias Name」。
- 在「憑證詳細資料」下方的「類型」下拉式選單中選取「自簽署憑證」。
- 請使用下表填寫表單。
- 選取 [儲存] 以建立憑證和私密金鑰組,並上傳到別名。
在產生的憑證中,您會看到下列額外欄位:
- 核發者
簽署及核發憑證的實體。如果是自行簽署的憑證,這就是您在建立憑證時指定的 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):
- 存取 TLS KeyStore 頁面。
- 選取環境 (通常是
prod
或test
)。 - 將遊標移到要測試的 TLS KeyStore 上,即可顯示動作選單,然後按一下「Test」。下方對話方塊會顯示信任儲存庫的名稱:
- 輸入後端服務的主機名稱。
- 輸入 TLS 通訊埠編號 (通常為 443)。
- 視需要指定任何通訊協定或加密演算法。
- 選取「測試」。
如何測試雙向傳輸層安全標準 (TLS):
- 選取所需的信任儲存庫,選取「Test」按鈕。
- 在對話方塊中,為「SSL Test Type」選取「Two Way」。系統隨即會顯示下列對話方塊:
- 指定用於雙向傳輸層安全標準 (TLS) 的 KeyStore 名稱。
- 在含有憑證和金鑰的 KeyStore 中指定別名名稱。
- 輸入後端服務的主機名稱。
- 輸入 TLS 通訊埠編號 (通常為 443)。
- 視需要指定任何通訊協定或加密演算法。
- 選取「測試」。
將憑證新增至採用雙向傳輸層安全標準 (TLS) 的信任存放區
使用雙向傳輸層安全標準 (TLS) 傳入連線時 (亦即對 Edge 發出的 API 要求),信任儲存庫會為每個可向 Edge 發出要求的用戶端建立憑證或 CA 鏈結。
一開始設定信任儲存庫時,您可以為已知的用戶端新增所有憑證。不過,經過一段時間後,當您新增用戶端時,可能會想要將其他憑證新增至信任儲存庫。
如何將新憑證新增至用於雙向傳輸層安全標準 (TLS) 的信任存放區:
- 請務必在虛擬主機中使用信任儲存庫的參照。
- 按照上方透過憑證建立別名 (僅限 truststore) 的說明,將新的憑證上傳至信任儲存庫。
更新信任儲存庫參照,將其設為「相同」值。這項更新會導致 Edge 重新載入信任存放區和新憑證。
詳情請參閱修改參考檔案。
刪除 KeyStore/truststore 或別名
刪除 KeyStore/truststore 或別名時,請務必謹慎行事。如果刪除虛擬主機、目標端點或目標伺服器正在使用的 KeyStore、信任存放區或別名,所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。
一般來說,刪除 KeyStore/truststore 或別名的程序如下:
- 按照上述說明建立新的 KeyStore/truststore 或別名。
- 針對「傳入連線」(也就是向 Edge 發出的 API 要求),請更新虛擬主機設定,以參照新的 KeyStore 和金鑰別名。
- 針對「傳出連線」,也就是從 Apigee 到後端伺服器:
- 針對參照舊 KeyStore 和金鑰別名的所有 API Proxy,更新 TargetEndpoint 設定,以參照新 KeyStore 和金鑰別名。如果您的 TargetEndpoint 會參照 TargetServer,請更新 TargetServer 定義以參照新的 KeyStore 和金鑰別名。
- 如果直接從 TargetEndpoint 定義參照 KeyStore 和信任儲存庫,您就必須重新部署 Proxy。如果 TargetEndpoint 參照 TargetServer 定義,且 TargetServer 定義參照了 KeyStore 和 Truststore,則無需重新部署 Proxy。
- 確認 API Proxy 運作正常。
- 刪除 KeyStore/truststore 或別名。
刪除 KeyStore
如要刪除 KeyStore 或信任儲存庫,請將遊標移至 KeyStore 或信任項目上,以顯示動作選單,然後按一下 。如果刪除虛擬主機或目標端點/目標伺服器正在使用的 KeyStore 或信任儲存庫,所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。
注意:您必須先轉換虛擬主機和目標端點/目標伺服器,才能使用新的 KeyStore,否則請勿刪除 KeyStore。
刪除別名
如要刪除別名寶寶,請將遊標移到清單中的別名上以顯示動作選單,然後按一下 。如果刪除虛擬主機或目標端點/目標伺服器正在使用的別名,所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。
注意:您必須先轉換虛擬主機和目標端點/目標伺服器,才能使用新的 KeyStore 和別名,否則請勿刪除別名。