為私有雲 4.17.09 以下版本建立 KeyStore 和 Truststores

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

本文說明如何在 Private Cloud 4.17.09 以下版本建立、修改及刪除 Edge 適用的 KeyStore 和 Truststores。

關於 KeyStore 和 Truststore

KeyStore 和 Truststore 會定義用於 TLS 加密的安全性憑證存放區。兩者的主要差異在於，兩者在傳輸層安全標準 (TLS) 握持程序中使用的位置：

  • KeyStore 包含傳輸層安全標準 (TLS) 憑證和私密金鑰，可在傳輸層安全標準 (TLS) 握持期間用於識別實體。

    在單向傳輸層安全標準 (TLS) 中，當用戶端連線至伺服器上的傳輸層安全標準 (TLS) 端點時，伺服器的 KeyStore 會向用戶端提供伺服器的憑證 (公開憑證)。接著，用戶端會透過憑證授權單位 (CA) (例如 Symantec 或 VeriSign) 驗證憑證。

    在雙向傳輸層安全標準 (TLS) 中，用戶端和伺服器會維護 KeyStore，其中包含自己的憑證和用於雙向驗證的私密金鑰。
  • truststore 包含用於驗證傳輸層安全標準 (TLS) 握手程序所收到憑證的憑證。

    在單向傳輸層安全標準 (TLS) 中，如果憑證是由有效的 CA 簽署，則不需要信任儲存庫。如果 TLS 用戶端收到的憑證由有效的 CA 簽署，則用戶端會向 CA 要求驗證憑證。TLS 用戶端通常會使用信任儲存庫來驗證從 TLS 伺服器收到的自行簽署憑證，或是不是由受信任 CA 簽署的憑證。在這種情況下，用戶端會將自己信任的憑證填入其信任儲存庫。然後，當用戶端收到伺服器憑證時，系統會根據其信任儲存庫中的憑證驗證傳入的憑證。

    舉例來說，TLS 用戶端會連線至傳輸層安全標準 (TLS) 伺服器，而伺服器會使用自行簽署的憑證。因為這是自行簽署的憑證，用戶端無法使用 CA 進行驗證。 用戶端改為將伺服器的自行簽署憑證預先載入至其信任儲存庫。接著，當用戶端嘗試連線至伺服器時，用戶端會使用其信任儲存庫來驗證從伺服器收到的憑證。

    如果是雙向傳輸層安全標準 (TLS)，TLS 用戶端和 TLS 伺服器都可以使用信任儲存庫。如果 Edge 做為 TLS 伺服器，在執行雙向 TLS 時，必須使用信任儲存庫。

憑證可由憑證授權單位 (CA) 核發，也可以由您產生的私密金鑰自行簽署。如果您具備 CA 的存取權，請按照 CA 提供的操作說明產生金鑰及核發憑證。如果您沒有存取 CA，可以使用眾多公開免費工具 (例如 openssl) 產生自行簽署的憑證。

在 Edge 中實作 KeyStore 和 Truststore

在 Edge 上，KeyStore 含有一或多個 JAR 檔案，其中 JAR 檔案含有：

  • 採用 TLS 憑證的 TLS 憑證：由憑證授權單位 (CA) 簽署的憑證、最後由 CA 簽署的憑證鏈結，或是自行簽署的憑證。
  • 做為 PEM 檔案的私密金鑰。Edge 最多支援 2048 位元的金鑰大小。通關密語為選用項目。

信任儲存庫與 KeyStore 相似，但前者只包含憑證做為 PEM 檔案，但沒有私密金鑰。

如果憑證隸屬於某個鏈結，KeyStore/truststore 就必須包含鏈結中的所有憑證，可以是個別 PEM 檔案或單一檔案。如果您使用單一檔案，則憑證必須按照下列順序排序：檔案中的第一個憑證是傳輸層安全標準 (TLS) 所使用的憑證，然後依序是憑證鏈結至 CA 憑證。您必須在檔案中的每個憑證之間插入空白行。

Edge 提供一個 API，可用於建立 KeyStore 和 Truststore。實際的 API 則相同。不同之處在於建立 KeyStore 時，您會傳遞包含憑證和私密金鑰的 JAR 檔案。建立信任儲存庫時，您只能將憑證做為 PEM 檔案傳遞，

憑證和金鑰檔案的格式簡介

本文件範例說明定義為 PEM 檔案的 TLS 憑證和金鑰 (符合 X.509 格式)。如果憑證或私密金鑰並未定義於 PEM 檔案，可以使用 openssl 等公用程式，將其轉換為 PEM 檔案。

不過，許多 .crt 檔案和 .key 檔案已採用 PEM 格式。如果這些檔案是文字檔案，且封裝在以下項目中：

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

或是：

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

這樣檔案就會與 PEM 格式相容，您可以在 KeyStore 或 Truststore 中使用這些檔案，不必將其轉換為 PEM 檔案。

如果您有憑證鏈，並想在 KeyStore 或信任儲存庫中使用該鏈結，則可將所有憑證合併為單一 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-----

取得現有 KeyStore 的詳細資料

使用 List Keystores 和 Truststores API 檢查現有 KeyStore 環境：

curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

對於雲端客戶，測試和正式版環境中的機構都有提供預設的 KeyStore，您應該會看到這兩個環境的這項呼叫結果如下：

[ "freetrial" ]

您可以使用這個預設 KeyStore 來測試 API，並將 API 推送至實際工作環境。不過，在部署至實際工作環境之前，您通常可以先自行建立 KeyStore，並加入自己的憑證和金鑰。

如果是私有雲客戶，在您建立第一個 KeyStore 之前，傳回的陣列會是空的。

使用 取得 KeyStore 或 Truststore API 來檢查 KeyStore 內容。對於雲端客戶，您應該會看到一個伺服器 TLS 憑證，這是 Apigee Edge 為免費試用帳戶提供的預設憑證。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

回應應如下所示：

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

您也可以在 Edge 管理 UI 中查看這項資訊：

  1. 前往 https://enterprise.apigee.com (雲端) 或 http://<ms-ip>:9000 (地端部署)，登入 Edge 管理 UI，其中 <ms-ip> 是管理伺服器節點的 IP 位址。
  2. 在 Edge Management UI 選單中，依序選取「Admin」>「TLS Certificates」。

取得 TLS 憑證詳細資料

您可以使用「 透過 KeyStore 或 Truststore API 取得憑證詳細資料」，查看 KeyStore 中的傳輸層安全標準 (TLS) 憑證詳細資料，例如到期日和核發者。首先，請取得所需的憑證名稱。這個範例會擷取名為「freetrial」的 KeyStore 資訊。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

回應範例：

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

然後使用 certs 屬性的值取得憑證詳細資料：

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

回應範例：

{
 "certInfo" : [ {
   "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
   "isValid" : "Yes",
   "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US",
   "subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
   "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
   "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
   "version" : 3
 } ],
 "name" : "example.apigee.net.crt"
}

您也可以在 Edge 管理 UI 中查看這項資訊：

  1. 前往 https://enterprise.apigee.com (雲端) 或 http://<ms-ip>:9000 (地端部署)，登入 Edge 管理 UI，其中 <ms-ip> 是管理伺服器節點的 IP 位址。
  2. 在 Edge Management UI 選單中，依序選取「Admin」>「TLS Certificates」。

在 Edge UI 中，您可以指定前端表示憑證到期時間多久。根據預設，UI 會醒目顯示在未來 10 天內到期的所有憑證。

建立 KeyStore

KeyStore 專屬於貴機構的某個環境，例如測試或正式環境。因此，如果您想先在測試環境中測試 KeyStore，然後再將其部署至實際工作環境，就必須在這兩個環境中建立這個 KeyStore。

建立 KeyStore 的程序包含兩個步驟：

  1. 建立包含憑證和私密金鑰的 JAR 檔案。
  2. 建立 KeyStore 並上傳 JAR 檔案。

建立包含憑證和私密金鑰的 JAR 檔案

使用您的私密金鑰、憑證和資訊清單建立 JAR 檔案。JAR 檔案必須包含下列檔案和目錄：

/META-INF/descriptor.properties
myCert.pem
myKey.pem

在包含金鑰組和憑證的目錄中，建立名為 /META-INF 的目錄。接著，在 /META-INF 中建立名為 descriptor.properties 的檔案，其中含有下列內容：

certFile={myCertificate}.pem
keyFile={myKey}.pem

產生包含金鑰組和憑證的 JAR 檔案：

jar -cf myKeystore.jar myCert.pem myKey.pem

將 描述元.properties 新增至 JAR 檔案：

jar -uf myKeystore.jar META-INF/descriptor.properties

建立 KeyStore 並上傳 JAR 檔案

如要在環境中建立 KeyStore，您只需要將 KeyStore 名稱指定為「建立 KeyStore 或 Truststore API」即可。名稱只能包含英數字元：

curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password

回應範例：

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystore"
}

在環境中建立已命名的 KeyStore 後，您可以使用 將 JAR 檔案上傳到 KeyStore API，上傳包含憑證和私密金鑰的 JAR 檔案：

curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password

其中 -F 選項會指定 JAR 檔案的路徑。

在這個呼叫中，您會指定兩個查詢參數：

  • alias：識別金鑰庫中的憑證和金鑰。建立虛擬主機時，您可以透過別名名稱參照憑證和金鑰。
  • password：私密金鑰的密碼。如果私密金鑰沒有密碼，請省略這個參數。

確認 KeyStore 是否正確上傳：

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

回應範例：

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

建立信任儲存庫

您用於建立信任儲存庫的 API 與用來建立 KeyStore 的 API 相同。唯一的差別在於您把憑證檔案是以 PEM 檔案形式傳遞，而不是 JAR 檔案。

如果憑證是鏈結的一部分，您必須將該鏈結中的所有憑證分別上傳至信任存放區，或是建立包含所有憑證的單一檔案 (在檔案中的各個憑證之間以換行的方式顯示)。最終憑證通常是由憑證核發者簽署。舉例來說，您在信任儲存庫中上傳了用戶端憑證 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 驗證就會失敗。

使用建立 KeyStore 或 Truststore (您用來建立 KeyStore 的 API)，在環境中建立空白的信任儲存庫：

curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

使用 將憑證上傳至 Truststore API，將憑證以 PEM 檔案的形式上傳至信任存放區：

curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password

其中 -F 選項會指定 PEM 檔案的路徑。

刪除 KeyStore 或 Truststore

您可以使用「刪除 KeyStore 或 Truststore」 API 刪除 KeyStore 或 TrustStore：

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

回應範例：

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

如果刪除由虛擬主機或目標端點/目標/伺服器使用的 KeyStore 或信任儲存庫，則透過虛擬主機或目標端點/目標伺服器執行的所有 API 呼叫都會失敗。