Order a new certificate
This section will cover the steps necessary to create a Stir/Shaken certificate.
Certificate private key
A private key for the certificate must be created using EC P-256 algorithm. This can be done using OpenSSL library for the selected programming language, or using the CLI tool:
openssl ecparam -genkey -name prime256v1 -out ./private_key.pemACME server does not support other encryption algorithms, as well as other types of Elliptic Curves.
TNAuthList
Every STIR/SHAKEN SP certificate must include a TNAuthList extension (OID 1.3.6.1.5.5.7.1.26), defined in RFC 8226.
The extension should contain a unique Service Provider account code (OCN):
asn1=SEQUENCE:tn_auth_list
[tn_auth_list]
field1=EXP:0,IA5:<OCN>TNAuthList value, used in the ACME HTTP requests, is a base64-encoded extension ASN.1 object.
For example, for OCN 616H X509v3 extension will be:
asn1=SEQUENCE:tn_auth_list
[tn_auth_list]
field1=EXP:0,IA5:616HAnd the base64-encoded TNAuthList value for HTTP requests:
How to generate "TNAuthList value"
tkvalue is a base64-encoded X509 extension and you can create it using openssl CLI tool with the following steps:
Step 1: Create ssl .conf file
Step 2: Create extension
Step 3: Encode
Here is a full example:
Order creation
To submit a new certificate order, ACME client should send a POST request to the newOrder URL with a set of parameters in the payload:
identifiers (mandatory) - contains TNAuthList value
notBefore (optional) - desired notBefore value of the created certificate
notAfter (optional) - desired notAfter value
Mandatory parameter "identifiers" must be a JSON array with a single TNAuthList value object:
Optional parameters notBefore and notAfter should have a RFC 3339 timestamp format (2022-01-15T00:00:01Z). If not set, certificate will be issued with the default lifespan of 1 year.
Example of the New Order request:
On success, ACME server should return a new ACME Order object, and ACME Order URL in the Location header:
ACME Client may get the ACME Order object by sending a POST request with an empty payload to the ACME order URL:
ACME Order object should contain:
Order status
Expiration time
ACME Order Challenge URL in the "authorizations" array
CSR submission URL in the "finalize" parameter
The possible values of the ACME Order status are:
"pending" - waiting for challenge submission
"ready" - user has passed the challenge; waiting for CSR submission
"processing" - creating a certificate
"valid" - certificate is ready for downloading
"invalid" - indicates an error
On failure, the "error" parameter must contain a problem document in a format, described in RFC 7807. The full list of registered error types can be found in the IANA database: https://www.iana.org/assignments/acme/acme.xhtml
Challenge
After submitting a new order, ACME client must acquire ACME Order Challenge, using URL from "authorizations" array of ACME order object.
Server should reply with an ACME Challenge object:
ACME Challenge object must contain a submission URL, and the current status of the ACME Challenge, which can be one of:
"pending" - waiting for the challenge submission
"processing" - validating submitted data
"valid" - user has successfully passed the challenge
"invalid" - an error has occurred during challenge processing
If status is "invalid", the "error" parameter must identify the rejection reason.
The "url" parameter represents ACME Challenge Submission URL.
Challenge submission
To prove ownership of the STI-SP account, ACME client must submit a fresh SPC token to the ACME Challenge Submission URL.
SPC token is a JWT (RFC 7519), signed by the STI Policy Administrator (Iconectiv) with mandatory parameters in the payload:
TNAuthList list value
CA flag (whether this SPC token is suitable for issuing End-Entity certificates, or for issuing CA certificates)
SHA256 fingerprint of the ACME Account key
SPC token payload example for regular (End-Entity) certificates:
ACME client must submit a SPC token to the Challenge submission URL:
On successful submission, ACME server should return 200 OK reply with the ACME Challenge object. Status of the ACME Challenge must be changed to "processing":
ACME client should poll ACME Challenge object, until status of the challenge changes. It's also possible to monitor status by polling ACME Order object.
CSR submission
Upon challenge validation, ACME Order status must be changed to "ready". Now ACME client should submit a CSR, which will be used to create a certificate.
The CSR for Service Providers must follow these rules:
CSR must contain a TNAuthList X509v3 extension (OID 1.3.6.1.5.5.7.1.26)
Country (DN: C) must be set to "US"
Organization (DN: O) must be non-empty
Common Name (DN: CN) parameter must contain the word "SHAKEN" and OCN
CSR cannot contain CRL Distribution Points others than the official PA CRL: https://authenticate-api.iconectiv.com/download/v1/crl
If CRL Distribution Points are not included in the CSR, they will be added automatically by the ACME server.
CSR example for Service Providers:
The URL to upload CSR can be found in the "finalize" parameter of the ACME Order object.
On success, ACME server should return 200 OK with the ACME Order object. The status of the order must be changed to "processing".
ACME client should poll ACME Order object until status of the order changes.
Certificate downloading
When ACME Order was successfully processed, status of the order should change to "valid", and URL to download the certificate must appear in the "certificate" parameter of the ACME Order object:
To download the certificate, ACME client must send a POST request with an empty payload to the Certificate URL:
Note, that the Certificate URL is not public, and can only be accessed with a signed POST request.
Review the certificate
The created certificate must have:
A valid lifespan (notBefore and notAfter parameters)
The requested Common Name
TNAuthList extension
CRL extension with URL of the official PA CRL
Basic Constraints extension, which identifies the type of the certificate (End-Entity or SCA)
2.16.840.1.114569.1.1.1 certificate policy
Last updated