<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
本文档介绍了如何创建、修改和删除 Edge 的密钥库和信任库 适用于 Cloud 和 Edge(适用于 Private Cloud 4.18.01 及更高版本)。
关于 Edge Cloud 的密钥库/信任存储区和虚拟主机
为 Edge Cloud 创建密钥库/信任存储区的流程要求您遵循所有 关于使用虚拟主机的规则例如,对于云端的虚拟主机:
- 虚拟主机必须使用 TLS。
- 虚拟主机只能使用端口 443。
- 您必须使用已签名的 TLS 证书。未签名证书无法用于云端的虚拟主机。
- TLS 证书指定的域名必须与虚拟主机的主机别名一致。
了解详情:
在以下位置实现密钥库和信任库: 边缘
要配置依赖公钥基础架构(例如 TLS)的功能,您需要 创建包含必要密钥和数字证书的密钥库和信任库。
在 Edge 中,密钥库和信任库均由 keystore 实体表示 包含一个或多个别名的别名。也就是说, Edge 上的密钥库和信任库之间。
密钥库和信任库之间的区别在于 及其在 TLS 握手中的使用方式:
- 密钥库 - 包含一个或多个密钥的密钥库实体 aliases,其中每个别名都包含一个证书/密钥对。
- 信任库 - 包含一个或多个密钥的密钥库实体 aliases,其中每个别名仅包含一个证书。
在为虚拟主机或目标端点配置 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 签名)或自签名证书 证书。
Edge 提供了一个界面和 API,可用于创建密钥库、创建别名、上传证书/密钥 以及更新证书您用于创建信任库的界面和 API 与 用于创建密钥库。不同之处在于,在创建信任库时,您可以创建别名 仅包含一个证书
关于证书和密钥的格式 文件
您可以将证书和密钥表示为 PEM 文件或 PKCS12/PFX 文件。PEM 文件符合
X.509 格式如果您的证书或私钥未在 PEM 文件中定义,您可以将其转换为
PEM 文件。openssl
不过,许多 .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
时,请求
成功。这是因为在出现 client_cert_2
时,Edge 会允许 TLS 验证成功
不存在于信任库中,但已由信任库中存在的证书签名。如果
请先从信任库中移除 CA 证书 ca_cert
,然后再从 TLS 验证中移除
失败。
浏览“TLS 密钥库”页面
访问“TLS 密钥库”页面(如下所述)。Edge
如需使用 Edge 界面访问“TLS 密钥库”页面,请执行以下操作:
- 以组织管理员身份登录 https://apigee.com/edge。
- 选择您的组织。
- 选择管理 >环境 >TLS 密钥库。
传统 Edge(私有云)
如需使用传统 Edge 界面访问“TLS 密钥库”页面,请执行以下操作:
- 以组织管理员身份登录
http://ms-ip:9000
,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。 - 选择您的组织。
- 选择管理 >环境配置 >TLS 密钥库。
系统随即会显示“TLS 密钥库”页面:
如上图突出显示,您可以通过“TLS 密钥库”页面执行以下操作:
。查看别名
要查看别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 选择环境(通常是
prod
或test
)。 - 点击与要查看的别名相关联的行。
系统随即会显示别名证书和密钥的详细信息。
您可以查看该别名的所有相关信息,包括到期日期。 - 使用页面顶部的按钮管理证书,以便:
<ph type="x-smartling-placeholder">
- </ph>
- 将证书下载为 PEM 文件。
- 生成 CSR。如果您的证书已过期并且想要续期,您可以下载 证书签名请求 (CSR)。然后,将 CSR 发送给您的 CA,以获取新的 证书。
- 更新证书。注意:如果您更新的证书
当前正由某个虚拟主机或目标服务器/目标端点使用,那么您必须
联系 Apigee Edge 支持,以重启路由器和消息处理器。更新 Deployment 的
是:
<ph type="x-smartling-placeholder">
- </ph>
- 创建新的密钥库或信任库。
- 将新证书添加到新的密钥库或信任库。
- 更新虚拟主机中的 reference,或 目标服务器/目标端点 密钥库或信任库。请参阅 为 Cloud 更新 TLS 证书以了解详情。
- 删除别名。注意:如果您删除了某个别名, 当前被某个虚拟主机或目标端点使用,那么该虚拟主机或 目标端点都将失败。
创建密钥库/信任库和别名
您可以创建密钥库,以用作 TLS 密钥库或 TLS 信任库。密钥库 特定于您组织中的环境,例如测试或生产环境。 因此,如果您希望先在测试环境中测试密钥库,然后再将其部署到 则必须在这两种环境中都创建。
要在某个环境中创建密钥库,您只需指定密钥库名称。在您之后 在环境中创建已命名的密钥库,然后便可创建别名并上传证书/密钥对 (密钥库)或仅将证书 (truststore) 上传到别名中。
如需创建密钥库,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 选择环境(通常是
prod
或test
)。 - 点击 + 密钥库。
- 指定密钥库名称。名称只能包含字母数字字符。
- 点击添加密钥库。新密钥库随即会出现在列表中。
- 使用以下某个过程来添加别名。另请参阅 支持的证书文件格式。
从证书创建别名 (truststore) )
如需通过证书创建别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 将光标悬停在密钥库上以显示操作菜单,然后点击 +。
- 指定别名。
- 在“证书详情”下的“类型”下拉列表中选择仅证书。
- 点击证书文件旁边的选择文件,导航到 PEM 文件,然后点击打开。
- 默认情况下,API 会进行检查以确保证书未过期。根据需要选择 允许过期证书以跳过验证。
- 选择保存以上传证书并创建别名。
从 JAR 文件创建别名 (仅限密钥库)
要从 JAR 文件创建别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 将光标悬停在密钥库上以显示操作菜单,然后点击 +。
- 指定别名。
- 在“证书详情”下的“类型”下拉列表中选择 JAR 文件。
- 点击 JAR 文件旁边的选择文件,找到包含证书和密钥的 JAR 文件,然后点击打开。
- 如果密钥有密码,请指定 Password。如果密钥没有 请将此字段留空。
- 默认情况下,API 会进行检查以确保证书未过期。根据需要选择 允许过期证书以跳过验证。
- 选择保存以上传密钥和证书,并创建别名。
通过证书创建别名 密钥(仅限密钥库)
如需通过证书和密钥创建别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 将光标悬停在密钥库上以显示操作菜单,然后点击 +。
- 指定别名。
- 在“证书详细信息”下的“类型”下拉列表中选择证书和密钥。
- 点击证书文件旁边的选择文件,找到包含相应证书的 PEM 文件,然后点击打开。
- 如果密钥有密码,请指定 Key Password。如果密钥没有 请将此字段留空。
- 点击 Key File(密钥文件)旁边的 Choose File(选择文件),找到包含该密钥的 PEM 文件,然后点击 Open(打开)。
- 默认情况下,API 会进行检查以确保证书未过期。根据需要选择 允许过期证书以跳过验证。
- 选择保存以上传密钥和证书,并创建别名。
通过 PKCS12/PFX 文件(仅限密钥库)
要从包含证书和密钥的 PKCS12 文件创建别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 将光标悬停在密钥库上以显示操作菜单,然后点击 +。
- 指定别名。
- 在“证书详细信息”下的“类型”下拉列表中选择 PKCS12/PFX。
- 点击 PKCS12/PFX 旁边的选择文件,导航到 文件,然后点击打开。
- 如果密钥有密码,请为 PKCS12/PFX 文件指定 Password(密码)。 如果密钥没有密码,请将此字段留空。
- 默认情况下,API 会进行检查以确保证书未过期。根据需要选择 允许过期证书以跳过验证。
- 选择保存,以上传文件并创建别名。
通过 自签名证书(仅限密钥库)
要创建使用自签名证书的别名,您需要在表单中填写 创建证书所需的信息然后,Edge 会创建证书和私钥对 并将其上传到别名中
如需通过自签名证书创建别名,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 将光标悬停在密钥库上以显示操作菜单,然后点击 +。
- 指定别名。
- 在“证书详情”下的“类型”下拉列表中选择自签名证书。
- 使用下表填写表单。
- 选择保存以创建证书和私钥对,并将其上传到 别名。
在生成的证书中,您还会看到以下附加字段:
- 发卡机构
签署和颁发证书的实体。对于自签名证书,这是 您在创建证书时指定的 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 个字符。 | 不适用 | 否 |
国家/地区 | 由两个字母组成的国家/地区代码。例如,IN 表示印度,US 表示美国。 | 不适用 | 否 |
别称 |
备用主机名列表。允许将其他身份绑定到正文
证书 ID。定义的选项包括互联网电子邮件地址、DNS
名称、IP 地址和统一资源标识符 (URI)。
每个值最多包含 255 个字符。您可以使用英文逗号分隔名称,也可以按 然后按 Enter 键 |
不适用 | 否 |
测试密钥库或信任库
您可以在 Edge 界面中测试信任库和密钥库,以验证是否已配置它们 正确。测试界面会验证从 Edge 向后端服务发出的 TLS 请求。后端服务 可以配置为支持单向 TLS 或双向 TLS。
如需测试单向 TLS,请执行以下操作:
- 访问“TLS 密钥库”页面。
- 选择环境(通常是
prod
或test
)。 - 将光标放在要测试的 TLS 密钥库上以显示操作菜单,然后点击 Test。以下对话框
方框中显示了此信任库的名称:
- 输入后端服务的主机名。
- 输入 TLS 端口号(通常为 443)。
- (可选)指定任何协议或加密。
- 选择测试。
如需测试双向 TLS,请执行以下操作:
- 对于所需的信任库,选择测试按钮。
- 在对话框中,针对 SSL 测试类型选择双向。
系统会显示以下对话框:
- 指定在双向 TLS 中使用的密钥库的名称。
- 在密钥库中指定包含证书和密钥的别名。
- 输入后端服务的主机名。
- 输入 TLS 端口号(通常为 443)。
- (可选)指定任何协议或加密。
- 选择测试。
将证书添加到双向 TLS 信任库
为入站连接使用双向 TLS 时(即向 Edge 发出 API 请求), 对于允许向 Edge 发出请求的每个客户端,信任库都包含一个证书或 CA 链。
首次配置信任库时,您可以添加已知客户端的所有证书。 不过,随着时间的推移,您可能需要在添加新客户端时向信任库添加更多证书。
如需将新证书添加到用于双向 TLS 的信任库,请执行以下操作:
- 确保您使用的是对虚拟主机中信任库的引用。
- 按照上文中的说明向信任库上传新证书 通过证书创建别名(仅限信任库)。
更新信任库引用以将其设置为相同的值。 此更新会导致 Edge 重新加载信任库和新证书。
如需了解详情,请参阅修改引用。
删除密钥库/信任库或别名
删除密钥库/信任库或别名时必须谨慎。如果您删除密钥库 信任库或别名, 通过虚拟主机或目标端点/目标服务器进行的 API 调用将失败。
通常,用于删除密钥库/信任库或别名的流程如下:
- 按照上述说明创建新的密钥库/信任库或别名。
- 对于入站连接(即发送到 Edge 的 API 请求),请更新 虚拟主机配置来引用新密钥库和密钥别名。
- 对于出站连接,表示从 Apigee 到后端服务器:
<ph type="x-smartling-placeholder">
- </ph>
- 为引用旧 API 代理的所有 API 代理更新 TargetEndpoint 配置 密钥库和密钥别名,以引用新的密钥库和密钥别名。如果您的 TargetEndpoint 引用 TargetServer 时,请更新 TargetServer 定义以引用新的密钥库 和键别名。
- 如果密钥库和信任库直接从 TargetEndpoint 引用 定义,则必须重新部署该代理。如果 TargetEndpoint 引用 TargetServer 定义,而 TargetServer 定义引用密钥库和 信任库,则无需重新部署代理。
- 确认您的 API 代理运行正常。
- 删除密钥库/信任库或别名。
删除密钥库
您可以将光标移动到列表中的密钥库或信任库以显示相应操作,从而删除密钥库或信任库。 菜单,然后点击 。如果您删除了 通过虚拟主机或目标端点/目标服务器使用的所有 API 调用, 或目标端点/目标服务器都将出现故障。
注意:在转换密钥之前,请勿删除密钥存储区。 虚拟主机和目标端点/目标服务器以使用新的密钥库。
删除别名
您可以将光标放在列表中的别名上以显示相应操作,从而删除别名。 菜单,然后点击 。如果您删除了某个虚拟主机正在使用的别名,或 目标端点/目标服务器,通过虚拟主机或目标端点/目标进行的所有 API 调用 就会发生故障
注意:在转换虚拟别名之前,请勿删除别名。 主机和目标端点/目标服务器以使用新的密钥库和别名。