为 Private Cloud 4.17.09 及更低版本创建密钥库和信任库

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

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

密钥库和信任库简介

密钥库和信任库定义了用于 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 文件形式的证书，而不包含私钥。

如果证书是链的一部分，则密钥库/truststore 必须包含链中的所有证书（以单个 PEM 文件或单个文件的形式）。如果您使用单个文件，则证书必须按以下顺序排列：文件中的第一个证书用于 TLS 的证书，其后是证书链，按顺序指向 CA 证书。您必须在文件中的每个证书之间插入一个空行。

Edge 提供了一个用于创建密钥库和信任库的 API。实际的 API 相同。不同之处在于，在创建密钥库时，您需要传递包含证书和私钥的 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-----

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

使用 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 管理界面中查看此信息：

  1. 访问 https://enterprise.apigee.com（云端）或 http://<ms-ip>:9000（本地），登录边缘管理界面，其中 <ms-ip> 是管理服务器节点的 IP 地址。
  2. 在边缘管理界面菜单中，依次选择管理 > TLS 证书。

获取 TLS 证书详情

您可以使用 从密钥库或 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=&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 管理界面中查看此信息：

  1. 访问 https://enterprise.apigee.com（云端）或 http://<ms-ip>:9000（本地），登录边缘管理界面，其中 <ms-ip> 是管理服务器节点的 IP 地址。
  2. 在边缘管理界面菜单中，选择管理 > TLS 证书。

在 Edge 界面中，您可以指定 Edge 指示证书即将到期的到期时间。默认情况下，界面会突出显示计划在接下来的 10 天内到期的所有证书。

创建密钥库

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

创建密钥库的过程分为两个步骤：

  1. 创建包含您的证书和私钥的 JAR 文件。
  2. 创建密钥库并上传 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 文件

如需在环境中创建密钥库，您只需向 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"
}

在环境中创建已命名的密钥库后，您可以使用 将 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，客户端身份验证就会成功。

或者，您拥有由同一证书 ca_cert 签名的第二个证书 client_cert_2。但是，您不能将 client_cert_2 上传到信任库。信任库仍包含 client_cert_1 和 ca_cert。

当服务器在 TLS 握手过程中传递 client_cert_2 时，请求会成功。这是因为，当可信存储区中不存在 client_cert_2 但由信任库中存在的证书签名时，Edge 允许 TLS 验证成功。如果您从信任库中移除 CA 证书 ca_cert，则 TLS 验证将失败。

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

使用 将证书上传到 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 文件的路径。

删除密钥库或信任库

您可以使用 Delete a Keystore or Truststore 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 调用都将失败。