使用 Edge Management API 创建密钥库和信任库

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

本文档介绍了如何创建、修改和删除 Edge 的密钥库和信任库 适用于 Cloud 和 Edge(适用于 Private Cloud 4.18.01 及更高版本)。

简介

要配置依赖公钥基础架构(例如 TLS)的功能,您需要 创建提供必要密钥和数字证书的密钥库和信任库。

有关密钥库、信任存储区和别名的说明,请参阅 密钥库和信任库

创建密钥库

密钥库特定于贵组织中的环境,例如测试或生产 环境因此,如果您要在部署密钥库之前在测试环境中测试密钥库, 部署到生产环境,则必须在这两种环境中创建。

如需在环境中创建密钥库,请执行以下操作:

  1. 请使用本部分中的 API 调用来创建密钥库。
  2. 创建别名并将证书/密钥对上传到该别名。上传证书和 取决于证书/密钥对的格式。以下部分介绍如何上传 每种证书/密钥对类型:

要创建密钥库,请在创建 Keystore 或 Truststore API。密钥库名称只能包含字母数字字符:

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

示例响应:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

以 JAR 文件形式上传证书和密钥

您必须先创建包含私钥、证书和清单的 JAR 文件。JAR 文件必须包含以下文件和目录:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

密钥库 JAR 可以只包含这三个文件。如果您有证书链, 链中的证书必须附加到单个 PEM 文件中,其中最后一个证书应进行签名 由根 CA 授权。证书必须以正确的顺序附加到 PEM 文件, 并在每个证书之间添加一个空行,表示:

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

在包含密钥对和证书的目录中,创建一个名为 /META-INF。然后,在 /META-INF,其中包含以下内容:

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 或 PKCS 文件创建别名 API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

其中,-F 选项指定 JAR 文件的路径。

在此调用中,您指定:

  • alias_name - 标识证书和密钥 密钥库。创建虚拟主机时,您需要通过 别名。
  • key_pword - 私钥的密码。省略 如果私钥没有密码,则此参数为此参数。

验证您的密钥库是否正确上传:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

示例响应:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

以 PEM 文件格式上传证书和密钥

使用 从证书和密钥 PEM 文件创建别名 API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

其中 -F 选项指定 PEM 文件的路径。

在此调用中,您指定:

  • alias_name - 标识证书和密钥 密钥库。创建虚拟主机时,您需要通过 别名。
  • key_pword - 私钥的密码。省略 如果私钥没有密码,则此参数为此参数。

验证您的密钥库是否正确上传:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

示例响应:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

以 PKCS12/PFX 格式上传证书和密钥 文件

使用 通过 JAR 或 PKCS 文件创建别名 API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

其中 -F 选项指定 P12 文件的路径。

在此调用中,您指定:

  • alias_name - 标识证书和密钥 密钥库。创建虚拟主机时,您需要通过 别名。
  • key_pword - 私钥的密码。省略 如果私钥没有密码,则此参数为此参数。

验证您的密钥库是否正确上传:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

示例响应:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

创建并上传自签名证书 密钥

您可以使用 通过生成自签名证书来创建别名 API 来创建自签名证书, 密钥并将其上传到别名中。以下调用仅指定 创建自签名证书。您可以修改此调用以添加其他信息:

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

响应应如下所示:

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

创建信任库

用于创建信任库的 API 与用于创建密钥库的 API 相同。通过 唯一的区别是您仅以 PEM 文件格式将证书文件上传至信任库。

如果证书是证书链的一部分,则您必须单独上传证书链中的所有证书 信任库,或创建一个包含所有证书的文件。您必须插入一个空的 每个证书之间加一行。

如果您要上传多个不属于证书链的自签名证书,请使用 方法相同:如果您想要信任多个证书,请在同一个文件中上传这些证书。

最终证书通常由证书颁发者签名。例如,在 您需要上传客户端证书 client_cert_1 和客户端证书颁发者的 即 ca_cert。

在双向 TLS 身份验证期间,当服务器发送 client_cert_1 传递给客户端。

或者,您还有一个由同一证书 ca_cert 签名的第二个证书 client_cert_2。 但是,您无法将 client_cert_2 上传到信任库。信任库仍然包含 client_cert_1 和 ca_cert。

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

使用创建 Keystore 或 Truststore,即用于创建密钥库的同一 API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

创建信任库后,请将证书以 PEM 文件格式上传到信任库,具体方法是: 使用 从证书 PEM 文件创建别名 API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

其中,-F 选项指定 PEM 文件的路径。

获取有关现有 密钥库或信任库

使用列出密钥库,检查您的环境中是否存在任何现有的密钥库 和 Truststores API:

curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

对于云客户,无论是在 测试和生产环境。对于上述两种情况,您应该都会看到此次调用的结果 环境:

[ "freetrial" ]

您可以使用此默认密钥库测试 API,并将 API 推送到生产环境, 使用您自己的证书和密钥创建自己的密钥库,然后再部署到 生产环境。

对于 Private Cloud 客户,在您创建第一个数组之前,返回的数组为空 密钥库。

使用 检查密钥库的内容 获取密钥库或信任库 API。对于云客户,您应该会看到单个服务器 TLS 证书 - Apigee Edge 为免费试用账号提供的默认证书。

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

响应应如下所示:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

获取有关别名的详细信息

使用 获取密钥库的所有别名的列表 列出别名 API:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

响应应如下所示:

[
  "alias1",
  "alias2",
  "alias3",
]

要获取关于别名的所有信息(例如到期日期和颁发者),请使用 获取别名 API 并指定别名:

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

响应应如下所示:

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

要为别名下载证书,请使用 为别名 API 导出证书

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

响应应如下所示:

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

如果您的证书已过期并想续用,可以下载证书签名 请求 (CSR)。然后,将 CSR 发送给您的 CA 以获取新的证书。要为 请使用 为别名生成 CSR API:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

响应应如下所示:

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

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

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

首次配置信任库时,您可以添加已知客户端的所有证书。 不过,随着时间的推移,您可能需要在添加新客户端时向信任库添加更多证书。

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

  1. 确保您使用的是对虚拟主机中信任库的引用。
  2. 按照上文中的说明向信任库上传新证书 创建信任库
  3. 更新信任库引用以将其设置为相同的值。 此更新会导致 Edge 重新加载信任库和新证书。

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

删除密钥库/信任库或别名

删除密钥库/信任库或别名时必须谨慎。如果您删除密钥库 信任库或别名, 通过虚拟主机或目标端点/目标服务器进行的 API 调用将失败。

通常,用于删除密钥库/信任库或别名的流程如下:

  1. 按照上述说明创建新的密钥库/信任库或别名。
  2. 对于入站连接(即发送到 Edge 的 API 请求),请更新 虚拟主机配置来引用新密钥库和密钥别名。
  3. 对于出站连接,表示从 Apigee 到后端服务器: <ph type="x-smartling-placeholder">
      </ph>
    1. 为引用旧 API 代理的所有 API 代理更新 TargetEndpoint 配置 密钥库和密钥别名,以引用新的密钥库和密钥别名。如果您的 TargetEndpoint 引用 TargetServer 时,请更新 TargetServer 定义以引用新的密钥库 和键别名。
    2. 如果密钥库和信任库直接从 TargetEndpoint 引用 定义,则必须重新部署该代理。如果 TargetEndpoint 引用 TargetServer 定义,而 TargetServer 定义引用密钥库和 信任库,则无需重新部署代理。
    3. 确认您的 API 代理运行正常。
    4. 删除密钥库/信任库或别名。

请参阅 请在别名中更新证书了解详情。

删除密钥库或信任库

您可以使用 删除密钥库或 Truststore API:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

如果您删除并重新创建虚拟主机正在使用的密钥库或信任库,则 您必须重新部署您的 API 代理。

删除别名

您可以使用 Delete alias API:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}