Sansay stand-alone STIR/SHAKEN ACME Client

updated 2 yrs ago

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
API Users for accessing STI-PA API (Need Staging & Production)

Dependencies

Node.js v10 or greater (v10.16.1 is preferred)
1. 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

The ACME client can be downloaded using this link.

Getting Started

To start, get the latest version of the Sansay ACME Client. Unzip the file and step into the folder. At this point you should 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

First, we need to get the config files set up. Step into ./ACME/conf/ then edit the file ‘acme_config.json’. It should look something like this:

{

  "mode":                "STAGING",            // STAGING | PRODUCTION

  "caName":                "Sansay",

  "caRootCertLocation":        "https://cr.sansay.com/CA.crt",

  "orgName":                "<<YOUR ORG NAME>>",

  "spAuthUser":            "<<YOUR API USER>>",

  "spAuthPass":            "<<YOUR PASS>>",

  "SpcList":                ["SPC1", “SPC2”, “SPC3”],

  "spEmail":                "<<YOUR EMAIL>>",

  "spTN":                "<<YOUR PHONE NUMBER>>",

  "certificate_renewal_rate":    24,               //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. 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. First, make sure you are using the correct version of Node.js(v10+), then run:

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.