Certificator

An ACME client for automatically managing accounts and ssl certificates with Let's Encrypt certificate authority.

Prerequisites

Requires node 10.x.x for updated crypto library.

Usage

  npm install -g @pclabs/certificator
  certificator --help

Configuration

Certificator can be configured using the --plugin or --config option flags.

Use the --plugin flag if you require external dependencies to properly handle event callbacks. Plugins need to be packages that can be fetched and installed by Certificator.

--plugin @payclearly/[email protected]

Alternatively, use the --config flag to provide an absolute path JavaScript file that exports a config object. By default the current working directory is set to the root of this project. This can be changed using the --cwd flag.

--config ./config.js

Example:

module.exports = (options) => {

  return {
    plugin: options.plugin,
    config: options.config,
    environment: options.dryRun ? 'test' : 'production',
    packageAgent: `${package.name}/${package.version}`,
    domains: options.domain || [],
    maintainerEmail: options.maintainer,
    subscriberEmail: options.subscriber,
    accountId: options.accountId,
    accountDetails: options.accountDetails,
    cwd: options.cwd,
    subject: options.subject,
    privateKey: options.privateKey,
    csr: options.csr,

    setChallenge: ({ challenge }) => Promise.resolve(),

    getChallenge: ({ challenge }) => Promise.resolve(),

    removeChallenge: ({ challenge }) => Promise.resolve(),

    accountCreated: (account, accountKey) => Promise.resolve(),

    certificateCreated: (certificate) => Promise.resolve(),

    fetchServerPrivateKey: () => Promise.resolve(),

    fetchAccountDetails: () => Promise.resolve()
  }
};

Parameters

| Parameter             | Description                                                                                                 |
| ----------------------| ----------------------------------------------------------------------------------------------------------- |
| accountDetails        | an object containing the Let's Encrypt Account ID as "kid" (misnomer, not actually a key id/thumbprint)     |
|                       | and an RSA or EC public/private keypair in JWK format.                                                      |
| accountId             | a unique 8 digit id assigned by Let's Encrypt                                                               |
| accountKey            |                                                                                                             |
| certificate           |                                                                                                             |
| environment           | sets Let's Encrypt Directory URL. https://acme-staging-v02.api.letsencrypt.org/directory by default         |
| subject               | the domain of the DNS being challenged                                                                      |
| domains               | domain(s) that are listed in the CSR and will be listed on the certificate                                  |
| maintainerEmail       | should be a contact for the author of the code to receive critical bug and security notices                 |
| subscriberEmail       | should be a contact for the service provider to receive renewal failure notices and manage the ACME account |
| challenge             | object containing the challenge url and token                                                               |
| packageAgent          | an RFC72321-style user-agent string to append to the ACME client (ex: mypackage/v1.1.1)                     |
| plugin                | published npm package name to be install and used.                                                          |
|                       | Certificator needs permission to clone and install.                                                         |
| config                | realtive path to a config.js file.                                                                          |
| cwd                   | realtive path to install and load files from. default to process.cwd()                                      |
| privateKey            | realtive path to a JSON file containing the server's private key. Used to sign the CSR.                     |
|                         not used if a valid CSR is provided                                                                         |
| csr                   | realtive path to csr JSON file                                                                              |

Event Callbacks

| callback                  | Description                                                                                                 |
| --------------------------| ----------------------------------------------------------------------------------------------------------- |
| setChallenge (required)   | Should make the token url return the key authorization.                                                     |
|                           | i.e. GET http://example.com/.well-known/acme-challenge/xxxx => xxxx.yyyy                                    |
| removeChallenge (required)| remove the previously set token file (just the one)                                                         | 
| getChallenge (required)   | confirm the record was set. get the token file via the hosting service API                                  | 
| certificateCreated        | called when certificator has received a signed certificate from Let's Encrypt CA.                           |
| accountCreated            | called when a new account has been created with Let's Encrypt                                               |
| fetchServerPrivateKey     | called when creating a new certificate. The server private key is used to sign the CSR                      |
| fetchAccountDetails       | callback to fetch Certificator account Details                                                              |

Tests

npm run tests

##Legal This client implementation was built with ACME.js (a Root project).