Updated on 2022-12-22 GMT+08:00

Applying for a Certificate

Function

This API is used to apply for a certificate.

URI

POST /v1/private-certificates

Request Parameters

Table 1 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token. The token can be obtained by calling the token API of IAM. The value of X-Auth-Token in the response header is the user token.

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

issuer_id

Yes

String

ID of the parent CA.

Minimum: 36

Maximum: 36

key_algorithm

Yes

String

Key algorithm. The options are as follows:

  • RSA2048: RSA algorithm with the key length of 2048 bits

  • RSA4096: RSA algorithm with the key length of 4096 bits

  • EC256: Elliptic Curve Digital Signature Algorithm (ECDSA) with the key length of 256 bits

  • EC384: Elliptic Curve Digital Signature Algorithm (ECDSA) with the key length of 384 bits

signature_algorithm

Yes

String

Signature hash algorithm. The options are as follows:

  • SHA256

  • SHA384

  • SHA512

distinguished_name

Yes

CertDistinguishedName object

Certificate name. For details, see data structure for the CertDistinguishedName field.

validity

Yes

Validity object

Certificate validity. For details, see data structure for the Validity field.

key_usages

No

Array of strings

Key usage. For details, see 4.2.1.3 in RFC 5280.

  • digitalSignature: The key is used as a digital signature.

  • nonRepudiation: The key can be used for non-repudiation.

  • keyEncipherment: The key can be used for key encryption.

  • dataEncipherment: The key can be used for data encryption.

  • keyAgreement: The key can be used for key negotiation.

  • keyCertSign: The key can issue a certificate.

  • cRLSign: The key can issue a certificate revocation list (CRL).

  • encipherOnly: The key is used only for encryption.

  • decipherOnly: The key is used only for decryption.

subject_alternative_names

No

Array of SubjectAlternativeName objects

Alternative name for the subject. For details, see data structure for the SubjectAlternativeName field.

  • Array size: [0, 20]

extended_key_usage

No

ExtendedKeyUsage object

Extended Key Usage. For details, see data structure for the ExtendedKeyUsage field.

customized_extension

No

CustomizedExtension object

Customized extension information. For details, see data structure for the CustomizedExtension field.

Table 3 CertDistinguishedName

Parameter

Mandatory

Type

Description

common_name

Yes

String

Common certificate name (CN).

Minimum: 1

Maximum: 64

country

No

String

Country code, which must comply with the regular expression "[A-Za-z]{2}".If not passed in, the value corresponding to the parent CA is inherited by default.

Minimum: 2

Maximum: 2

state

No

String

State or city name.If not passed in, the value corresponding to the parent CA is inherited by default.

Minimum: 1

Maximum: 128

locality

No

String

Country/Region.If not passed in, the value corresponding to the parent CA is inherited by default.

Minimum: 1

Maximum: 128

organization

No

String

Organization name.If not passed in, the value corresponding to the parent CA is inherited by default.

Minimum: 1

Maximum: 64

organizational_unit

No

String

Organization Unit (OU).If not passed in, the value corresponding to the parent CA is inherited by default.

Minimum: 1

Maximum: 64

Table 4 Validity

Parameter

Mandatory

Type

Description

type

Yes

String

Validity period type, which is mandatory. The options are as follows:

  • YEAR: Year (12 months)

  • MONTH: Month (31 days)

  • DAY: Day

  • HOUR: Hour

value

Yes

Integer

The certificate validity period. The value of this parameter varies depending on the value of type:

  • Root CA certificates: no longer than 30 years

  • Subordinate CA or private certificates: no longer than 20 years

start_from

No

Integer

Start time. The options are as follows:

  • The value is a timestamp in milliseconds. For example, 1645146939688 indicates 2022-02-18 09:15:39.

  • The value of start_from cannot be earlier than the result of the value of current_time minus 5 minutes.

Table 5 SubjectAlternativeName

Parameter

Mandatory

Type

Description

type

Yes

String

Type of the alternative name. Currently, only DNS, IP, DNS, and URI are allowed.

  • DNS

  • IP

  • EMAIL

  • URI

value

Yes

String

Value of the corresponding alternative name type.

  • DNS type. Length range: 0 to 253 characters

  • IP address type. Length range: 0 to 39 characters

  • EMAIL type. Length range: 0 to 256 characters

  • URI address type. Length range: 0 to 253 characters

Table 6 ExtendedKeyUsage

Parameter

Mandatory

Type

Description

server_auth

No

Boolean

Server authentication. The OID is 1.3.6.1.5.5.7.3.1.

  • true

  • false

NOTE:

Enable this enhanced key usage for the server certificate. The default value is false.

Default: false

client_auth

No

Boolean

Client authentication. The OID is 1.3.6.1.5.5.7.3.2

  • true

  • false

NOTE:

Enable this enhanced key usage for the client certificate. The default value is false.

Default: false

code_signing

No

Boolean

Signing of downloadable executable code client authentication. The OID is 1.3.6.1.5.5.7.3.3.

  • true

  • false

NOTE:

The default value is false.

Default: false

email_protection

No

Boolean

Email protection. The OID is 1.3.6.1.5.5.7.3.4.

  • true

  • false

NOTE:

The default value is false.

Default: false

time_stamping

No

Boolean

Binding the hash of an object to a time. The OID is 1.3.6.1.5.5.7.3.8

  • true

  • false

NOTE:

The default value is false.

Default: false

Table 7 CustomizedExtension

Parameter

Mandatory

Type

Description

object_identifier

No

String

Object identifier

NOTE:

The value of this parameter must be a dot-decimal notation string that complies with the ASN1 specifications, for example, 1.3.6.1.4.1.2011.4.99.

Minimum: 1

Maximum: 64

value

No

String

Custom attribute content

Minimum: 1

Maximum: 64

Response Parameters

Status code: 200

Table 8 Response body parameters

Parameter

Type

Description

certificate_id

String

ID of the certificate being issued.

Minimum: 36

Maximum: 36

Status code: 400

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Error code

Minimum: 3

Maximum: 36

error_msg

String

Error message

Minimum: 0

Maximum: 1024

Status code: 401

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Error code

Minimum: 3

Maximum: 36

error_msg

String

Error message

Minimum: 0

Maximum: 1024

Status code: 403

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Error code

Minimum: 3

Maximum: 36

error_msg

String

Error message

Minimum: 0

Maximum: 1024

Status code: 404

Table 12 Response body parameters

Parameter

Type

Description

error_code

String

Error code

Minimum: 3

Maximum: 36

error_msg

String

Error message

Minimum: 0

Maximum: 1024

Status code: 500

Table 13 Response body parameters

Parameter

Type

Description

error_code

String

Error code

Minimum: 3

Maximum: 36

error_msg

String

Error message

Minimum: 0

Maximum: 1024

Example Requests

When you use this API to apply for a certificate, a token is required in the X-Auth-Token field in the request header. The token must have the permission to access the API.

POST https://ccm.ae-ad-1.myhuaweicloud.com/v1/private-certificates

{
  "key_algorithm" : "RSA2048",
  "distinguished_name" : {
    "country" : "your country abbreviation",
    "state" : "your state",
    "locality" : "your locality",
    "organization" : "your organization",
    "organizational_unit" : "your unit",
    "common_name" : "your CN"
  },
  "subject_alternative_names" : [ {
    "type" : "IP",
    "value" : "156.127.116.38"
  } ],
  "signature_algorithm" : "SHA256",
  "validity" : {
    "type" : "YEAR",
    "value" : 3
  },
  "issuer_id" : "2cb2878b-6cd1-460d-bd25-afe655159bdc",
  "key_usages" : [ "digitalSignature", "nonRepudiation" ],
  "customized_extension" : {
    "object_identifier" : "1.3.6.1.4.1.2011.4.1",
    "value" : "This is custom extensions."
  }
}

Example Responses

Status code: 200

Request succeeded.

{
  "certificate_id" : "ae9a326a-b61e-4446-854d-cda30ffe31f5"
}

Status code: 400

Invalid request parameters.

{
  "error_code" : "PCA.XXX",
  "error_msg" : "XXX"
}

Status code: 401

Token required for the requested page.

{
  "error_code" : "PCA.XXX",
  "error_msg" : "XXX"
}

Status code: 403

Authentication failed.

{
  "error_code" : "PCA.XXX",
  "error_msg" : "XXX"
}

Status code: 404

No resources available or found.

{
  "error_code" : "PCA.XXX",
  "error_msg" : "XXX"
}

Status code: 500

Internal service error.

{
  "error_code" : "PCA.XXX",
  "error_msg" : "XXX"
}

Status Codes

Status Code

Description

200

Request succeeded.

400

Invalid request parameters.

401

Token required for the requested page.

403

Authentication failed.

404

No resources available or found.

500

Internal service error.

Error Codes

See Error Codes.