Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 Edge Management API 创建密钥库和信任库

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

本文档介绍了如何为 Edge for Cloud 和 Edge for Private Cloud 版本 4.18.01 及更高版本创建、修改和删除密钥库和信任库。

注意：以下 API 示例会向 Cloud 的 Edge 管理 API 的网址 https://api.enterprise.apigee.com 发出请求。对于 Private Cloud 安装，请将该网址替换为 https://MS_IP:8080，其中 MS_IP 是管理服务器的 IP 地址。

简介

如需配置依赖于公钥基础架构 (PKI) 的功能（例如 TLS），您需要创建提供必要密钥和数字证书的密钥库和 truststore。

如需了解密钥库、信任库和别名的简介，请参阅密钥库和信任库。

创建密钥库

密钥库特定于组织中的某个环境，例如测试环境或生产环境。因此，如果您想在将密钥库部署到生产环境之前先在测试环境中对其进行测试，则必须在两个环境中都创建密钥库。

如需在环境中创建密钥库，请执行以下操作：

使用本部分中的 API 调用创建密钥库。
创建别名，并将证书/密钥对上传到该别名。上传证书和密钥的方式取决于证书/密钥对的格式。以下各部分介绍了如何上传每种类型的证书/密钥对：
注意：我们建议尽可能使用 PEM 格式的密钥和证书。如需了解详情，请参阅支持的证书文件格式。

如需创建密钥库，请向创建密钥库或信任库 API 指定密钥库名称。密钥库名称只能包含字母数字字符：

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

密钥库 JAR 可以只包含这三个文件。如果您有证书链，则必须将链中的所有证书附加到单个 PEM 文件中，其中最后一个证书应由根 CA 签名。证书必须按正确的顺序附加到 PEM 文件中，每个证书之间用空行分隔，这意味着：

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

在包含密钥对和证书的目录中，创建一个名为 /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

您现在可以使用 Create an alias from a JAR or PKCS file 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 - 私钥的密码。如果私钥没有密码，请忽略此参数。

验证您的密钥库是否已正确上传：

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 文件形式上传证书和密钥

使用 Create an alias from certificate and key PEM files 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 - 私钥的密码。如果私钥没有密码，请忽略此参数。

验证您的密钥库是否已正确上传：

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 文件形式上传证书和密钥

使用 Create an alias from a JAR or PKCS file 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 - 私钥的密码。如果私钥没有密码，请忽略此参数。

验证您的密钥库是否已正确上传：

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"
}

创建并上传自签名证书和密钥

您可以使用 Create an alias by generating a self-signed certificate 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 与用于创建密钥库的 API 相同。唯一的区别在于，您只需将证书文件（以 PEM 文件形式）上传到信任库。

如果证书是链的一部分，则您必须将链中的所有证书单独上传到信任库，或者创建一个包含所有证书的文件。您必须在文件中的每个证书之间插入一个空行。

如果您想上传多个不属于链的自签名证书，请使用相同的技术：如果您想信任多个证书，请将它们上传到单个文件中。

最终证书通常由证书签发者签名。例如，在信任库中，您上传了客户端证书 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 时，请求会成功。这是因为，当 truststore 中不存在 client_cert_2 但存在为其签名的证书时，Edge 允许 TLS 验证成功。如果您从信任库中移除 CA 证书 ca_cert，则 TLS 验证会失败。

使用 Create a Keystore or Truststore（您用于创建密钥库的同一 API）在环境中创建一个空的信任库：

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

创建信任库后，使用 Create an alias from a certificate PEM file 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 文件的路径。

获取有关现有密钥库或信任库的详细信息

使用 List Keystores and Truststores API 检查您的环境中是否存在任何现有密钥库：

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

对于云客户，系统会在测试环境和生产环境中为试用组织提供默认密钥库。您应该会看到以下针对这两个环境的调用结果：

[ "freetrial" ]

您可以使用此默认密钥库来测试 API 并将 API 推送到生产环境，但在部署到生产环境之前，您通常需要创建自己的密钥库，其中包含您自己的证书和密钥。

对于私有云客户，在您创建第一个密钥库之前，返回的数组为空。

使用 Get a Keystore or Truststore API 检查密钥库的内容。对于云客户，您应该会看到一个服务器 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"
}

获取别名的详细信息

使用 List aliases API 获取密钥库的所有别名的列表：

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",
]

如需获取有关别名的所有信息（例如失效日期和签发者），请使用 Get alias 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，请使用 Generate a CSR for an alias 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 向信任库添加证书

如果为入站连接（即向 Edge 发出的 API 请求）使用双向 TLS，则信任库会包含允许向 Edge 发出请求的每个客户端的证书或 CA 链。

初次配置信任库时，您可以添加已知客户端的所有证书。不过，随着时间的推移，您可能会在添加新客户端时向信任库添加其他证书。

如需向用于双向 TLS 的信任库添加新证书，请执行以下操作：

确保您在虚拟主机中使用对信任库的引用。
按照上文创建信任库中的说明，将新证书上传到信任库。
更新信任库引用，将其设置为相同的值。此更新会导致 Edge 重新加载信任库和新证书。

如需了解详情，请参阅修改参考。

删除密钥库/信任库或别名

删除密钥库/信任库或别名时，您必须谨慎操作。如果您删除虚拟主机、目标端点或目标服务器正在使用的密钥库、信任库或别名，则通过虚拟主机或目标端点/目标服务器进行的所有 API 调用都会失败。

通常，您用于删除密钥库/信任库或别名的流程如下：

按照上述说明创建新的密钥库/信任库或别名。
对于入站连接（即向 Edge 发出的 API 请求），请更新虚拟主机配置以引用新的密钥库和密钥别名。
对于出站连接（即从 Apigee 到后端服务器的连接）：
1. 更新引用旧密钥库和密钥别名的所有 API 代理的 TargetEndpoint 配置，以引用新的密钥库和密钥别名。如果您的 TargetEndpoint 引用了 TargetServer，请更新 TargetServer 定义以引用新的密钥库和密钥别名。
2. 如果密钥库和信任库直接从 TargetEndpoint 定义中引用，则必须重新部署代理。如果 TargetEndpoint 引用了 TargetServer 定义，并且 TargetServer 定义引用了密钥库和信任库，则无需重新部署代理。
3. 确认您的 API 代理正常运行。
4. 删除密钥库/信任库或别名。

如需了解详情，请参阅更新别名中的证书。

删除密钥库或信任库

您可以使用删除密钥库或信任库 API 删除密钥库或信任库：

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

如果您删除并重新创建虚拟主机正在使用的密钥库或信任库，则必须重新部署 API 代理。

删除别名

您可以使用删除别名 API 删除密钥库或信任库中的别名：

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