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.

• RFC 8555 - Automatic Certificate Management Environment (ACME): https://tools.ietf.org/html/rfc8555
• Boulder divergences from ACME: https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md

ACME compatibility

acme-client	API	Style	Node.js
v3.x	ACMEv2	Promise	>= v8
v2.x	ACMEv2	Promise	>= v4
v1.x	ACMEv1	callback	>= v4

Table of contents

• Installation
• Usage
• Cryptography
  • acme.forge
  • acme.openssl
• Auto mode
  • Internal challenge verification
• API
• HTTP client defaults
• Debugging
• License

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

• Should be used when node >= v10.12.0 or OpenSSL CLI dependency can not be met
• API documentation: docs/forge.md

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

• Can be used when node < v10.12.0 and OpenSSL CLI dependency can be met
• API documentation: docs/openssl.md
• Warning: Will most likely be deprecated some time in the future

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

Internal challenge verification

When ordering a certificate 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.

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

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:

• https://github.com/axios/axios#request-config
• https://github.com/axios/axios#custom-instance-defaults

Debugging

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

DEBUG=acme-client node index.js

License

MIT

Changelog

v3.3.1 (2020-01-07)

• fixed Improvements to TypeScript definitions