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

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

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

关于 Edge Cloud 的密钥库/信任存储区和虚拟主机

为 Edge Cloud 创建密钥库/信任存储区的过程要求您遵循有关使用虚拟主机的所有规则。例如，对于云端的虚拟主机：

  • 虚拟主机必须使用 TLS。
  • 虚拟主机只能使用端口 443。
  • 您必须使用已签名的 TLS 证书。未签名证书不可用于云端的虚拟主机。
  • TLS 证书指定的域名必须与虚拟主机的主机别名一致。

了解详情：

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

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

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

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

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

为虚拟主机或目标端点配置 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。

关于实现别名

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

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

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

  • PEM 文件的 TLS 证书 - 由证书授权机构 (CA) 签署的证书、最后一个证书由 CA 签署的证书链，或自签名证书。

Edge 提供了一个用于创建密钥库、创建别名、上传证书/密钥对和更新证书的界面和 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 文件。

证书链简介

如果证书是证书链的一部分，则您可以根据证书是在密钥库中使用还是在信任库中使用来以不同的方式处理该证书：

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

例如，您可以将所有证书合并到单个 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 时，请求会成功。这是因为，当 Truststore 中不存在 client_cert_2 但通过 Truststore 中存在的证书进行签名时，Edge 允许 TLS 验证成功。如果您从信任库中移除 CA 证书 ca_cert，则 TLS 验证会失败。

探索“TLS 密钥库”页面

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

Edge

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

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

传统 Edge (Private Cloud)

如需使用传统版 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. 将虚拟主机或目标服务器/目标端点中的引用更新为密钥库或信任库。如需了解详情，请参阅 更新 Google Cloud 的 TLS 证书。
      4. 删除该别名。注意：如果您删除别名，并且当前正由虚拟主机或目标端点使用，则虚拟主机或目标端点将发生故障。

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

您可以创建一个密钥库，以用作 TLS 密钥库或 TLS 信任库。密钥库特定于您组织中的环境，例如测试或生产环境。 因此，如果您要在将密钥库部署到生产环境之前在测试环境中对其进行测试，则必须在这两个环境中均创建它。

若要在环境中创建密钥库，您只需指定密钥库名称即可。在环境中创建已命名的密钥库后，您可以创建别名并上传证书/密钥对（密钥库）或仅将证书（信任存储区）上传到别名。

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

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

从证书创建别名（仅限 Truststore）

要从证书创建别名，请执行以下操作：

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

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

要从 JAR 文件创建别名，请执行以下操作：

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

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

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

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

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

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

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

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

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

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

  1. 访问“TLS 密钥库”页面。
  2. 将光标放到密钥库上以显示操作菜单，然后点击 +。
  3. 指定 Alias Name。
  4. 在“证书详细信息”下，从“类型”下拉列表中选择自签名证书。
  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://）、端口号或资源路径。

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

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

每个值最多 255 个字符。您可以使用英文逗号分隔各个名称，也可以在输入每个名称后按 Enter 键来分隔各个名称。

 不适用 否

测试密钥库或信任库

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

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

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

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

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

将证书添加到双向 TLS 的信任库

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

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

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

  1. 确保您在虚拟主机中使用对信任库的引用。
  2. 按照上文从证书创建别名（仅限 truststore）中的说明，将新证书上传到信任库。

  3. 更新信任库引用，将其设置为相同的值。此更新会导致 Edge 重新加载信任库和新证书。

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

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

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

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

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

删除密钥库

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

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

删除别名

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

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