lkddi/certd
1
0
Fork 0
mirror of https://github.com/certd/certd.git synced 2026-04-24 20:57:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

🔱: [acme] sync upgrade with 10 commits [trident-sync]

Browse Source 
Bump v5.1.0
Bump dep axios@1.6.5
Bump dep jsrsasign@11.0.0
Bump dev deps, typo in editorconfig
Replace uuid devdep with crypto.randomUUID
LICENSE, docs formatting, remove upgrade notice
Fix package.json typo
Replace deprecated dtslint with tsd, bump types
Add Node v20 to matrix, bump misc CI stuff
This commit is contained in:
GitHub Actions Bot
2024-01-20 19:24:14 +00:00
parent f64ea78c44
commit d22a25d260
17 changed files with 52 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/core/acme-client/README.md
+9 -32
View File
@@ -7,15 +7,7 @@ This module is written to handle communication with a Boulder/Let's Encrypt-styl
* 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)
## Important upgrade notice
On September 15, 2022, Let's Encrypt will stop accepting Certificate Signing Requests signed using the obsolete SHA-1 hash. This change affects all `acme-client` versions lower than `3.3.2` and `4.2.4`. Please upgrade ASAP to ensure that your certificates can still be issued following this date.
A more detailed explanation can be found [at the Let's Encrypt forums](https://community.letsencrypt.org/t/rejecting-sha-1-csrs-and-validation-using-tls-1-0-1-1-urls/175144).
### Compatibility
## Compatibility
| acme-client | Node.js | |
| ------------- | --------- | ----------------------------------------- |
@@ -25,8 +17,7 @@ A more detailed explanation can be found [at the Let's Encrypt forums](https://c
| v2.x | >= v4 | [Changelog](CHANGELOG.md#v200-2018-04-02) |
| v1.x | >= v4 | [Changelog](CHANGELOG.md#v100-2017-10-20) |
### Table of contents
## Table of contents
* [Installation](#installation)
* [Usage](#usage)
@@ -43,14 +34,12 @@ A more detailed explanation can be found [at the Let's Encrypt forums](https://c
* [Debugging](#debugging)
* [License](#license)
## Installation
```bash
$ npm install acme-client
```
## Usage
```js
@@ -64,7 +53,6 @@ const client = new acme.Client({
});
```
### Directory URLs
```js
@@ -77,7 +65,6 @@ acme.directory.letsencrypt.production;
acme.directory.zerossl.production;
```
### External account binding
To enable [external account binding](https://tools.ietf.org/html/rfc8555#section-7.3.4) when creating your ACME account, provide your KID and HMAC key to the client constructor.
@@ -93,7 +80,6 @@ const client = new acme.Client({
});
```
### 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.
@@ -114,14 +100,13 @@ You can fetch the clients current account URL, either after creating an account
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 [jsrsasign](https://www.npmjs.com/package/jsrsasign) is used to generate and parse Certificate Signing Requests.
These utility methods are exposed through `.crypto`.
* __Documentation: [docs/crypto.md](docs/crypto.md)__
* **Documentation: [docs/crypto.md](docs/crypto.md)**
```js
const privateRsaKey = await acme.crypto.createPrivateRsaKey();
@@ -133,22 +118,20 @@ const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
});
```
### 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](docs/upgrade-v5.md).
* __Documentation: [docs/forge.md](docs/forge.md)__
* **Documentation: [docs/forge.md](docs/forge.md)**
## 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.
* __Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)__
* __Full example: [examples/auto.js](examples/auto.js)__
* **Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)**
* **Full example: [examples/auto.js](examples/auto.js)**
```js
const autoOpts = {
@@ -162,12 +145,11 @@ const autoOpts = {
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/).
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`:
@@ -178,7 +160,6 @@ await client.auto({
});
```
### 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.
@@ -194,13 +175,12 @@ await client.auto({
});
```
## API
For more fine-grained control you can interact with the ACME API using the methods documented below.
* __Documentation: [docs/client.md](docs/client.md)__
* __Full example: [examples/api.js](examples/api.js)__
* **Documentation: [docs/client.md](docs/client.md)**
* **Full example: [examples/api.js](examples/api.js)**
```js
const account = await client.createAccount({
@@ -216,7 +196,6 @@ const order = await client.createOrder({
});
```
## 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`.
@@ -237,7 +216,6 @@ 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
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.
@@ -256,7 +234,6 @@ Debugging to the console can also be enabled through [debug](https://www.npmjs.c
DEBUG=acme-client node index.js
```
## License
[MIT](LICENSE)