Sansay stand-alone STIR/SHAKEN ACME Client
Objective
Sansay natively supports Automated Certificate Management Environemt in the NSS product. This guide is exclusively for Service Providers using third-party STI-AS implementations and using Sansay as their STI-CA looking to implement automated certificate renewal.
This client is in compliance with ATIS-1000080v3 standards.
General Requirements
Service Provider account with valid SPC(s) that is approved by STI-PA.
Production environment API user credentials.
STI-PA and STI-CA API endpoint whitelisting.
Software Dependencies
Node.js v10 or greater (v10.16.1 is preferred).
If using an alternate version of Node, please be sure to run `npm install` once inside the directory to avoid version conflicts.
OpenSSL 1.0.1e or greater.
Download
Download the ACME client using the file provided in this article.
Getting Started
To start, unzip the file and step into a STI-PA and STI-CA whitelisted system.
After unpacking the ZIP file you will see something like this:
# ll total 152 -rw-r--r-- 1 root root 76766 Jun 15 18:00 acme_client.js drwxr-xr-x 2 root root 4096 Jun 14 21:15 certs drwxr-xr-x 2 root root 4096 Jun 15 20:24 conf drwxr-xr-x 2 root root 4096 Jun 14 21:26 csrs drwxr-xr-x 2 root root 4096 Jun 14 21:27 keys drwxr-xr-x 2 root root 4096 Jun 15 17:15 LOG drwxr-xr-x 94 root root 4096 Jun 9 18:23 node_modules -rw-r--r-- 1 root root 613 Jun 9 18:23 package.json -rw-r--r-- 1 root root 27783 Jun 9 18:23 package-lock.json -rw-r--r-- 1 root root 3452 Jun 15 20:56 sti-pa-crl.pem -rw-r--r-- 1 root root 365 Jun 15 17:59 test.js -rw-r--r-- 1 root root 7404 Jun 15 21:02 trusted-ca-bundle.pem
Configuration
The first step is to configure your Service Provider's details that will be used to obtain the SPC token and request the certificate. The configuration parameters are set up in ./ACME/conf/acme_config.json.
Note: You will need to replace all the values enclosed in << >>.
It should look something like this:
{
"mode": "PRODUCTION",
"caName": "Sansay",
"caRootCertLocation": "https://cr.sansay.com/CA.crt",
"orgName": "<<YOUR ORG NAME>>",
"spAuthUser": "<<YOUR API USER>>",
"spAuthPass": "<<YOUR PASS>>",
"SpcList": ["<<SPC1>>","<<SPC2>>"],
"spEmail": "<<YOUR EMAIL>>",
"spTN": "<<YOUR PHONE NUMBER>>",
"certificate_renewal_rate": "168", // Lifetime in hours
"sti_ca_directory_url": "https://sti-ca.sansay.com:4443/acme",
"config.acme_client_log_level": 0 // Logs from level 0 - 5
}
Once that is complete, you will also need to create a CSR file. Edit the file ‘csr.conf’ in the same directory as follows:
[req] default_bits = 2048 distinguished_name = dn prompt = no [dn] C="US" //Currently only US is supported ST="<<YOUR STATE>>" L="<<YOUR CITY>>" O="<<YOUR ORG NAME>>" OU="<<YOUR ORG UNIT NAME>>" emailAddress="<<YOUR EMAIL>>" CN="SHAKEN <<ORG NAME>> <<YOUR SPC>>"
The Common Name must follow the format “SHAKEN <<ORG_NAME>> <<SPC>>” where <<ORG_NAME>> is the exact same string as what you supplied to the O= line and <<SPC>> is the SPC that you’d like to create the CSR for. Once the file is updated, save it and run the following command:
If you already have a private key:
openssl req -config ./conf/csr.conf -new -key /PATH/TO/YOUR/KEY.key -out ./csrs/<<SPC>>.csr.pem
If you don’t already have a private key:
openssl ecparam -name prime256v1 -genkey -noout -out ./keys/<<SPC>>.key.pem
Then
openssl req -config ./conf/csr.conf -new -key ./keys/<<SPC>>.key.pem -out ./csrs/<<SPC>>.csr.pem
NOTE: This must be done once for every SPC that you plan to use with ACME. Different SPCs CAN use the same private key, but they cannot have the same CSR.
NOTE: Please make sure that you test the client in STAGING mode before sending queries to production.
Starting the Client
Once you have created your CSR(s) and updated the config files, then you’re ready to use the test client.
node ./test.js
If successful, you should see the following:
“We have entered the cert complete callback. GOT: https://cr.sansay.com/T3ST/order/123_T3ST_2”
At this point, you can now download the certificate using the response URL. Sansay’s ACME solution supports POST-AS-GET when communicating with sti-ca.sansay.com:4443 URLs and plain GET when using cr.sansay.com URLs.
By calling AcmeClient(), you’re initializing the Client. Once initialized, All you need to do is call CLIENT.run(<<SOME CALLBACK>>). When the certificate is created, the callback will be triggered and the URL of the new certificate will be passed in.
test.js is the actual client that will be used in production. With a successful output you can rename the client as you wish and/or add logic to your software stack.