ImportCertificate - 上传证书--证书中心-火山引擎

文档中心

立即注册

导航

ImportCertificate - 上传证书

最近更新时间：2025.01.10 11:55:43首次发布时间：2024.11.13 19:44:18

调用本接口上传一本SSL证书到证书中心。

使用说明

您可以上传一本采用SM2密钥算法的国密证书，或者上传一本采用RSA或ECC密钥算法的非国密证书。

注意事项

您上传的证书必须是有效的。证书有效表示证书未过期、未被吊销。
您必须同时上传证书文件和私钥文件。

请求说明

请求频率：同一个租户每秒最多允许请求20次。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必填	示例值	描述
Action	String	是	ImportCertificate	要执行的操作，取值：ImportCertificate。
Version	String	是	2024-10-01	API的版本，取值：2024-10-01。

Body

参数	类型	是否必填	示例值	描述
Tag	String	否	uploaded-cert	为证书设置备注。
ProjectName	String	否	default	设置证书实例所属的火山引擎项目。如果您不设置该参数，那么证书实例将归属到`default`（默认项目）。项目是火山引擎提供的一种资源管理工具。您可以使用项目对云资源进行分组，然后基于项目设置访问控制策略或查询账单。更多信息，请参见项目概述。
Repeatable	Boolean	否	true	是否允许上传相同的证书。该参数有以下取值： `false`（默认）：表示不允许上传相同的证书。证书中心会检验您上传的证书是否与证书中心已有的证书相同（基于证书指纹进行判断）。如果证书中心已存在相同的证书，那么您的证书无法上传成功，接口将返回与您的证书相同的证书的ID。（如果证书中心存在多本相同证书，则返回的是首本证书的ID。） `true`：表示允许上传相同的证书。如果您将该参数值设置为`true`，那么即使证书中心已存在相同的证书，您仍然可以上传相同的证书。
NoVerifyAndFixChain	Boolean	否	false	是否跳过证书完整性校验。该参数有以下取值： `false`（默认）：表示不跳过证书完整性校验。证书中心默认对您上传的证书进行完整性校验。完整性校验是指证书中心检查上传的证书是否包含完整的证书链，证书链中每个证书是否由下一个证书签发，以及证书是否采用了不安全的摘要算法。只有通过校验的证书才允许上传，这样能够保证被上传证书的可用性。如果证书链不完整，证书中心将会自动补全证书链。但如果签发关系不成立，或者证书采用了不安全的摘要算法，则证书将无法通过校验，不允许上传。 `true`：表示跳过证书完整性校验。如果您将该参数值设置为`true`，则证书中心将不会对上传证书的完整性进行校验。只要证书可以正确解析、证书的公钥和私钥相互匹配，就可以上传。跳过完整性校验可能导致您上传并使用有安全风险的证书，从而影响您的线上业务。正常情况下您无需设置该参数。如果需要把该参数值设置为`true`，请务必先咨询证书中心技术团队，我们将帮助您分析业务可能受到的影响。
CertificateInfo	Object	否		要上传的SSL证书（非国密证书）的详情。如果证书采用的RSA或ECC密钥算法，您需要设置该参数，无需设置`GmCertificateInfo`参数。
GmCertificateInfo	Object	否		要上传的SSL证书（国密证书）的详情。如果证书采用的SM2密钥算法，您需要设置该参数，无需设置`CertificateInfo`参数。
Tags	Array of Object	否		为证书实例绑定资源标签。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
InstanceId	String	cert-5fea76da5ec54e2999819ffc5aba****	证书中心为本次上传证书生成的实例ID。只有当证书上传成功时，该参数才有值。
RepeatId	String	cert-5fea76da5ec54e2999819ffc5aba****	在证书中心已存在的，与本次上传证书相同的首本证书的实例ID。如果请求参数`repeatable`的值被设置为`true`，则该参数固定为空值。

请求示例

POST /?Action=ImportCertificate&Version=2024-10-01 HTTP/1.1
Host: open.volcengineapi.com
Content-Type: application/json; charset=UTF-8
X-Date: 20241105T031307Z
X-Content-Sha256: 287e874e******d653b44d21e
Authorization: HMAC-SHA256 Credential=Adfks******wekfwe/20241105/cn-beijing/certificate_service/request, SignedHeaders=host;x-content-sha256;x-date, Signature=47a7d934ff7b37c03938******cd7b8278a40a1057690c401e92246a0e41085f

{
    "Tag": "uploaded-cert",
    "ProjectName": "default",
    "Repeatable": true,
    "NoVerifyAndFixChain": false,
    "CertificateInfo": {
        "CertificateChain": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n......\n-----END RSA PRIVATE KEY-----"
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2024110511135900003918523121038B",
        "Action": "ImportCertificate",
        "Version": "2024-10-01",
        "Service": "certificate_service",
        "Region": "cn-beijing"
    },
    "Result": {
        "InstanceId": "cert-5fea76da5ec54e2999819ffc5aba****",
        "RepeatId": ""
    }
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	SystemBusy	The system is busy. Please try again later.	系统繁忙，请稍后重试。
400	MalformedRequest	The request is malformed	请求参数格式不合法。
400	QuotaExceeded	%s has exceeded the quota. example: The memory size of the specified disk has exceeded the quota.	资源超出配额限制。
400	NotFound.Project	The specified project is not found	未找到指定的项目。
400	Expired.Certificate	Unable to do this operation because the certificate has expired.	不支持对过期证书进行操作。
400	Unsupported.PrivateKeyAlgorithm	The private key algorithm is not supported.	不支持的密钥算法。
400	Malformed.PrivateKey	Failed to decode private key.	私钥解析失败。
400	NotMatch.KeyPair	Failed to verify the public and private key.	公私钥不匹配。
400	NotMatch.KeyAlgorithm	The key algorithm is not matched with request	国密证书算法必须为SM2。
400	NotMatch.CertificateKeyUsage	The KeyUsage of the signature certificate chain and/or encryption certificate chain is illegal.	签名证书/加密证书的密钥用法字段不合法。
400	Malformed.Certificate	Failed to decode the certificate.	证书解析失败。
400	UnknownError.ObtainCertChain	Failed to obtain the certificate chain.	无法补全证书链。
500	InternalError	The request has failed due to an unknown error.	未知错误。