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

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

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

密钥库和信任库简介

密钥库和信任库定义了用于 TLS 加密的安全证书库。这两者之间的主要区别在于它们在 TLS 握手过程中的使用位置：

  • 密钥库包含 TLS 证书和私钥，用于在 TLS 握手过程中标识实体。

    在单向 TLS 中，当客户端连接到服务器上的 TLS 端点时，服务器的密钥库会向客户端提供服务器的证书（公钥）。然后，客户端会向证书颁发机构 (CA)（例如 Symantec 或 VeriSign）验证该证书。

    在双向 TLS 中，客户端和服务器都维护一个密钥库，其中包含用于进行相互身份验证的自己的证书和私钥。
  • 信任库包含用于验证在 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 是相同的。区别在于，创建密钥库时，您需要传递包含证书和私钥的 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

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

[ "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. 登录 Edge 管理界面：https://enterprise.apigee.com（云端）或 http://<ms-ip>:9000（本地），其中 <ms-ip> 是管理服务器节点的 IP 地址。
  2. 在 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=&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. 登录 Edge 管理界面：https://enterprise.apigee.com（云端）或 http://<ms-ip>:9000（本地），其中 <ms-ip> 是管理服务器节点的 IP 地址。
  2. 在 Edge 管理界面菜单中，依次选择管理 > 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 文件

如需在环境中创建密钥库，您只需向创建密钥库或信任库 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，但 client_cert_2 由信任库中存在的证书签名时，Edge 会允许 TLS 验证成功。如果您从信任库中移除 CA 证书 ca_cert，则 TLS 验证会失败。

使用创建密钥库或信任库（用于创建密钥库的同一 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

使用 将证书上传到信任库 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 调用都将失败。