Request

Endpoint: !DecodeCSR

http(s)://trust-provider.com/products/!DecodeCSR

For GET requests, submit parameters in the query string.

For POST requests, submit parameters in application/x-www-form-urlencoded format. POST method is recommended when submitting large CSRs.

https://secure.sectigo.com/utilities/decodeCSR.html is a demonstration of the DecodeCSR API and can be used in browsers that support XMLHttpRequest.

Request parameters

The following table displays the required, optional, and conditional parameters.

Parameter Requirement Type Max.Length Description

csr

required

string

32767 chars

The Base64-encoded certificate signing request (CSR), with or without the -----BEGIN xxxxx----- and -----END xxxxx----- header and footer.

For more information, see CSR structure.

responseFormat

optional

integer

Specifies the format of the returned certificate data.

The allowed values are:

  • 0 — UTF-8 text

  • 1 — XML

  • 2 — JSON

If omitted, the value defaults to 0.

showErrorCodes

optional

char

1 char

Specifies whether error codes should be included in the response.

The allowed values are:

  • Y — Include error codes.

  • N — Do not include error codes.

If omitted, the value defaults to Y.

showErrorMessages

optional

char

1 char

Specifies whether error messages should be included in the response.

The allowed values are:

  • Y — Include error messages.

  • N — Do not include error messages.

If omitted, the value defaults to Y.

showFieldNames

optional

char

1 char

Specifies whether field names should be included in the response.

The allowed values are:

  • Y — Include field names.

  • N — Do not include field names.

If omitted, the value defaults to Y.

showEmptyFields

optional

char

1 char

Specifies whether empty fields should be included in the response.

The allowed values are:

  • Y — Include empty fields.

  • N — Do not include empty fields.

If omitted, the value defaults to Y.

showCN

optional

char

1 char

Specifies whether the Common Name (CN) should be included in the response.

The allowed values are:

  • Y — Include the Common Name.

  • N — Do not include the Common Name.

If omitted, the value defaults to Y.

showAddress

optional

char

1 char

Specifies whether the address field should be included in the response.

The allowed values are:

  • Y — Include the address.

  • N — Do not include the address.

If omitted, the value defaults to Y.

showPublicKey

optional

char

1 char

Specifies whether the public key should be included in the response.

The allowed values are:

  • Y — Include the public key.

  • N — Do not include the public key.

If omitted, the value defaults to N.

showKeySize

optional

char

1 char

Specifies whether the key size should be included in the response.

The allowed values are:

  • Y — Include the key size.

  • N — Do not include the key size.

If omitted, the value defaults to N.

showSANDNSNames

optional

char

1 char

(Multi-Domain SSL and Unified Communications certificates only) Specifies whether the Subject Alternative Name (SAN) DNS names should be included in the response.

The allowed values are:

  • Y — Include the SAN DNS names.

  • N — Do not include the SAN DNS names.

If omitted, the value defaults to N.

showCSR

optional

char

1 char

Specifies whether the original CSR should be included in the response.

The allowed values are:

  • Y — Include the original CSR.

  • N — Do not include the original CSR.

If omitted, the value defaults to N.

showCSRHashes

optional

char

1 char

Specifies whether the CSR hashes should be included in the response.

The allowed values are:

  • Y — Include the CSR hashes.

  • N — Do not include the CSR hashes.

If omitted, the value defaults to N.

showCSRHashes2

optional

char

1 char

Specifies whether additional CSR hashes should be included in the response.

The allowed values are:

  • Y — Include the additional CSR hashes.

  • N — Do not include the additional CSR hashes.

If omitted, the value defaults to N.

showSignatureAlgorithm

optional

char

1 char

Specifies whether the signature algorithm should be included in the response.

The allowed values are:

  • Y — Include the signature algorithm.

  • N — Do not include the signature algorithm.

If omitted, the value defaults to N.

product

optional

integer

Specifies the product for which this CSR will be used.

The allowed values for DV SSL certificates are:

  • 488 — SectigoSSL DV

  • 489 — SectigoSSL Wildcard DV

  • 492 — SectigoSSL SSL Unified Communications certificate DV

The allowed values for EV SSL certificates are:

  • 337 — SectigoSSL EV certificate

  • 338 — EV SGC SSL certificate

  • 410 — SectigoSSL EV Multi-Domain EV certificate

The allowed values for OV SSL certificates are:

  • 43 — Trial SSL certificate

  • 44 — Intranet SSL certificate

  • 24 — InstantSSL certificate

  • 34 — InstantSSL Pro certificate

  • 7 — PremiumSSL Certificate

  • 35 — PremiumSSL Wildcard certificate

  • 316 — PremiumSSL Legacy certificate

  • 322 — PremiumSSL Legacy Wildcard certificate

  • 317 — SGC SSL certificate

  • 323 — SGC SSL Wildcard certificate

  • 62 — EliteSSL certificate

  • 63 — GoldSSL certificate

  • 64 — PlatinumSSL certificate

  • 65 — PlatinumSSL Wildcard certificate

  • 318 — PlatinumSSL Legacy certificate

  • 324 — PlatinumSSL Legacy Wildcard certificate

  • 319 — PlatinumSSL SGC certificate

  • 325 — PlatinumSSL SGC Wildcard certificate

  • 335 — Multi-Domain SSL certificate

  • 361 — Unified Communications certificate

The allowed values for AMT SSL certificates are:

  • 510 — AMT SSL certificate

  • 511 — AMT SSL Wildcard certificate

  • 512 — AMT SSL Multi-Domain certificate

If omitted, product-specific checks are not performed.

countryNameType

optional

string

7 chars

Specifies the format of the country name in the CSR.

The allowed values are:

  • TWOCHAR — Two-character country code.

  • FULLNAME — Full country name.

If omitted, the value defaults to TWOCHAR.

Sample request

curl --location 'https://secure.trust-provider.com/products/!DecodeCSR' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'csr=-----BEGIN CERTIFICATE REQUEST-----
MIIC9TCCAd0CAQAwbTEdMBsGA1UEAwwUc2VjdGlnb3Rlc3RjZXJ0cy5jb20xCzAJ
...
aPcCpvDcXSYT9L6tCj7R3Cqhoxj/oxABfjym9PuZXBPvn90CVfrkLZs=
-----END CERTIFICATE REQUEST-----
' \
--data-urlencode 'showErrorCodes=Y' \
--data-urlencode 'showErrorMessages=Y' \
--data-urlencode 'showSignatureAlgorithm=Y' \
--data-urlencode 'showCSRHashes=Y' \
--data-urlencode 'showCSRHashes2=Y' \
--data-urlencode 'showKeySize=Y'

Response

The request is successful when the server returns a response with the status code equals 0.

Any status code less than 0 indicates an error condition.

The MIME type of the response is text/plain when the responseFormat request parameter is set to 0 or is omitted.

The following is the format of the response, assuming that all of the showXXXXXXX request parameters are set to Y.

Line Possible Value(s)

Number of error codes/messages

0, 1, 2, etc

Error code and error message

For more information, see Error codes.

Common Name

CN=xxxxx

Organizational unit name

OU=xxxxx

Organization name

O=xxxxx

Post office box

POBox=xxxxx

Street address 1

STREET=xxxxx

Street address 2

STREET=xxxxx

Street address 3

STREET=xxxxx

Locality name

L=xxxxx

State or province name

S=xxxxx

Postal code

PostalCode=xxxxx

Country name

C=xxxxx

Email address

Email=xxxxx

Telephone number

Phone=xxxxx

Public key

Public Key=xxxxx

Key size (in bits)

Key Size=xxxxx

Subject alternative name dnsName(s)

dnsName(s)=xxxxx,yyyy,zzzzz,etc

MD5 Hash of DER-encoded CSR

md5=xxxxx

SHA-1 Hash of DER-encoded CSR

sha1=xxxxx

SHA-256 Hash of DER-encoded CSR

sha256=xxxxx

CSR signature algorithm

sigalg=xxxxx

<Blank Line>

CSR (multiple lines)

The CSR request variable, except:

  • Any characters before the -----BEGIN header (if present) are removed.

  • Leading and trailing spaces are removed.

Each error code and error message line is of the format <Error Code><SPACE><Error Message>, depending on the values of showErrorCodes and showErrorMessages.

If multiple error codes or messages are present, each appears on a separate line.

The response can be formatted in one of the following ways:

  • If showErrorCodes=N and showErrorMessages=N, the 'Number of Error Codes/Messages' line is completely omitted from the response.

  • If showErrorCodes=N, the error code portions of the error code and error message x lines are completely omitted from the response.

  • If showErrorMessages=N, the error message portions of the error code and error message x lines are completely omitted from the response.

  • If showFieldNames=N, the lines from Common Name to public key only contain 'xxxxx'. Accordingly, CN=, OU=, O= and others are omitted.

  • If showEmptyFields=N, any lines from Common Name to telephone number are completely omitted where 'xxxxx' is empty.

  • If showFieldNames=N and showEmptyFields=N, it will be very difficult to determine which line in the response relates to which of the attributes from Common Name to the public key.

  • If showCN=N, the Common Name line is completely omitted.

  • If showAddress=N, the lines from the organizational unit name to the telephone number are completely omitted.

  • If showPublicKey=N, the public key line is completely omitted.

  • If showKeySize=N, the key size line is completely omitted.

  • If showSANDNSNames=N, the Subject Alternative Name dnsName(s) line is completely omitted.

  • If showCSRHashes and showCSRHashes2 are both N, the md5 and sha1 lines are completely omitted.

  • If showCSRHashes2=N, the SHA256 line is completely omitted.

  • If showSignatureAlgorithm=N, the sigalg line is completely omitted.

  • If showCSR=N, the <Blank Line> and CSR line(s) are completely omitted.

  • If countryNameType is TWOCHAR, 'xxxxx' in the C=xxxxx line will use the ISO-3166 two character country code.

  • If countryNameType=FULL, 'xxxxx' in the C=xxxxx line will use the ISO-3166 full country name.

Sample successful response

0
CN=sectigotestcerts.com
OU=
O=Sectigo Limited
POBox=
STREET=
STREET=
STREET=
L=Manchester
S=Salford
PostalCode=
C=GB
Email=
Phone=
Public Key=3082010A028...0203010001
Key Size=2048
md5=123456789...12345AE
sha1=1234567890X60...12345AE
sha256=123456789...1CCE6576D98DD1
sigalg=sha256WithRSAEncryption

Sample error response

1
-3 The "csr" argument is missing!
CN=
OU=
O=
POBox=
STREET=
STREET=
STREET=
L=
S=
PostalCode=
C=
Email=
Phone=

Error codes

The following table outlines error responses returned by the DecodeCSR API endpoint. Each error response consists of an errorCode and an errorMessage indicating why the request failed.

Error Code Error Message Description

-1

Request was not made over https and 'showCSRHashes=Y' was specified!

The request must use HTTPS protocol.

-2

'xxxxx' is an unrecognised argument!

The provided argument is not recognised.

-3

The 'xxxxx' argument is missing!

A required argument is missing from the request.

-4

The value of the 'xxxxx' argument is invalid!

The argument value does not meet validation requirements.

-5

The Common Name (Domain Name) may not contain a *

The Common Name field contains an invalid wildcard character.

-6

The Common Name (Domain Name) must contain ONE *

The Common Name field must contain exactly one wildcard character.

-7

'xxx' is not a valid ISO-3166 country code!

The provided country code is not valid.

-8

The CSR is missing a required field!

The CSR does not include all required fields.

-10

The CSR cannot be decoded!

The CSR could not be parsed.

-11

The CSR uses an unsupported algorithm!

The algorithm used in the CSR is not supported.

-12

The CSR has an invalid signature!

The signature on the CSR is invalid.

-13

The CSR uses an unsupported key size!

The key size in the CSR is not supported.

-14

An unknown error occurred!

An unknown error occurred.

-18

The Common Name (Server Name) may not be a Fully-Qualified Domain Name!

The Common Name field can’t be a fully qualified domain name.

-19

The Common Name (Server Name) may not be an Internet-accessible IP Address!

The Common Name field can’t be an IP address.

-23

The Common Name (Domain Name) should not include the http:// part!

The Common Name (Domain Name) can’t include the http:// part!

-24

The Common Name (Domain Name) should not include the https:// part!

The Common Name (Domain Name) should not include the https:// prefix.

-25

The Common Name (Domain Name) may only contain the following characters: A..Z a..z 0..9 . -

The Common Name (Domain Name) contains invalid characters.

-40

The CSR uses a key that is believed to have been compromised!

The CSR’s key is on a compromised keys list.

-41

The CSR uses an invalid key!

The CSR’s key is invalid.

Additional request structures

CSR structure

A CSR contains a version field and a subject field.

The version field specifies the CSR format.

In PKCS#10, the CSR version is always 0.

The following table describes the fields included in the CSR’s subject.

The fields in the subject may appear in any order.

Ensure that multiple street addresses are in the correct order, if present.
OID Description Supported ASN.1 Type(s) Max. Length

Required fields

2.5.4.3

The Common Name.

It must contain the fully qualified domain name (FQDN).

DirectoryString

64 chars

Optional fields

2.5.4.10

The organization name.

DirectoryString

64 chars

2.5.4.11

The organizational unit name.

DirectoryString

64 chars

2.5.4.18

The post office box.

DirectoryString

40 chars

2.5.4.9

The street address 1.

DirectoryString

128 chars

2.5.4.9

The street address 2.

DirectoryString

128 chars

2.5.4.9

The street address 3.

DirectoryString

128 chars

2.5.4.7

The locality name.

DirectoryString

128 chars

2.5.4.8

The state or province name.

DirectoryString

128 chars

2.5.4.17

The postal code.

DirectoryString

40 chars

2.5.4.6

The ISO-3166 two-character code of the country name.

PrintableString

2 chars

DirectoryString is a choice of PrintableString, TeletexString, BMPString, UniversalString (ASCII only) or UTF8String.
Any other fields are optional and may be present, but they will be ignored.

The Subject Public Key Info field contains the following data:

  • RSA: OID — rsaEncryption (PKCS#1). The size is 2048 to 8192 bits.

  • ECC: OID — id-ecPublicKey (RFC3279). Curve: P-256, P-384 or P-521.

Any attributes are optional and may be present, but they will be ignored.

The possible values for Signature Algorithm are:

  • md5WithRSAEncryption (PKCS#1)

  • sha1WithRSAEncryption (PKCS#1)

  • sha224WithRSAEncryption (PKCS#1)

  • sha256WithRSAEncryption (PKCS#1)

  • sha384WithRSAEncryption (PKCS#1)

  • sha512WithRSAEncryption (PKCS#1)

  • ecdsa-with-SHA1 (RFC3279)

  • ecdsa-with-SHA224 (RFC5758)

  • ecdsa-with-SHA256 (RFC5758)

  • ecdsa-with-SHA384 (RFC5758)

  • ecdsa-with-SHA512 (RFC5758)