acme-client

What is acme-client?

The acme-client npm package is a client library for the ACME (Automated Certificate Management Environment) protocol, which is used to automate the process of obtaining and renewing SSL/TLS certificates. It is commonly used with Let's Encrypt, a free, automated, and open Certificate Authority.

What are acme-client's main functionalities?

Creating an ACME client instance

This code demonstrates how to create an instance of the ACME client. The client is configured to use Let's Encrypt's production directory and a newly generated account key.

const acme = require('acme-client');
const client = new acme.Client({
  directoryUrl: acme.directory.letsencrypt.production,
  accountKey: await acme.forge.createPrivateKey()
});

Creating a new account

This code shows how to create a new account with the ACME server. It agrees to the terms of service and provides a contact email.

await client.createAccount({
  termsOfServiceAgreed: true,
  contact: ['mailto:[e-mail]']
});

Generating a certificate

This code demonstrates how to generate a certificate signing request (CSR) and then use the ACME client to automatically obtain a certificate for the domain 'example.com'.

const [key, csr] = await acme.forge.createCsr({
  commonName: 'example.com'
});
const cert = await client.auto({
  csr,
  email: '[e-mail]',
  termsOfServiceAgreed: true
});

Renewing a certificate

This code shows how to renew an existing certificate using the ACME client. It requires the existing certificate and CSR.

const renewedCert = await client.renewCertificate({
  certificate: existingCert,
  csr: existingCsr
});

Other packages similar to acme-client

greenlock

Greenlock is another ACME client for Node.js that simplifies the process of obtaining and renewing SSL/TLS certificates from Let's Encrypt. It provides a higher-level API compared to acme-client and includes additional features like automatic renewal and integration with various web servers.

letsencrypt

The letsencrypt package is a Node.js client for Let's Encrypt. It is designed to be simple and easy to use, providing basic functionality for obtaining and renewing certificates. It is less feature-rich compared to acme-client but can be a good choice for straightforward use cases.

certbot

Certbot is a popular ACME client developed by the Electronic Frontier Foundation (EFF). While it is not a Node.js package, it is widely used for obtaining and renewing Let's Encrypt certificates. It offers a comprehensive set of features and is highly configurable, making it suitable for a variety of environments.

README

acme-client

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

acme-client	API	Style
v2.x	ACMEv2	Promise
v1.x	ACMEv1	callback

Notice: On November 1st, 2019 Let's Encrypt will remove support for unauthenticated GETs from the v2 API. Please update to acme-client >= v3.2.0 or >= v2.3.1 before this date to avoid being affected by this API change.

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.letsencrypt.staging;
acme.directory.letsencrypt.production;

Cryptography

For key pair generation and Certificate Signing Requests, acme-client 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 acme.forge.createPrivateKey();

const [certificateKey, certificateCsr] = await acme.forge.createCsr({
    commonName: '*.example.com',
    altNames: ['example.com']
})

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 acme.openssl.createPrivateKey();

const [certificateKey, certificateCsr] = await acme.openssl.createCsr({
    commonName: '*.example.com',
    altNames: ['example.com']
})

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: '[e-mail]',
    termsOfServiceAgreed: true,
    challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
    challengeRemoveFn: async (authz, challenge, keyAuthorization) => {}
}

const certificate = await client.auto(autoOpts);

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.createAccount({
    termsOfServiceAgreed: true,
    contact: ['mailto:[e-mail]']
});

const order = await client.createOrder({
    identifiers: [
        { type: 'dns', value: 'example.com' },
        { type: 'dns', value: '*.example.com' }
    ]
});

Debugging

acme-client uses debug for debugging which can be enabled by running

DEBUG=acme-client node index.js

License

MIT