npm package: @paar-it-gmbh/acme-client
Description: Simple and unopinionated ACME client
Author: nmorsman
Latest version: 4.3.0

# acme-client [![CircleCI](https://circleci.com/gh/publishlab/node-acme-client.svg?style=svg)](https://circleci.com/gh/publishlab/node-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](https://tools.ietf.org/html/rfc8555)
* Boulder divergences from ACME: [https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md](https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md)


### Compatibility

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


### Table of contents

* [Installation](#installation)
* [Usage](#usage)
* [Cryptography](#cryptography)
* [Auto mode](#auto-mode)
    * [Challenge priority](#challenge-priority)
    * [Internal challenge verification](#internal-challenge-verification)
* [API](#api)
* [HTTP client defaults](#http-client-defaults)
* [Debugging](#debugging)
* [License](#license)


## Installation

```bash
$ npm install acme-client
```


## Usage

```js
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

```js
acme.directory.letsencrypt.staging;
acme.directory.letsencrypt.production;
```


## Cryptography

For key pair generation and Certificate Signing Requests, `acme-client` uses [node-forge](https://www.npmjs.com/package/node-forge), a pure JavaScript implementation of the TLS protocol.

These utility methods are exposed through `.forge`.

__API documentation: [docs/forge.md](docs/forge.md)__


#### Example

```js
const privateKey = await acme.forge.createPrivateKey();

const [certificateKey, certificateCsr] = await acme.forge.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](examples/auto.js).

__Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)__


#### Example

```js
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](https://letsencrypt.org/docs/challenge-types/).

To modify challenge priority, provide a list of challenge types in `challengePriority`:

```js
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](#http-client-defaults).

To completely disable `acme-client`s internal challenge verification, enable `skipChallengeVerification`:

```js
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](examples/api.js).

__API documentation: [docs/client.md](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' }
    ]
});
```


## HTTP client defaults

This module uses [axios](https://github.com/axios/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:

```js
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#request-config)
* [https://github.com/axios/axios#custom-instance-defaults](https://github.com/axios/axios#custom-instance-defaults)


## Debugging

`acme-client` uses [debug](https://www.npmjs.com/package/debug) for debugging which can be enabled by running

```bash
DEBUG=acme-client node index.js
```


## License

[MIT](LICENSE)