Security News
NIST Misses 2024 Deadline to Clear NVD Backlog
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.
acme-client
Advanced tools
A simple and unopinionated ACME client.
This module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.
acme-client | Node.js | |
---|---|---|
v5.x | >= v16 | Upgrade guide |
v4.x | >= v10 | Changelog |
v3.x | >= v8 | Changelog |
v2.x | >= v4 | Changelog |
v1.x | >= v4 | Changelog |
$ npm install acme-client
const acme = require('acme-client');
const accountPrivateKey = '<PEM encoded private key>';
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey,
});
acme.directory.buypass.staging;
acme.directory.buypass.production;
acme.directory.letsencrypt.staging;
acme.directory.letsencrypt.production;
acme.directory.zerossl.production;
To enable external account binding when creating your ACME account, provide your KID and HMAC key to the client constructor.
const client = new acme.Client({
directoryUrl: 'https://acme-provider.example.com/directory-url',
accountKey: accountPrivateKey,
externalAccountBinding: {
kid: 'YOUR-EAB-KID',
hmacKey: 'YOUR-EAB-HMAC-KEY',
},
});
During the ACME account creation process, the server will check the supplied account key and either create a new account if the key is unused, or return the existing ACME account bound to that key.
In some cases, for example with some EAB providers, this account creation step may be prohibited and might require you to manually specify the account URL beforehand. This can be done through accountUrl
in the client constructor.
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey,
accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678',
});
You can fetch the clients current account URL, either after creating an account or supplying it through the constructor, using getAccountUrl()
:
const myAccountUrl = client.getAccountUrl();
For key pairs acme-client
utilizes native Node.js cryptography APIs, supporting signing and generation of both RSA and ECDSA keys. The module @peculiar/x509 is used to generate and parse Certificate Signing Requests.
These utility methods are exposed through .crypto
.
const privateRsaKey = await acme.crypto.createPrivateRsaKey();
const privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();
const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
altNames: ['example.com', '*.example.com'],
});
.forge
interfaceThe legacy node-forge
crypto interface is still available for backward compatibility, however this interface is now considered deprecated and will be removed in a future major version of acme-client
.
You should consider migrating to the new .crypto
API at your earliest convenience. More details can be found in the acme-client v5 upgrade guide.
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.
const autoOpts = {
csr: '<PEM encoded CSR>',
email: 'test@example.com',
termsOfServiceAgreed: true,
challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {},
};
const certificate = await client.auto(autoOpts);
When ordering a certificate using auto mode, acme-client
uses a priority list when selecting challenges to respond to. Its default value is ['http-01', 'dns-01']
which translates to "use http-01
if any challenges exist, otherwise fall back to dns-01
".
While most challenges can be validated using the method of your choosing, please note that wildcard certificates can only be validated through dns-01
. More information regarding Let's Encrypt challenge types can be found here.
To modify challenge priority, provide a list of challenge types in challengePriority
:
await client.auto({
...,
challengePriority: ['http-01', 'dns-01'],
});
When using auto mode, acme-client
will first validate that challenges are satisfied internally before completing the challenge at the ACME provider. In some cases (firewalls, etc) this internal challenge verification might not be possible to complete.
If internal challenge validation needs to travel through an HTTP proxy, see HTTP client defaults.
To completely disable acme-client
s internal challenge verification, enable skipChallengeVerification
:
await client.auto({
...,
skipChallengeVerification: true,
});
For more fine-grained control you can interact with the ACME API using the methods documented below.
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' },
],
});
This module uses axios when communicating with the ACME HTTP API, and exposes the client instance through .axios
.
For example, should you need to change the default axios configuration to route requests through an HTTP proxy, this can be achieved as follows:
const acme = require('acme-client');
acme.axios.defaults.proxy = {
host: '127.0.0.1',
port: 9000,
};
A complete list of axios options and documentation can be found at:
To get a better grasp of what acme-client
is doing behind the scenes, you can either pass it a logger function, or enable debugging through an environment variable.
Setting a logger function may for example be useful for passing messages on to another logging system, or just dumping them to the console.
acme.setLogger((message) => {
console.log(message);
});
Debugging to the console can also be enabled through debug by setting an environment variable.
DEBUG=acme-client node index.js
FAQs
Simple and unopinionated ACME client
The npm package acme-client receives a total of 59,845 weekly downloads. As such, acme-client popularity was classified as popular.
We found that acme-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.
Security News
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.