Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

acme-client

publishlab73.1kMIT5.4.0TypeScript support: included

Simple and unopinionated ACME client

acme, client, lets, encrypt, acmev2, boulder

readme

acme-client test

A simple and unopinionated ACME client.

This module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.

Compatibility

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

Table of contents

Installation

$ npm install acme-client

Usage

const acme = require('acme-client');

const accountPrivateKey = '<PEM encoded private key>';

const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
});

Directory URLs

acme.directory.buypass.staging;
acme.directory.buypass.production;

acme.directory.google.staging;
acme.directory.google.production;

acme.directory.letsencrypt.staging;
acme.directory.letsencrypt.production;

acme.directory.zerossl.production;

External account binding

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',
    },
});

Specifying the account URL

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();

Cryptography

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'],
});

Legacy .forge interface

The 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.

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.

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);

Challenge priority

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'],
});

Internal challenge verification

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-clients internal challenge verification, enable skipChallengeVerification:

await client.auto({
    ...,
    skipChallengeVerification: true,
});

API

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' },
    ],
});

HTTP client defaults

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:

Debugging

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

License

MIT

changelog

Changelog

v5.4.0 (2024-07-16)

  • added Directory URLs for Google ACME provider
  • fixed Invalidate ACME provider directory cache after 24 hours
  • fixed Retry HTTP requests on server errors or when rate limited - #89

v5.3.1 (2024-05-22)

  • fixed Allow client.auto() being called with an empty CSR common name
  • fixed Bug when calling updateAccountKey() with external account binding

v5.3.0 (2024-02-05)

  • added Support and tests for satisfying tls-alpn-01 challenges
  • changed Replace jsrsasign with @peculiar/x509 for certificate and CSR handling
  • changed Method getChallengeKeyAuthorization() now returns $token.$thumbprint when called with a tls-alpn-01 challenge
    • Previously returned base64url encoded SHA256 digest of $token.$thumbprint erroneously
    • This change is not considered breaking since the previous behavior was incorrect

v5.2.0 (2024-01-22)

  • fixed Allow self-signed or invalid certs when validating http-01 challenges that redirect to HTTPS - #65
  • fixed Wait for all challenge promises to settle before rejecting client.auto() - #75

v5.1.0 (2024-01-20)

v5.0.0 (2022-07-28)

  • Upgrade guide here
  • added New native crypto interface, ECC/ECDSA support
  • breaking Remove support for Node v10, v12 and v14
  • breaking Prioritize issuer closest to root during preferred chain selection - #46
  • changed Replace bluebird dependency with native promise APIs
  • changed Replace backo2 dependency with internal utility

v4.2.5 (2022-03-21)

v4.2.4 (2022-03-19)

  • fixed Use SHA-256 when signing CSRs

v3.3.2 (2022-03-19)

  • backport Use SHA-256 when signing CSRs

v4.2.3 (2022-01-11)

  • added Directory URLs for ACME providers Buypass and ZeroSSL
  • fixed Skip already valid authorizations when using client.auto()

v4.2.2 (2022-01-10)

v4.2.1 (2022-01-10)

  • fixed ZeroSSL duplicate_domains_in_array error when using client.auto()

v4.2.0 (2022-01-06)

  • added Support for external account binding - RFC 8555 Section 7.3.4
  • added Ability to pass through custom logger function
  • changed Increase default backoffAttempts to 10
  • fixed Deactivate authorizations where challenges can not be completed
  • fixed Attempt authoritative name servers when verifying dns-01 challenges
  • fixed Error verbosity when failing to read ACME directory
  • fixed Correctly recognize ready and processing states - RFC 8555 Section 7.1.6

v4.1.4 (2021-12-23)

v4.1.3 (2021-02-22)

v4.1.2 (2020-11-16)

  • fixed Bug when encoding PEM payloads, potentially causing malformed requests

v4.1.1 (2020-11-13)

  • fixed Missing TypeScript definitions

v4.1.0 (2020-11-12)

  • added Option preferredChain added to client.getCertificate() and client.auto() to indicate which certificate chain is preferred if a CA offers multiple
  • added Method client.getOrder() to refresh order from CA
  • fixed Upgrade `axios@0.21.0`
  • fixed Error when attempting to revoke a certificate chain
  • fixed Missing URL augmentation in client.finalizeOrder() and client.deactivateAuthorization()
  • fixed Add certificate issuer to response from forge.readCertificateInfo()

v4.0.2 (2020-10-09)

v4.0.1 (2020-09-15)

v4.0.0 (2020-05-29)

  • breaking Remove support for Node v8
  • breaking Remove deprecated openssl crypto module
  • fixed Incorrect TypeScript CertificateInfo definitions
  • fixed Allow trailing whitespace character in http-01 challenge response

v3.3.1 (2020-01-07)

  • fixed Improvements to TypeScript definitions

v3.3.0 (2019-12-19)

v3.2.1 (2019-11-14)

  • added New option skipChallengeVerification added to client.auto() to bypass internal challenge verification

v3.2.0 (2019-08-26)

  • added More extensive testing using letsencrypt/pebble
  • changed When creating a CSR, commonName no longer defaults to 'localhost'
    • This change is not considered breaking since commonName: 'localhost' will result in an error when ordering a certificate
  • fixed Retry signed API requests on urn:ietf:params:acme:error:badNonce - RFC 8555 Section 6.5
  • fixed Minor bugs related to POST-as-GET when calling updateAccount()
  • fixed Ensure subject common name is present in SAN when creating a CSR - CAB v1.2.3 Section 9.2.2
  • fixed Send empty JSON body when responding to challenges - RFC 8555 Section 7.5.1

v2.3.1 (2019-08-26)

  • backport Minor bugs related to POST-as-GET when calling client.updateAccount()
  • backport Send empty JSON body when responding to challenges

v3.1.0 (2019-08-21)

  • added UTF-8 support when generating a CSR subject using forge - RFC 5280
  • fixed Implement POST-as-GET for all ACME API requests - RFC 8555 Section 6.3

v2.3.0 (2019-08-21)

  • backport Implement POST-as-GET for all ACME API requests

v3.0.0 (2019-07-13)

  • added Expose axios instance to allow manipulating HTTP client defaults
  • breaking Remove support for Node v4 and v6
  • breaking Remove Babel transpilation

v2.2.3 (2019-01-25)

  • added DNS CNAME detection when verifying dns-01 challenges

v2.2.2 (2019-01-07)

  • added Support for tls-alpn-01 challenge key authorization

v2.2.1 (2019-01-04)

  • fixed Handle and throw errors from OpenSSL process

v2.2.0 (2018-11-06)

  • added New node-forge crypto interface, removes OpenSSL CLI dependency
  • added Support native crypto.generateKeyPair() API when generating key pairs

v2.1.0 (2018-10-21)

  • added Ability to set and get current account URL
  • fixed Replace HTTP client request with axios
  • fixed Auto-mode no longer tries to create account when account URL exists

v2.0.1 (2018-08-17)

v2.0.0 (2018-04-02)

  • breaking ACMEv2
  • breaking API changes
  • breaking Rewrite to ES6
  • breaking Promises instead of callbacks

v1.0.0 (2017-10-20)

  • API stable

v0.2.1 (2017-09-27)

  • fixed Bug causing invalid anti-replay nonce

v0.2.0 (2017-09-21)

  • breaking OpenSSL method readCsrDomains and readCertificateInfo now return domains as an object
  • fixed Added and fixed some tests

v0.1.0 (2017-09-14)

  • acme-client released