使用 Edge 界面创建密钥库和信任库

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

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

Edge Cloud 的密钥库/信任库和虚拟主机简介

为 Edge Cloud 创建密钥库/信任库的过程中，您需要遵循有关使用虚拟主机的所有规则。例如，在 Cloud 中使用虚拟主机：

  • 虚拟主机必须使用 TLS。
  • 虚拟主机只能使用端口 443。
  • 您必须使用签名 TLS 证书。不允许将未签名的证书用于 Cloud 中的虚拟主机。
  • TLS 证书指定的域名必须与虚拟主机的主机别名匹配。

了解详情：

在 Edge 中实现密钥库和信任库

如需配置依赖于公钥基础架构的功能（例如 TLS），您需要创建包含必要密钥和数字证书的密钥库和信任库。

在 Edge 中，密钥库和信任库都由包含一个或多个别名的密钥库实体表示。也就是说，在 Edge 上，密钥库和信任库之间没有实现差异。

密钥库和信任库之间的区别源自它们包含的条目类型以及在 TLS 握手中的使用方式：

  • 密钥库 - 包含一个或多个别名的密钥库实体，其中每个别名都包含一个证书/密钥对。
  • 信任库 - 包含一个或多个别名的密钥库实体，其中每个别名仅包含一个证书。

为虚拟主机或目标端点配置 TLS 时，密钥库和信任库在 TLS 握手过程中提供不同的角色。配置虚拟主机或目标端点时，您需要在 <SSLInfo> 标记中分别指定密钥库和信任库，如以下虚拟主机示例所示：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

在此示例中，您需要指定虚拟主机用于其 TLS 密钥库的密钥库名称和别名。您可以使用引用来指定密钥库名称，以便在证书过期后进行更改。别名包含一个证书/密钥对，用于向访问虚拟主机的 TLS 客户端标识虚拟主机。在此示例中，不需要信任库。

如果需要信任库（例如，对于双向 TLS 配置），请使用 <TrustStore> 标记指定信任库：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

在此示例中，<TrustStore> 标记仅引用密钥库，而未指定特定别名。密钥库中的每个别名都包含一个证书或证书链，用于 TLS 握手流程。

支持的证书格式

格式 支持 API 和界面上传 支持北向 已验证
PEM 是 是 是
* PKCS12 是 是 是
注意：Apigee 会在内部将 PKCS12 转换为 PEM。
* DER 否 否 是
* PKCS7 否 否 否

* 建议您尽可能使用 PEM。

将 PKCS12 密钥库与 Edge for Private Cloud 4.53.00 或更高版本搭配使用

如果您使用的是 Edge for Private Cloud 4.53.00 或更高版本，则应仅使用 PKCS12 密钥库将密钥和相关证书上传到 Apigee。如需有关将现有密钥和证书转换为 PKCS12/PFX 格式的帮助，请参阅将证书转换为受支持的格式。

关于实现别名

在 Edge 上，密钥库包含一个或多个别名，其中每个别名包含：

  • TLS 证书（作为 PEM 或 PKCS12/PFX 文件）- 由证书授权机构 (CA) 签名的证书、包含由 CA 签名的最后一个证书的证书链的文件，或自签名证书。
  • 私钥（以 PEM 或 PKCS12/PFX 文件的形式）。Edge 支持的密钥大小上限为 2048 位。口令是可选的。

在 Edge 上，信任库包含一个或多个别名，其中每个别名都包含：

  • 以 PEM 文件形式提供的 TLS 证书 - 由证书授权机构 (CA) 签名的证书、由 CA 签名的最后一张证书的证书链，或自签名证书。

Edge 提供了一个界面和 API，供您创建密钥库、创建别名、上传证书/密钥对以及更新证书。用于创建信任库的界面和 API 与用于创建密钥库的界面和 API 相同。区别在于，创建信任库时，您创建的别名仅包含证书。

证书和密钥文件格式简介

您可以将证书和密钥表示为 PEM 文件或 PKCS12/PFX 文件。PEM 文件符合 X.509 格式。如果您的证书或私钥未由 PEM 文件定义，您可以使用 openssl 等实用程序将其转换为 PEM 文件。

不过，许多 .crt 文件和 .key 文件已采用 PEM 格式。如果这些文件是文本文件，并且包含在以下代码中：

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

或者：

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

这样，这些文件就与 PEM 格式兼容，您可以在密钥库或信任库中使用它们，而无需将其转换为 PEM 文件。

证书链简介

如果证书是链的一部分，则您应根据证书是在密钥库中还是在信任库中使用来处理它：

  • Keystore - 如果证书是链的一部分，则您必须创建一个包含链中所有证书的文件。证书必须按顺序排列，并且最后一个证书必须是根证书或由根证书签署的中间证书。
  • 信任库 - 如果证书是链的一部分，则您必须创建一个包含所有证书的文件，并将该文件上传到别名，或者每个证书使用一个不同的别名，将链中的所有证书单独上传到信任库。如果您将它们作为单个证书上传，则证书必须按顺序排列，并且最后一个证书必须是根证书或由根证书签名的中间证书。
  • 如果您创建一个包含多个证书的单个文件，则必须在每个证书之间插入一个空行。

例如，您可以将所有证书合并到一个 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-----

如果您的证书表示为 PKCS12/PFX 文件，您可以使用 openssl 命令根据证书链创建 PKCS12/PFX 文件，如下所示：

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

在信任库中使用证书链时，您不一定总是需要上传链中的所有证书。例如，您可以上传客户端证书 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 验证会失败。

FIPS 注意事项

如果您在启用了 FIPS 的操作系统上使用 Edge for Private Cloud 4.53.00 或更高版本，则应仅使用 PKCS12 密钥库将密钥和相关证书上传到 Apigee。

探索“TLS 密钥库”页面

访问“TLS 密钥库”页面，如下所述。

Edge

如需使用 Edge 界面访问“TLS 密钥库”页面，请执行以下操作：

  1. 以组织管理员身份登录 https://apigee.com/edge。
  2. 选择您的组织。
  3. 依次选择管理 > 环境 > TLS 密钥库。

传统边缘（私有云）

如需使用 Classic Edge 界面访问“TLS 密钥库”页面，请执行以下操作：

  1. 以组织管理员身份登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 选择您的组织。
  3. 依次选择管理 > 环境配置 > TLS 密钥库。

系统会显示“TLS 密钥库”页面：

如上图所示，您可以在“TLS 密钥库”页面上：

查看别名

如需查看别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 选择环境（通常是 prod 或 test）。
  3. 点击与您要查看的别名关联的行。

    系统会显示别名证书和密钥的详细信息。

    您可以查看别名的所有信息，包括失效日期。

  4. 使用页面顶部的按钮管理证书，以执行以下操作：
    • 将证书下载为 PEM 文件。
    • 生成 CSR。如果您的证书已过期，并且您想续期，可以下载证书签名请求 (CSR)。然后，您将 CSR 发送给 CA 以获取新证书。
    • 更新证书。注意：如果您更新了当前由虚拟主机或目标服务器/目标端点使用的证书，则必须联系 Apigee Edge 支持团队以重启路由器和消息处理器。更新证书的推荐方法是：
      1. 创建新的密钥库或信任库。
      2. 将新证书添加到新的密钥库或信任库。
      3. 更新虚拟主机或目标服务器/目标端点中对密钥库或信任库的引用。如需了解详情，请参阅 更新 Cloud 的 TLS 证书。
      4. 删除别名。注意：如果您删除了别名，而该别名当前正在被虚拟主机或目标端点使用，则虚拟主机或目标端点将会失败。

创建密钥库/信任库和别名

您可以创建一个密钥库，以用作 TLS 密钥库或 TLS 信任库。密钥库是特定于贵组织中的某个环境（例如测试环境或生产环境）的。因此，如果您想先在测试环境中测试密钥库，然后再将其部署到生产环境，则必须在这两个环境中都创建该密钥库。

如需在环境中创建密钥库，您只需指定密钥库名称即可。在环境中创建命名密钥库后，您可以创建别名，并向别名上传证书/密钥对（密钥库）或仅上传证书（信任库）。

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

  1. 访问“TLS 密钥库”页面。
  2. 选择环境（通常是 prod 或 test）。
  3. 点击 + 密钥库。
  4. 指定密钥库名称。名称只能包含字母数字字符。
  5. 点击添加密钥库。新密钥库会显示在列表中。
  6. 请使用以下任一方法添加别名。另请参阅支持的证书文件格式。

通过证书创建别名（仅限信任库）

如需根据证书创建别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 将光标悬停在密钥库上以显示操作菜单，然后点击 +。
  3. 指定别名。
  4. 在“证书详细信息”下，从“类型”下拉菜单中选择仅证书。
  5. 点击证书文件旁边的选择文件，找到包含证书的 PEM 文件，然后点击打开。
  6. 默认情况下，API 会进行检查，确保证书未过期。（可选）选择允许过期证书以跳过验证。
  7. 选择保存以上传证书并创建别名。

通过 JAR 文件创建别名（仅限密钥库）

如需根据 JAR 文件创建别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 将光标悬停在密钥库上以显示操作菜单，然后点击 +。
  3. 指定别名。
  4. 在“证书详情”下，从“类型”下拉菜单中选择 JAR 文件。
  5. 点击 JAR 文件旁边的选择文件，找到包含证书和密钥的 JAR 文件，然后点击打开。
  6. 如果密钥有密码，请指定密码。如果密钥没有密码，请将此字段留空。
  7. 默认情况下，API 会进行检查，确保证书未过期。（可选）选择允许过期证书以跳过验证。
  8. 选择保存以上传密钥和证书并创建别名。

通过证书和密钥创建别名（仅限密钥库）

如需根据证书和密钥创建别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 将光标悬停在密钥库上以显示操作菜单，然后点击 +。
  3. 指定别名。
  4. 在“证书详细信息”下，从“类型”下拉菜单中选择证书和密钥。
  5. 点击证书文件旁边的选择文件，找到包含证书的 PEM 文件，然后点击打开。
  6. 如果密钥有密码，请指定密钥密码。如果密钥没有密码，请将此字段留空。
  7. 点击密钥文件旁边的选择文件，找到包含密钥的 PEM 文件，然后点击打开。
  8. 默认情况下，API 会进行检查，确保证书未过期。（可选）选择允许过期证书以跳过验证。
  9. 选择保存以上传密钥和证书并创建别名。

通过 PKCS12/PFX 文件创建别名（仅限密钥库）

如需根据包含证书和密钥的 PKCS12 文件创建别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 将光标置于密钥库上以显示操作菜单，然后点击 +。
  3. 指定别名。
  4. 在“证书详细信息”下，从“类型”下拉菜单中选择 PKCS12/PFX。
  5. 点击 PKCS12/PFX 旁边的选择文件，找到包含密钥和证书的文件，然后点击打开。
  6. 如果密钥有密码，请为 PKCS12/PFX 文件指定密码。 如果密钥没有密码，请将此字段留空。
  7. 默认情况下，API 会进行检查，确保证书未过期。（可选）选择允许过期证书以跳过验证。
  8. 选择保存以上传文件并创建别名。

通过自签名证书创建别名（仅限密钥库）

如需创建使用自签名证书的别名，您需要填写一个表单，其中包含创建证书所需的必要信息。然后，Edge 会创建证书和私钥对，并将其上传到别名。

如需使用自签名证书创建别名，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 将光标置于密钥库上以显示操作菜单，然后点击 +。
  3. 指定别名。
  4. 在“Certificate details”（证书详情）下，从“Type”（类型）下拉菜单中选择 Self-Signed Certificate（自签名证书）。
  5. 请使用下表填写表单。
  6. 选择保存以创建证书和私钥对，并将其上传到别名。

在生成的证书中，您会看到以下额外字段：

  • 颁发者
    签署和颁发证书的实体。对于自签名证书，这是您在创建证书时指定的 CN。
  • 有效期
    证书有效期表示为两个日期：证书有效期的开始日期和证书有效期的结束日期。这两种时间戳均可编码为 UTCTime 或 GeneralizedTime 值。

下表介绍了表单字段：

表单字段 说明 默认 必填
别名名称 别名名称。长度上限为 128 个字符。 不适用 是
密钥大小 密钥的大小（以位为单位）。默认值和最大值均为 2048 位。 2048 否
签名算法 用于生成私钥的签名算法。有效值为“SHA512withRSA”“SHA384withRSA”和“SHA256withRSA”（默认）。 SHA256withRSA 否
证书有效期（天） 证书的有效期（天）。接受非零正值。 365 否
通用名称 组织的通用名称 (CN) 用于标识与证书关联的完全限定域名。它通常由主机和域名组成。 例如，api.enterprise.apigee.com、www.apigee.com 等。长度上限为 64 个字符。

根据证书类型，CN 可以是属于同一网域的一个或多个主机名（例如 example.com、www.example.com）、通配符名称（例如 *.example.com）或网域列表。请勿包含任何协议（http:// 或 https://）、端口号或资源路径。

只有当请求主机名与证书公用名中的至少一个匹配时，证书才有效。

 不适用 是
电子邮件 电子邮件地址。长度上限为 255 个字符。 不适用 否
组织部门名称 组织团队名称。长度上限为 64 个字符。 不适用 否
组织名称 组织名称。长度上限为 64 个字符。 不适用 否
市行政区 城市/城镇名称。长度上限为 128 个字符。 不适用 否
州/省 州/省名称。长度上限为 128 个字符。 不适用 否
国家/地区 由 2 个字母组成的国家/地区代码。例如，IN 代表印度，US 代表美国。 不适用 否
备用名称 备用主机名称列表。允许将其他身份绑定到证书的主题。已定义的选项包括互联网电子邮件地址、DNS 名称、IP 地址和统一资源标识符 (URI)。

每个值的字符数上限为 255 个字符。您可以使用英文逗号分隔姓名，也可以在输入每个姓名后按 Enter 键。

 不适用 否

测试密钥库或信任库

您可以在 Edge 界面中测试信任库和密钥库，以验证它们是否配置正确。测试界面会验证从 Edge 到后端服务的 TLS 请求。后端服务可以配置为支持单向或双向 TLS。

如需测试单向 TLS，请执行以下操作：

  1. 访问“TLS 密钥库”页面。
  2. 选择环境（通常是 prod 或 test）。
  3. 将光标置于要测试的 TLS 密钥库上，以显示操作菜单，然后点击测试。系统会显示以下对话框，其中显示了信任库的名称：
  4. 输入后端服务的主机名。
  5. 输入 TLS 端口号（通常为 443）。
  6. 可选择指定任何协议或加密算法。
  7. 选择测试。

如需测试双向 TLS，请执行以下操作：

  1. 对于所需的 truststore，选择 Test 按钮。
  2. 在对话框中，为 SSL 测试类型选择双向。 系统会显示以下对话框：
  3. 指定在双向 TLS 中使用的密钥库的名称。
  4. 在包含证书和密钥的密钥库中指定别名名称。
  5. 输入后端服务的主机名。
  6. 输入 TLS 端口号（通常为 443）。
  7. 可选择指定任何协议或加密算法。
  8. 选择测试。

将证书添加到信任库以实现双向 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 定义引用密钥库和信任库，则无需重新部署代理。
  4. 确认您的 API 代理正常运行。
  5. 删除密钥库/信任库或别名。

删除密钥库

如需删除密钥库或信任库，请将光标悬停在列表中的密钥库或信任库上以显示操作菜单，然后点击 。如果您删除虚拟主机或目标端点/目标服务器正在使用的密钥库或信任库，通过虚拟主机或目标端点/目标服务器进行的所有 API 调用都将失败。

注意：在将虚拟主机和目标端点/目标服务器转换为使用新密钥库之前，请勿删除密钥库。

删除别名

如需删除别名，请将光标悬停在列表中的别名上以显示操作菜单，然后点击 。如果您删除虚拟主机或目标端点/目标服务器正在使用的别名，通过虚拟主机或目标端点/目标服务器进行的所有 API 调用都将失败。

注意：在将虚拟主机和目标端点/目标服务器转换为使用新的密钥库和别名之前，请勿删除别名。