您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息
本文档介绍了如何为 Edge for Private Cloud 版本 4.17.09 及更低版本创建、修改和删除密钥库和信任库。
密钥库和信任库简介
密钥库和信任库定义了用于 TLS 加密的安全证书库。这两者之间的主要区别在于它们在 TLS 握手过程中的使用位置：
- 密钥库包含 TLS 证书和私钥，用于在 TLS 握手过程中标识实体。
在单向 TLS 中，当客户端连接到服务器上的 TLS 端点时，服务器的密钥库会将服务器的证书（公共证书）提供给客户端。然后，客户端会使用证书颁发机构 (CA)（例如 Symantec 或 VeriSign）验证该证书。
在双向 TLS 中，客户端和服务器都维护一个密钥库，其中包含用于相互身份验证的各自证书和私钥。 - 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 上实现密钥库和信任库
在 Edge 上，密钥库包含一个或多个 JAR 文件，其中 JAR 文件包含：
- PEM 文件格式的 TLS 证书 - 证书授权机构 (CA) 签名的证书、最后一个证书由 CA 签名的证书链，或自签名证书。
- 以 PEM 文件形式提供的私钥。Edge 支持的密钥大小上限为 2048 位。口令是可选的。
信任库与密钥库类似，但前者仅包含 PEM 文件格式的证书，而不包含私钥。
如果证书是链的一部分，则密钥库/信任库必须包含链中的所有证书，可以是单独的 PEM 文件，也可以是单个文件。如果您使用单个文件，则证书必须按顺序排列，其中文件中的第一个证书是用于 TLS 的证书，后面依次是证书链，直到 CA 证书。您必须在文件中的每个证书之间插入一个空行。
Edge 提供了一个 API，您可以使用该 API 创建密钥库和信任库。实际的 API 是相同的。不同之处在于，创建密钥库时，您需要传递包含证书和私钥的 JAR 文件。创建信任库时，您只需以 PEM 文件形式传递证书。
证书和密钥文件的格式简介
本文档中的示例展示了定义为 PEM 文件（符合 X.509 格式）的 TLS 证书和密钥。如果您的证书或私钥不是由 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-----
获取有关现有密钥库的详细信息
使用 List Keystores and Truststores API 检查您的环境中是否存在任何现有密钥库：
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
对于云客户，系统会在测试环境和生产环境中为试用组织提供默认密钥库。您应该会看到以下针对这两个环境的调用结果：
[ "freetrial" ]
您可以使用此默认密钥库来测试 API 并将 API 推送到生产环境，但在部署到生产环境之前，您通常需要创建自己的密钥库，其中包含您自己的证书和密钥。
对于私有云客户，在您创建第一个密钥库之前，返回的数组为空。
使用 Get a Keystore or Truststore API 检查密钥库的内容。对于云客户，您应该会看到一个服务器 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 管理界面中查看此信息：
- 登录 Edge 管理界面，网址为 https://enterprise.apigee.com（云端）或
http://<ms-ip>:9000（本地），其中<ms-ip>是管理服务器节点的 IP 地址。 - 在 Edge 管理界面菜单中，依次选择管理 > TLS 证书。
获取 TLS 证书详细信息
您可以使用 Get Cert Details from a Keystore or Truststore API 查看密钥库中 TLS 证书的详细信息，例如到期日期和签发者。首先，获取您感兴趣的证书的名称。此示例会提取名为“freetrial”的密钥库的相关信息。
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="GoDaddy.com, Inc.", 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 管理界面中查看此信息：
- 登录 Edge 管理界面，网址为 https://enterprise.apigee.com（云端）或
http://<ms-ip>:9000（本地），其中<ms-ip>是管理服务器节点的 IP 地址。 - 在 Edge 管理界面菜单中，依次选择管理 > TLS 证书。
在 Edge 界面中，您可以指定 Edge 提前多久指示证书即将过期。默认情况下，界面会突出显示计划在未来 10 天内过期的任何证书。
创建密钥库
密钥库特定于组织中的某个环境，例如测试环境或生产环境。因此，如果您想在将密钥库部署到生产环境之前先在测试环境中对其进行测试，则必须在两个环境中都创建密钥库。
创建密钥库的过程分为两个步骤：
- 创建一个包含证书和私钥的 JAR 文件。
- 创建密钥库并上传 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
创建密钥库并上传 JAR 文件
如需在环境中创建密钥库，您只需向创建密钥库或信任库 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" }
在环境中创建命名密钥库后，您可以使用 将 JAR 文件上传到密钥库 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- 私钥的密码。如果私钥没有密码，请忽略此参数。
验证您的密钥库是否已正确上传：
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 与用于创建密钥库的 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 验证会失败。
使用 Create a Keystore or Truststore（您用于创建密钥库的同一 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
使用 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 文件的路径。
删除密钥库或信任库
您可以使用 删除密钥库或信任库 API 删除密钥库或信任库：
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
示例响应：
{ "certs" : [ ], "keys" : [ ], "name" : "myKeystoreName" }
如果您删除虚拟主机或目标端点/目标/服务器正在使用的密钥库或信任库，则通过虚拟主机或目标端点/目标服务器进行的所有 API 调用都会失败。