CreateCustomCertificate

Updated at:

Issues a digital certificate with the specified subject name, subject alternative names, key usages, and extended key usages. Before you call this API operation, if the SUB_ROOT CA specified by ParentIdentifier is newly created, you must first call AssignCertificateCount (set the CaIdentifier parameter to the value of ParentIdentifier) to allocate a certificate quota (CertTotalCount) for the CA. Otherwise, the QuotaExceeded error is returned.

Operation description

Before you call this API operation, if the SUB_ROOT CA specified by ParentIdentifier is newly created, you must first call AssignCertificateCount (set the CaIdentifier parameter to the value of ParentIdentifier) to allocate a certificate quota (CertTotalCount) for the CA. Otherwise, the QuotaExceeded error is returned.

By default, the certificate subject name is obtained from the CSR to issue the certificate. If a certificate subject name is specified, the certificate subject name in the CSR becomes invalid, and the specified certificate subject name is used to issue the certificate.

You must specify key usages or extension key usages based on common scenarios. The following examples show common scenarios:

  • Server authentication certificate.

Key usages: digitalSignature and keyEncipherment.

Extended key usage: serverAuth.

  • Client authentication certificate.

Key usages: digitalSignature and keyEncipherment.

Extended key usage: clientAuth.

  • mTLS mutual authentication certificate.

Key usages: digitalSignature and keyEncipherment.

Extended key usages: serverAuth and clientAuth.

  • Email signing certificate.

Key usages: digitalSignature and contentCommitment.

Extended key usage: emailProtection.

Note: Compliance CAs are managed by third-party authorities and do not support this API operation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-cert:CreateCustomCertificate

create

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

ParentIdentifier

string

Yes

The CA certificate identifier. This parameter must point to a SUB_ROOT (end-entity) CA. If a ROOT CA is used, the API operation returns OperationDenied.NotSupport.

1ed4068c-6f1b-6deb-8e32-3f8439a851cb

Csr

string

Yes

The CSR content. You can generate a CSR by using the OpenSSL or Keytool tool. For more information, see How to create a CSR file.

-----BEGIN CERTIFICATE REQUEST----- MIIBczCCARgCAQAwgYoxFDASBgNVBAMMC2FsaXl1bi50ZXN0MQ0wCwYDVQQ ... ... ... vbIgMQIhAKHDWD6/WAMbtezAt4bysJ/BZIDz1jPWuUR5GV4TJ/mS -----END CERTIFICATE REQUEST-----

Validity

string

Yes

The certificate validity period. The validity period cannot exceed the instance validity period. Both relative time and absolute time are supported.

Relative time: The supported units are year, month, and day.

  • Year: y

  • Month: m

  • Day: d

Absolute time: GMT time is used. Format: yyyy-MM-dd'T'HH:mm:ss'Z'

  • Specify the end time: $NotAfter

  • Specify the start time and end time: $NotBefore/$NotAfter

Relative time: ● 1y ● 3m ● 7d Absolute time: ● 2006-01-02T15:04:05Z ● 2006-01-02T15:04:05Z/2023-03-09T17:48:13Z

ApiPassthrough

object

No

The pass-through parameter. Call example: { "apiPassthrough": { "extensions": { "keyUsage": { "digitalSignature": true, "keyEncipherment": true }, "extendedKeyUsages": ["serverAuth", "clientAuth"], "subjectAlternativeNames": [ {"type": "dNSName", "value": "www.example.com"}, {"type": "dNSName", "value": "example.com"}, {"type": "iPAddress", "value": "192.168.1.1"} ], "criticals": ["ExtendedKeyUsages"] } } }

Subject

object

No

The certificate subject name.

Country

string

No

The country code. Use the two-letter country code defined in ISO 3166-1. For more information, see ISO.

CN

State

string

No

The name of the province, municipality, or autonomous region where the organization associated with the CA certificate is located.

Zhejiang Province

Locality

string

No

The name of the city where the organization is located. Chinese and English characters are supported.

Hangzhou

Organization

string

No

The organization name.

XXX Company

OrganizationUnit

string

No

The name of the department or branch under the organization.

XXX Department

CommonName

string

No

The common name of the certificate subject.

Zhang San

CustomAttributes

array<object>

No

The subject property of the custom certificate.

object

No

The subject property of the custom certificate.

ObjectIdentifier

string

No

The custom attribute key, which must comply with industry standards. Examples:

  • 2.5.4.6: Country code

  • 2.5.4.10: Organization

  • 2.5.4.11: Organizational unit name

  • 2.5.4.12: Title

  • 2.5.4.3: Common name

  • 2.5.4.9: Street

  • 2.5.4.5: Serial number

  • 2.5.4.7: Locality

  • 2.5.4.8: State or province

  • 1.3.6.1.4.1.37244.1.1: Matter certificate - Node ID

  • 1.3.6.1.4.1.37244.1.5: Matter certificate - Fabric ID

  • 1.3.6.1.4.1.37244.2.1: Matter certificate Vendor ID (VID)

  • 1.3.6.1.4.1.37244.2.2: Matter certificate Product ID (PID)

2.5.4.3

Value

string

No

The custom attribute value.

Aliyun

Extensions

object

No

The certificate extensions.

KeyUsage

object

No

The key usage.

DigitalSignature

boolean

No

Digital signature. Allows the certificate private key to be used for digital signatures and the certificate public key to be used to verify digital signatures.

true

ContentCommitment

boolean

No

Content commitment (non-repudiation). Originally named NonRepudiation. Allows the certificate key to be used for content commitment.

false

NonRepudiation

boolean

No

Non-repudiation (equivalent to contentCommitment). Renamed to ContentCommitment in the X.509 standard.

false

KeyEncipherment

boolean

No

Secret key encryption. Allows the certificate key to encrypt and protect other keys.

false

DataEncipherment

boolean

No

Data encryption. Used to encrypt data.

false

KeyAgreement

boolean

No

Key agreement.

false

EncipherOnly

boolean

No

When KeyAgreement is true, used to mark that the certificate key can only be used for encryption.

false

DecipherOnly

boolean

No

When KeyAgreement is true, used to mark that the certificate key can only be used for decryption.

false

ExtendedKeyUsages

array

No

The extended key usages. Type: List. The following predefined names and custom OIDs are supported:

string

No

Valid values:

  • any: No restrictions.

  • serverAuth: Server authentication.

  • clientAuth: Client authentication.

  • codeSigning: Code signing.

  • emailProtection: Email protection.

  • timeStamping: Time stamping.

  • OCSPSigning: OCSP signing.

  • Other extended key usage OIDs: Parsed as custom OIDs, such as "1.3.6.1.5.5.7.3.9".

1.3.6.1.4.1.311.20.2.2

SubjectAlternativeNames

array<object>

No

The subject alternative names (SANs). Type: List<Extensions.SubjectAlternativeName>. Each item contains type (GeneralNameType enum) and value (string).

object

No

The subject alternative name of the certificate.

Type

string

Yes

Valid values:

  • otherName: A value starting with # indicates hex-encoded ASN1; otherwise, it is a UTF8String.

  • rfc822Name: Email address.

  • dNSName: Domain name.

  • directoryName: X.500 DN.

  • uniformResourceIdentifier: Uniform Resource Identifier (URI).

  • iPAddress: IP address.

  • registeredID: OID.

dNSName

Value

string

No

The value that conforms to the Type definition.

  • otherName: A value starting with # indicates hex-encoded ASN1; otherwise, it is a UTF8String. Special processing for otherName: If the value starts with #, remove # and hex-decode it into an ASN1 structure (ASN1Primitive.fromByteArray). Otherwise, wrap it as DERUTF8String.

  • rfc822Name: Email address, such as user@example.com.

  • dNSName: Domain name, such as www.example.com.

  • directoryName: X.500 DN, such as CN=Test,O=Org.

  • uniformResourceIdentifier: URI, such as https://example.com.

  • iPAddress: IP address, such as 192.168.1.1.

  • registeredID: OID, such as 1.2.3.4.

rfc822Name: example.aliyundoc.com dNSName: learn.aliyundoc.com uniformResourceIdentifier: acs:ecs:regionid:15619224785*****:instance/i-bp1bzvz55uz27hf***** iPAddress: 127.0.0.1

Criticals

array

No

Controls the critical flag of the extension. If a parameter is required, the criticals list includes the parameter name.

string

No

The parameter name of the required parameter, such as ExtendedKeyUsages.

ExtendedKeyUsages

SerialNumber

string

No

The serial number of the custom certificate (must be a long integer).

16889526086333

Immediately

integer

No

Specifies whether to obtain the certificate immediately. Valid values:

  • 0: Issues the certificate asynchronously.

  • 1: Issues the certificate immediately.

  • 2: Issues the certificate immediately and returns the CA certificate chain.

0

EnableCrl

integer

No

Specifies whether to include the CRL address. Valid values:

  • 0: No.

  • 1: Yes.

1

Tags

array<object>

No

The list of tags.

object

No

The list of tags.

Key

string

No

The tag key.

testKey

Value

string

No

The tag value.

1

ResourceGroupId

string

No

The resource group ID. You can obtain this ID by calling the ListResources API operation.

rg-aek****wia

customIdentifier

string

No

The user-defined identifier.

XXX068c-6f1b-6deb-8e32-3f8439a8XXX

Response elements

Element

Type

Description

Example

object

OpenApiResponseV1

Identifier

string

The unique identifier of the certificate.

160ae6bb538d538c70c01f81dcf2****

Certificate

string

The certificate content. Returned when Immediately is 1 or 2.

-----BEGIN CERTIFICATE----- MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/ ... ... ... KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg== -----END CERTIFICATE-----

CertificateChain

string

The CA certificate chain. Returned when Immediately is 2.

-----BEGIN CERTIFICATE----- MIIBfzCCATGgAwIBAgIUfI5kSdcO2S0+LkpdL3b2VUJG10YwBQYDK2VwMDUxCzAJ ... ... ... ZYYG -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIBczCCARgCAQAwgYoxFDASBgNVBAMMC2FsaXl1bi50ZXN0MQ0wCwYDVQQ ... ... ... KL5cUmF -----END CERTIFICATE-----

SerialNumber

string

The certificate serial number. Returned when Immediately is 1 or 2.

084bde9cd233f0ddae33adc438cfbbbd****

RequestId

string

The ID of the request. It is a unique identifier generated by Alibaba Cloud for the request and can be used for troubleshooting.

12345678-1234-1234-1234-123456789ABC

Examples

Success response

JSON format

{
  "Identifier": "160ae6bb538d538c70c01f81dcf2****",
  "Certificate": "-----BEGIN CERTIFICATE-----\nMIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/\n...\n...\n...\nKOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==\n-----END CERTIFICATE-----",
  "CertificateChain": "-----BEGIN CERTIFICATE-----\nMIIBfzCCATGgAwIBAgIUfI5kSdcO2S0+LkpdL3b2VUJG10YwBQYDK2VwMDUxCzAJ\n...\n...\n...\nZYYG\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIBczCCARgCAQAwgYoxFDASBgNVBAMMC2FsaXl1bi50ZXN0MQ0wCwYDVQQ\n...\n...\n...\nKL5cUmF\n-----END CERTIFICATE-----",
  "SerialNumber": "084bde9cd233f0ddae33adc438cfbbbd****",
  "RequestId": "12345678-1234-1234-1234-123456789ABC"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.