Simple and unopinionated ACME client
npm install nacmeA 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
| nacme | API | Style |
| ------------- | --------- | --------- |
| v2.x | ACMEv2 | Promise |
| v1.x | ACMEv1 | callback |
``bash`
$ npm install nacme
`js
const acme = require('nacme');
const accountPrivateKey = '
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey
});
`
`js`
acme.directory.letsencrypt.staging;
acme.directory.letsencrypt.production;
For key pair generation and Certificate Signing Requests, nacme supports multiple interchangeable cryptographic engines.
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
`js
const privateKey = await acme.forge.createPrivateKey();
const [certificateKey, certificateCsr] = await acme.forge.createCsr({
commonName: '*.example.com',
altNames: ['example.com']
})
`
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
`js
const privateKey = await acme.openssl.createPrivateKey();
const [certificateKey, certificateCsr] = await acme.openssl.createCsr({
commonName: '*.example.com',
altNames: ['example.com']
})
`
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
`js
const autoOpts = {
csr: '
email: 'test@example.com',
termsOfServiceAgreed: true,
challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {}
}
const certificate = await client.auto(autoOpts);
`
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
`js
const account = await client.createAccount({
termsOfServiceAgreed: true,
contact: ['mailto:test@example.com']
});
const order = await client.createOrder({
identifiers: [
{ type: 'dns', value: 'example.com' },
{ type: 'dns', value: '*.example.com' }
]
});
`
nacme uses debug for debugging which can be enabled by running
`bash``
DEBUG=nacme node index.js