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

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

本文档介绍如何为适用于云端的 Edge 和适用于私有云 4.18.01 及更高版本的 Edge 创建、修改和删除密钥库和信任存储区。

简介

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

有关密钥库、信任库和别名的介绍,请参阅密钥库和信任库

创建密钥库

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

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

  1. 使用本部分中的 API 调用来创建密钥库。
  2. 创建别名并将证书/密钥对上传到别名。上传证书和密钥的方式取决于证书/密钥对的格式。以下部分介绍了如何上传每种类型的证书/密钥对:

如需创建密钥库,请向 Create a Keystore or Truststore 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

现在,您可以使用 从 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 - 私钥的密码。如果私钥没有密码,请省略此参数。

验证密钥库是否已正确上传:

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 - 私钥的密码。如果私钥没有密码,请省略此参数。

验证密钥库是否已正确上传:

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 - 私钥的密码。如果私钥没有密码,请省略此参数。

验证密钥库是否已正确上传:

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 与创建密钥库的 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 时,请求会成功。这是因为,当 Truststore 中不存在 client_cert_2 但由 Truststore 中存在的证书签名时,Edge 允许 TLS 验证成功。如果您从信任库中移除 CA 证书 ca_cert,则 TLS 验证会失败。

使用创建密钥库或 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

创建信任库后,使用 从证书 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 文件的路径。

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

使用 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 电子邮件别名 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,请使用 为别名生成 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 的信任库

入站连接(即发送到 Edge 的 API 请求)使用双向 TLS 时,对于允许向 Edge 发出请求的每个客户端,信任库都会包含一个证书或 CA 链。

最初配置信任库时,您可以添加已知客户端的所有证书。但随着时间推移,在添加新客户端时,您可能希望向信任库添加其他证书。

如需将新证书添加到用于双向 TLS 的信任库,请执行以下操作:

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

    如需了解详情,请参阅修改引用

删除密钥库/受信任证书存储区或别名

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

通常,用于删除密钥库/信任库或别名的过程如下:

  1. 按照上文所述创建新的密钥库/受信任证书存储区或别名。
  2. 对于入站连接(即向 Edge 发出 API 请求),请更新虚拟主机配置以引用新的密钥库和密钥别名。
  3. 对于出站连接,即从 Apigee 到后端服务器:
    1. 更新引用旧密钥库和密钥别名的任何 API 代理的 TargetEndpoint 配置,以引用新的密钥库和密钥别名。如果您的 TargetEndpoint 引用了 TargetServer,请更新 TargetServer 定义以引用新的密钥库和密钥别名。
    2. 如果直接从 TargetEndpoint 定义引用密钥库和信任库,您必须重新部署代理。如果 TargetEndpoint 引用 TargetServer 定义,并且 TargetServer 定义引用 Keystore 和 Truststore,则不需要重新部署代理。
    3. 确认您的 API 代理运行正常。
    4. 删除密钥库/信任库或别名。

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

删除密钥库或信任库

您可以使用 删除 Keystore 或 Truststore API 来删除 Keystore 或 Truststore:

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

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

删除别名

您可以使用 Delete alias API 来删除密钥库或信任库中的别名:

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