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

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本文說明如何建立、修改及刪除 Edge 的金鑰存放區和信任存放區，適用於 Private Cloud 4.17.09 以下版本。

關於 KeyStore 和 TrustStore

KeyStore 和 TrustStore 會定義用於 TLS 加密的安全憑證存放區。兩者的主要差異在於，它們在 TLS 握手程序中的作用：

  • KeyStore 包含 TLS 憑證和私密金鑰，用於在 TLS 握手期間識別實體。

    在單向 TLS 中，當用戶端連線至伺服器上的 TLS 端點時，伺服器的 KeyStore 會將伺服器的憑證 (公開憑證) 呈現給用戶端。接著，用戶端會透過憑證授權單位 (CA) 驗證憑證，例如 Symantec 或 VeriSign。

    在雙向 TLS 中，用戶端和伺服器都會維護一個 KeyStore，其中包含用於雙向驗證的憑證和私密金鑰。
  • 信任存放區包含用於驗證在 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 上，金鑰庫包含一或多個 JAR 檔案，而 JAR 檔案包含下列項目：

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

信任存放區與金鑰存放區類似，但只包含 PEM 檔案形式的憑證，而沒有私密金鑰。

如果憑證是鏈結的一部分，則金鑰存放區/信任存放區必須包含鏈結中的所有憑證，可為個別 PEM 檔案或單一檔案。如果您使用單一檔案，則憑證必須依序排列，其中檔案中的第一個憑證是用於 TLS 的憑證，接著是憑證鏈結，依序連結至 CA 憑證。您必須在檔案中的每個憑證之間插入空白行。

Edge 提供 API，可用於建立金鑰庫和信任存放區。實際的 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 格式相容，您可以在金鑰庫或信任金鑰庫中使用這些檔案，而無須將檔案轉換為 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-----

取得現有 KeyStore 的詳細資料

使用「List Keystores and 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 之前，傳回的陣列會是空白的。

使用 Get a Keystore or 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. 登入 Edge 管理介面 UI，網址為 https://enterprise.apigee.com (雲端) 或 http://<ms-ip>:9000 (地端)，其中 <ms-ip> 是管理伺服器節點的 IP 位址。
  2. 在 Edge 管理 UI 選單中，依序選取「Admin」>「TLS Certificates」。

取得 TLS 憑證詳細資料

您可以使用 Get Cert Details from a Keystore or 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. 登入 Edge 管理介面 UI 的網址為 https://enterprise.apigee.com (雲端) 或 http://<ms-ip>:9000 (地端)，其中 <ms-ip> 是管理伺服器節點的 IP 位址。
  2. 在 Edge 管理 UI 選單中，依序選取「Admin」>「TLS Certificates」。

您可以在 Edge UI 中指定 Edge 提前多久通知憑證即將到期。根據預設，UI 會醒目顯示接下來 10 天內即將到期的憑證。

建立 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

將 descriptor.properties 新增至 JAR 檔案：

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

建立 KeyStore 並上傳 JAR 檔案

如要在環境中建立 KeyStore，您只需將 KeyStore 名稱指定給 Create a KeyStore or 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 後，您可以使用「Upload a JAR file to a 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 - 識別 KeyStore 中的憑證和金鑰。建立虛擬主機時，您可以使用別名名稱參照憑證和金鑰。
  • 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 傳送至用戶端，則用戶端驗證會成功。

或者，您可以使用由同一個憑證 ca_cert 簽署的第二個憑證 client_cert_2。不過，您不會將 client_cert_2 上傳至信任存放區。信任存放區仍包含 client_cert_1 和 ca_cert。

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

使用「Create a Keystore or Truststore」 API (用於建立 KeyStore)，在環境中建立空白的信任存放區：

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

使用「 Upload a Certificate to a 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

您可以使用「Delete a Keystore or 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 或 TrustStore，則透過虛擬主機或目標端點/目標伺服器的所有 API 呼叫都會失敗。