nacme
A simple and unopinionated ACME client.
This module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.
ACME specification: https://github.com/ietf-wg-acme/acme/blob/master/draft-ietf-acme-acme.md
Information on how the Boulder/Let's Encrypt API diverges from the ACME spec: https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md
ACME compatibility
nacme | API | Style |
---|---|---|
v2.x | ACMEv2 | Promise |
v1.x | ACMEv1 | callback |
Installation
$ npm install nacme
Usage
const acme = ; const accountPrivateKey = '<PEM encoded private key>'; const client = directoryUrl: acmedirectoryletsencryptstaging accountKey: accountPrivateKey;
Directory URLs
acmedirectoryletsencryptstaging;acmedirectoryletsencryptproduction;
Cryptography
For key pair generation and Certificate Signing Requests, nacme
supports multiple interchangeable cryptographic engines.
acme.forge
-- docs/forge.md
Recommended when node >= v10.12.0
or OpenSSL CLI dependency can not be met.
Uses node-forge, a pure JavaScript implementation of the TLS protocol.
This engine has no external dependencies since it is completely implemented in JavaScript, however CPU-intensive tasks (like generating a large size key pair) has a performance penalty and will be slower than doing it natively.
This caveat is removed in Node v10.12.0 with the introduction of crypto.generateKeyPair(), a native Node API for key pair generation. The forge engine will automatically use this API when available.
Example
const privateKey = await acmeforge; const certificateKey certificateCsr = await acmeforge
acme.openssl
-- docs/openssl.md
Recommended when node < v10.12.0
and OpenSSL CLI dependency can be met.
Uses openssl-wrapper to execute commands using the OpenSSL CLI.
This engine requires OpenSSL to be installed and available in $PATH
.
Example
const privateKey = await acmeopenssl; const certificateKey certificateCsr = await acmeopenssl
Auto mode
For convenience an auto()
method is included in the client that takes a single config object.
This method will handle the entire process of getting a certificate for one or multiple domains.
A full example can be found at examples/auto.js.
Documentation: docs/client.md#AcmeClient+auto
Example
const autoOpts = csr: '<PEM encoded CSR>' email: 'test@example.com' termsOfServiceAgreed: true challengeCreateFn: async {} challengeRemoveFn: async {} const certificate = await client;
API
For more fine-grained control you can interact with the ACME API using the methods documented below.
A full example can be found at examples/api.js.
Documentation: docs/client.md
Example
const account = await client; const order = await client;
Debugging
nacme
uses debug for debugging which can be enabled by running
DEBUG=nacme node index.js