TLS 证书管理 API

本页 API 文档提供了 TLS 证书管理的各种操作信息，包括添加、查看，更新和删除 TLS 证书信息。

此 API 适用于 EMQX 专有版、Dedicated Flex v5 部署，以及平台账号下创建的 EMQX v4（4.4.x）部署，不支持更新 BYOC 部署的 TLS 证书。

证书输入要求

• cert 必须包含一张或多张 PEM 编码的 X.509 第 1 版或第 3 版证书。按照服务端证书在前、各级中间证书在后的签发顺序排列证书。证书链最多包含 5 张证书。
• 服务端证书必须已生效，且距离到期至少还有 5 天。
• 证书块之间只能包含空白字符。系统会拒绝额外文本、私钥块、不完整的证书块或不匹配的 PEM 标记。
• 证书及其可分辨名称（DN）必须正确编码。如果 DN 包含 countryName，其值必须是由 2 个字符组成的 PrintableString。证书序列号必须为 0 或正数。
• 不支持 MD5 签名。证书链中后接其签发证书的证书（即子证书）还不得使用 SHA-1 签名。
• 对于提交的证书链中的每一对相邻证书，子证书的签发者名称必须与下一张证书的使用者名称匹配，并且必须能够使用下一张证书的公钥验证子证书签名。
• 每张签发证书必须是 CA 证书；如果包含 Key Usage 扩展，则该扩展必须允许签发证书。
• 如果叶证书使用 EC 公钥，则支持的椭圆曲线为 P-256、P-384 和 P-521。
• key 必须是 PKCS#1 或 PKCS#8 格式的无密码 PEM 私钥，并且必须与服务端证书匹配。
• 使用双向 TLS 时必须提供 cacert。该字段可以包含一张或多张可信客户端 CA 证书，EMQX Cloud 会分别验证每张证书。这些证书无需组成有序证书链。仅服务端证书链受以下要求限制：最多包含 5 张证书，且首张证书至少剩余 5 天有效期。

API 会在保存或应用 TLS/SSL 配置前验证证书输入。如果验证失败，当前证书和配置不会发生变化。证书验证错误返回 HTTP 400，并在错误信息中指出请求字段、证书在输入中的位置（从 1 开始编号）和具体原因。

查看指定部署下 TLS 证书状态

URI

GET /deployments/{deployment_id}/tls

TIP

该方法 60 分钟只能请求 60 次。{deployment_id} 为部署 ID， 非部署名称。

请求消息

无

响应消息

• 200:

名称	类型	描述
tlsType	String	TLS 证书类型：'one-way'单向 TLS，'two-way'双向 TLS。
expire	String	证书过期时间。
status	String	TLS 证书状态：'running' 运行中，' pending'创建中。

• 401: API Key 认证失败。
• 403: API Key 没有权限访问。
• 404: 未找到部署。
• 429: 请求次数超过限制。

请求示例

curl -u key:secret -X GET {api}/deployments/ge6a1a75/tls

响应示例

{
  "expire": "2034-05-22 02:43:21",
  "status": "running",
  "tlsType": "one-way"
}

为指定部署创建 TLS 证书

URI

POST /deployments/{deployment_id}/tls

TIP

该方法 60 分钟内只能请求 6 次。{deployment_id} 为部署 ID， 非部署名称。

请求消息

名称	类型	描述
tlsType	String	TLS 证书类型：'one-way'单向 TLS，'two-way'双向 TLS。
cert	String	公钥证书
key	String	私钥
cacert	String	客户端 CA 证书，当证书类型为 'two-way' 需要上传。

响应消息

• 201:

名称	类型	描述
tlsType	String	TLS 证书类型：'one-way'单向 TLS，'two-way'双向 TLS。
expire	String	证书过期时间。
status	String	TLS 证书状态：'running' 运行中，' pending'创建中。

• 400: 证书、证书链、有效期、私钥或证书与私钥的匹配关系无效。
• 401: API Key 认证失败。
• 403: API Key 没有权限访问。
• 404: 未找到部署。
• 422: 缺少必填字段或请求属性无效。tlsType 为 two-way 时必须提供 cacert。
• 429: 请求次数超过限制。

请求示例

curl -u key:secret \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

响应示例

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

为指定部署更新 TLS 证书

URI

PUT /deployments/{deployment_id}/tls

TIP

该方法 60 分钟内只能请求 6 次。{deployment_id} 为部署 ID， 非部署名称。

请求消息

名称	类型	描述
tlsType	String	TLS 证书类型：'one-way'单向 TLS，'two-way'双向 TLS。
cert	String	公钥证书
key	String	私钥
cacert	String	客户端 CA 证书，当证书类型为 'two-way' 需要上传。

响应消息

• 200:

名称	类型	描述
tlsType	String	TLS 证书类型：'one-way'单向 TLS，'two-way'双向 TLS。
expire	String	证书过期时间。
status	String	TLS 证书状态：'running' 运行中，' pending'创建中。

• 400: 证书、证书链、有效期、私钥或证书与私钥的匹配关系无效。
• 401: API Key 认证失败。
• 403: API Key 没有权限访问。
• 404: 未找到部署。
• 422: 缺少必填字段或请求属性无效。tlsType 为 two-way 时必须提供 cacert。
• 429: 请求次数超过限制。

请求示例

curl -u key:secret \
  -X PUT \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

响应示例

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

删除指定部署的 TLS 证书

URI

DELETE /deployments/{deployment_id}/tls

TIP

该方法 60 分钟内只能请求 6 次。{deployment_id} 为部署 ID， 非部署名称。

请求消息

无

响应消息

• 204: 成功。
• 401: API Key 认证失败。
• 403: API Key 没有权限访问。
• 404: 未找到部署。
• 429: 请求次数超过限制。

请求示例

curl -u key:secret -X DELETE {api}/deployments/ge6a1a75/tls

响应示例

// HTTP status response code
204