本頁面由 Cloud Translation API 翻譯而成。

使用 Edge Management API 建立 KeyStore 和信任存放區

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

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

注意：下方的 API 範例會向 Cloud Edge Management API 的網址發出要求：https://api.enterprise.apigee.com。如要安裝私有雲，請將該網址替換為 https://MS_IP:8080，其中 MS_IP 是管理伺服器的 IP 位址。

引言

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

如需 KeyStore、信任儲存庫和別名的簡介，請參閱 Keystore 和 Truststores。

建立 KeyStore

KeyStore 專屬於貴機構的環境，例如測試或實際工作環境。因此，如要先在測試環境中測試 KeyStore，再將 KeyStore 部署至實際工作環境，您必須先在這兩種環境中建立 KeyStore。

如何在環境中建立 KeyStore：

請使用本節中的 API 呼叫建立 KeyStore。
建立別名並將憑證/金鑰組上傳至別名。憑證和金鑰的上傳方式取決於憑證/金鑰組的格式。以下各節將說明如何上傳不同類型的憑證/金鑰組：
注意事項：建議您盡可能使用 PEM 格式當做金鑰和憑證。詳情請參閱「支援的憑證檔案格式」。

如要建立 KeyStore，請將 KeyStore 名稱指定為建立 KeyStore 或 Truststore API。KeyStore 名稱只能包含英數字元：

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

回應範例：

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

上傳憑證和金鑰做為 JAR 檔案

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

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

KeyStore JAR 可以只包含這三個檔案。如果您有憑證鏈結，則鏈結中的所有憑證都必須附加至單一 PEM 檔案，其中最後一個憑證應由根 CA 簽署。憑證必須按照正確順序附加至 PEM 檔案，且每個憑證之間不會有空白行，這表示：

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

在包含金鑰組和憑證的目錄中，建立名為 /META-INF 的目錄。然後在 /META-INF 中建立含有下列內容的檔案，在 /META-INF 中建立名為 describe.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

您可以使用「從 JAR 或 PKCS 檔案建立別名」API 上傳包含憑證和私密金鑰的 JAR 檔案：

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

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

在這次呼叫中，您會指定以下項目：

alias_name：識別金鑰儲存庫中的憑證和金鑰。建立虛擬主機時，您可以使用憑證的別名名稱來參照憑證和金鑰。
key_pword：私密金鑰的密碼。如果私密金鑰沒有密碼，請省略此參數。

確認 KeyStore 已正確上傳：

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

回應範例：

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

上傳憑證和金鑰做為 PEM 檔案

使用透過憑證和金鑰 PEM 檔案建立別名 API，上傳含有憑證和私密金鑰的 PEM 檔案：

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

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

在這次呼叫中，您會指定以下項目：

alias_name：識別金鑰儲存庫中的憑證和金鑰。建立虛擬主機時，您可以使用憑證的別名名稱來參照憑證和金鑰。
key_pword：私密金鑰的密碼。如果私密金鑰沒有密碼，請省略此參數。

確認 KeyStore 已正確上傳：

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

回應範例：

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

以 PKCS12/PFX 檔案格式上傳憑證和金鑰

使用「透過 JAR 或 PKCS 檔案建立別名」API 上傳內含憑證和私密金鑰的 PKCS12/PFX 檔案：

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

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

在這次呼叫中，您會指定以下項目：

alias_name：識別金鑰儲存庫中的憑證和金鑰。建立虛擬主機時，您可以使用憑證的別名名稱來參照憑證和金鑰。
key_pword：私密金鑰的密碼。如果私密金鑰沒有密碼，請省略此參數。

確認 KeyStore 已正確上傳：

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

回應範例：

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

建立及上傳自行簽署的憑證和金鑰

您可以使用產生自行簽署憑證 API 來建立別名，藉此建立自行簽署的憑證與金鑰，並上傳至別名。下列呼叫僅指定建立自行簽署憑證的必要資訊。如要加入其他資訊，您可以修改這場通話：

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

回應應如下所示：

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

建立信任儲存庫

您用於建立信任儲存庫的 API 與用來建立 KeyStore 的 API 相同。唯一的差別在於您只需將憑證檔案 (PEM 檔案) 上傳至信任儲存庫。

如果憑證屬於鏈結的一部分，您必須將鏈結中的所有憑證分別上傳至信任儲存庫，或是建立包含所有憑證的單一檔案。您必須在檔案中的每個憑證之間插入空白行。

如果您想上傳不屬於鏈結中的多個自行簽署憑證，請使用相同技巧：如果您要信任多個憑證，請將這些憑證上傳到單一檔案。

最終憑證通常是由憑證核發者簽署。舉例來說，在信任儲存庫中，您上傳用戶端憑證、client_cert_1，以及用戶端憑證核發者的憑證 (ca_cert)。

在雙向傳輸層安全標準 (TLS) 驗證期間，伺服器會在 TLS 處理程序中將 client_cert_1 傳送至用戶端，驗證成功。

此外，您也可以使用相同的憑證 (ca_cert) 來簽署第二個憑證 (client_cert_2)。但不會將 client_cert_2 上傳到 Truststore。信任儲存庫仍會包含 client_cert_1 和 ca_cert。

當伺服器在傳輸層安全標準 (TLS) 握手過程中傳遞 client_cert_2 時，要求就會成功。這是因為如果信任儲存庫中沒有 client_cert_2，但透過信任儲存庫中的憑證簽署，Edge 會允許 TLS 驗證作業成功。如果從 Truststore 移除 CA 憑證 (ca_cert)，傳輸層安全標準 (TLS) 驗證作業就會失敗。

使用您在建立 KeyStore 時使用的 API，透過建立 KeyStore 或 Truststore，在環境中建立空白的信任儲存庫：

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

建立信任存放區後，請使用透過憑證 PEM 檔案建立別名 API，將憑證以 PEM 檔案的形式上傳至信任儲存庫：

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

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

取得現有 KeyStore 或信任儲存庫的詳細資料

使用列出 KeyStores 和 Truststores API，檢查環境中是否有任何現有 KeyStore：

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

如果您是雲端客戶，無論是測試版還是實際工作環境中的機構，都能使用預設的 KeyStore。這兩種環境應會顯示此呼叫的下列結果：

[ "freetrial" ]

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

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

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

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

回應應如下所示：

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

取得別名的詳細資料

使用 ListAlias API 取得 KeyStore 的所有別名清單：

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

回應應如下所示：

[
  "alias1",
  "alias2",
  "alias3",
]

如要取得別名的所有資訊 (例如到期日和核發者)，請使用取得別名 API 並指定別名名稱：

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

回應應如下所示：

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

如要下載別名的憑證，請使用匯出別名的憑證 API：

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

回應應如下所示：

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

如果您的憑證已過期，如要更新憑證，您可以下載憑證簽署要求 (CSR)。然後將 CSR 傳送至 CA 取得新的憑證。如要產生別名的 CSR，請使用產生別名的 CSR API：

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

回應應如下所示：

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

將憑證新增至採用雙向傳輸層安全標準 (TLS) 的信任存放區

使用雙向傳輸層安全標準 (TLS) 傳入連線時 (亦即對 Edge 發出的 API 要求)，信任儲存庫會為每個可向 Edge 發出要求的用戶端建立憑證或 CA 鏈結。

一開始設定信任儲存庫時，您可以為已知的用戶端新增所有憑證。不過，經過一段時間後，當您新增用戶端時，可能會想要將其他憑證新增至信任儲存庫。

如何將新憑證新增至用於雙向傳輸層安全標準 (TLS) 的信任存放區：

請務必在虛擬主機中使用信任儲存庫的參照。
按照上方「建立信任儲存庫」一節的說明，將新憑證上傳至信任儲存庫。
更新信任儲存庫參照，將其設為「相同」值。這項更新會導致 Edge 重新載入信任存放區和新憑證。

詳情請參閱修改參考檔案。

刪除 KeyStore/truststore 或別名

刪除 KeyStore/truststore 或別名時，請務必謹慎行事。如果刪除虛擬主機、目標端點或目標伺服器正在使用的 KeyStore、信任存放區或別名，所有透過虛擬主機或目標端點/目標伺服器發出的 API 呼叫都會失敗。

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

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

詳情請參閱「更新別名中的憑證」。

刪除 KeyStore 或信任儲存庫

您可以使用刪除 KeyStore 或 Truststore API 來刪除 KeyStore 或信任儲存庫：

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

如果刪除並重新建立虛擬主機使用的 KeyStore 或信任儲存庫，就必須重新部署 API Proxy。

刪除別名

您可以使用 Delete alias API 刪除 KeyStore 或信任儲存庫中的別名：

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}