github
/
certd
mirror of https://github.com/certd/certd
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Small crypto docs fix 2
Small crypto docs fix
Bump v5.3.1
Discourage use of cert subject common name, examples and docs
Style refactor docs and examples
Bump dependencies
pull/53/head
GitHub Actions Bot 2024-05-23 19:24:12 +00:00
parent 0f1ae6ccd9
commit 162e10909b
16 changed files with 94 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
packages/core/acme-client/CHANGELOG.md
View File

@ -1,6 +1,6 @@
# Changelog
## v5.3.1
## 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

39
packages/core/acme-client/README.md
View File

@ -9,13 +9,13 @@ This module is written to handle communication with a Boulder/Let's Encrypt-styl
## Compatibility
| acme-client | Node.js | |
| ------------- | --------- | ----------------------------------------- |
| v5.x | >= v16 | [Upgrade guide](docs/upgrade-v5.md) |
| v4.x | >= v10 | [Changelog](CHANGELOG.md#v400-2020-05-29) |
| v3.x | >= v8 | [Changelog](CHANGELOG.md#v300-2019-07-13) |
| v2.x | >= v4 | [Changelog](CHANGELOG.md#v200-2018-04-02) |
| v1.x | >= v4 | [Changelog](CHANGELOG.md#v100-2017-10-20) |
| acme-client | Node.js | |
| ----------- | ------- | ----------------------------------------- |
| v5.x | >= v16 | [Upgrade guide](docs/upgrade-v5.md) |
| v4.x | >= v10 | [Changelog](CHANGELOG.md#v400-2020-05-29) |
| v3.x | >= v8 | [Changelog](CHANGELOG.md#v300-2019-07-13) |
| v2.x | >= v4 | [Changelog](CHANGELOG.md#v200-2018-04-02) |
| v1.x | >= v4 | [Changelog](CHANGELOG.md#v100-2017-10-20) |
## Table of contents
@ -49,7 +49,7 @@ const accountPrivateKey = '<PEM encoded private key>';
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey
accountKey: accountPrivateKey,
});
```
@ -75,8 +75,8 @@ const client = new acme.Client({
accountKey: accountPrivateKey,
externalAccountBinding: {
kid: 'YOUR-EAB-KID',
hmacKey: 'YOUR-EAB-HMAC-KEY'
}
hmacKey: 'YOUR-EAB-HMAC-KEY',
},
});
```
@ -90,7 +90,7 @@ In some cases, for example with some EAB providers, this account creation step m
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey,
accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678'
accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678',
});
```
@ -113,8 +113,7 @@ const privateRsaKey = await acme.crypto.createPrivateRsaKey();
const privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();
const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
commonName: '*.example.com',
altNames: ['example.com']
altNames: ['example.com', '*.example.com'],
});
```
@ -139,7 +138,7 @@ const autoOpts = {
email: 'test@example.com',
termsOfServiceAgreed: true,
challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {}
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {},
};
const certificate = await client.auto(autoOpts);
@ -156,7 +155,7 @@ To modify challenge priority, provide a list of challenge types in `challengePri
```js
await client.auto({
...,
challengePriority: ['http-01', 'dns-01']
challengePriority: ['http-01', 'dns-01'],
});
```
@ -171,7 +170,7 @@ To completely disable `acme-client`s internal challenge verification, enable `sk
```js
await client.auto({
...,
skipChallengeVerification: true
skipChallengeVerification: true,
});
```
@ -185,14 +184,14 @@ For more fine-grained control you can interact with the ACME API using the metho
```js
const account = await client.createAccount({
termsOfServiceAgreed: true,
contact: ['mailto:test@example.com']
contact: ['mailto:test@example.com'],
});
const order = await client.createOrder({
identifiers: [
{ type: 'dns', value: 'example.com' },
{ type: 'dns', value: '*.example.com' }
]
{ type: 'dns', value: '*.example.com' },
],
});
```
@ -207,7 +206,7 @@ const acme = require('acme-client');
acme.axios.defaults.proxy = {
host: '127.0.0.1',
port: 9000
port: 9000,
};
```

28
packages/core/acme-client/docs/client.md
View File

@ -63,7 +63,7 @@ Create ACME client instance
```js
const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging,
accountKey: 'Private key goes here'
accountKey: 'Private key goes here',
});
```
**Example**
@ -75,7 +75,7 @@ const client = new acme.Client({
accountUrl: 'Optional account URL goes here',
backoffAttempts: 10,
backoffMin: 5000,
backoffMax: 30000
backoffMax: 30000,
});
```
**Example**
@ -86,8 +86,8 @@ const client = new acme.Client({
accountKey: 'Private key goes here',
externalAccountBinding: {
kid: 'YOUR-EAB-KID',
hmacKey: 'YOUR-EAB-HMAC-KEY'
}
hmacKey: 'YOUR-EAB-HMAC-KEY',
},
});
```
<a name="AcmeClient+getTermsOfServiceUrl"></a>
@ -145,7 +145,7 @@ https://datatracker.ietf.org/doc/html/rfc8555#section-7.3
Create a new account
```js
const account = await client.createAccount({
termsOfServiceAgreed: true
termsOfServiceAgreed: true,
});
```
**Example**
@ -153,7 +153,7 @@ Create a new account with contact info
```js
const account = await client.createAccount({
termsOfServiceAgreed: true,
contact: ['mailto:test@example.com']
contact: ['mailto:test@example.com'],
});
```
<a name="AcmeClient+updateAccount"></a>
@ -174,7 +174,7 @@ https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.2
Update existing account
```js
const account = await client.updateAccount({
contact: ['mailto:foo@example.com']
contact: ['mailto:foo@example.com'],
});
```
<a name="AcmeClient+updateAccountKey"></a>
@ -218,8 +218,8 @@ Create a new order
const order = await client.createOrder({
identifiers: [
{ type: 'dns', value: 'example.com' },
{ type: 'dns', value: 'test.example.com' }
]
{ type: 'dns', value: 'test.example.com' },
],
});
```
<a name="AcmeClient+getOrder"></a>
@ -452,7 +452,7 @@ Revoke certificate with reason
```js
const certificate = { ... }; // Previously created certificate
const result = await client.revokeCertificate(certificate, {
reason: 4
reason: 4,
});
```
<a name="AcmeClient+auto"></a>
@ -479,7 +479,7 @@ Auto mode
Order a certificate using auto mode
```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
});
const certificate = await client.auto({
@ -491,14 +491,14 @@ const certificate = await client.auto({
},
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
// Clean up challenge here
}
},
});
```
**Example**
Order a certificate using auto mode with preferred chain
```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
});
const certificate = await client.auto({
@ -507,7 +507,7 @@ const certificate = await client.auto({
termsOfServiceAgreed: true,
preferredChain: 'DST Root CA X3',
challengeCreateFn: async () => {},
challengeRemoveFn: async () => {}
challengeRemoveFn: async () => {},
});
```
<a name="Client"></a>

13
packages/core/acme-client/docs/crypto.md
View File

@ -239,29 +239,30 @@ Create a Certificate Signing Request
Create a Certificate Signing Request
```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
});
```
**Example**
Certificate Signing Request with both common and alternative names
> *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
keySize: 4096,
commonName: 'test.example.com',
altNames: ['foo.example.com', 'bar.example.com']
altNames: ['foo.example.com', 'bar.example.com'],
});
```
**Example**
Certificate Signing Request with additional information
```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com',
altNames: ['test.example.com'],
country: 'US',
state: 'California',
locality: 'Los Angeles',
organization: 'The Company Inc.',
organizationUnit: 'IT Department',
emailAddress: 'contact@example.com'
emailAddress: 'contact@example.com',
});
```
**Example**
@ -270,8 +271,9 @@ Certificate Signing Request with ECDSA private key
const certificateKey = await acme.crypto.createPrivateEcdsaKey();
const [, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
}, certificateKey);
```
<a name="createAlpnCertificate"></a>
## createAlpnCertificate(authz, keyAuthorization, [keyPem]) ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code>
@ -298,6 +300,7 @@ Create a ALPN certificate with ECDSA private key
```js
const alpnKey = await acme.crypto.createPrivateEcdsaKey();
const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey);
```
<a name="isAlpnCertificateAuthorizationValid"></a>
## isAlpnCertificateAuthorizationValid(certPem, keyAuthorization) ⇒ <code>boolean</code>

11
packages/core/acme-client/docs/forge.md
View File

@ -222,29 +222,30 @@ Create a Certificate Signing Request
Create a Certificate Signing Request
```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
});
```
**Example**
Certificate Signing Request with both common and alternative names
> *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({
keySize: 4096,
commonName: 'test.example.com',
altNames: ['foo.example.com', 'bar.example.com']
altNames: ['foo.example.com', 'bar.example.com'],
});
```
**Example**
Certificate Signing Request with additional information
```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com',
altNames: ['test.example.com'],
country: 'US',
state: 'California',
locality: 'Los Angeles',
organization: 'The Company Inc.',
organizationUnit: 'IT Department',
emailAddress: 'contact@example.com'
emailAddress: 'contact@example.com',
});
```
**Example**
@ -253,5 +254,5 @@ Certificate Signing Request with predefined private key
const certificateKey = await acme.forge.createPrivateKey();
const [, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com'
altNames: ['test.example.com'],
}, certificateKey);

3
packages/core/acme-client/examples/api.js
View File

@ -135,8 +135,7 @@ module.exports = async () => {
/* Finalize order */
const [key, csr] = await acme.crypto.createCsr({
commonName: '*.example.com',
altNames: ['example.com'],
altNames: ['example.com', '*.example.com'],
});
const finalized = await client.finalizeOrder(order, csr);

2
packages/core/acme-client/examples/auto.js
View File

@ -95,7 +95,7 @@ module.exports = async () => {
/* Create CSR */
const [key, csr] = await acme.crypto.createCsr({
commonName: 'example.com',
altNames: ['example.com'],
});
/* Certificate */

3
packages/core/acme-client/examples/dns-01/dns-01.js
View File

@ -41,8 +41,7 @@ function log(m) {
log(`Creating CSR for ${WILDCARD_DOMAIN}`);
const [key, csr] = await acme.crypto.createCsr({
commonName: WILDCARD_DOMAIN,
altNames: [`*.${WILDCARD_DOMAIN}`],
altNames: [WILDCARD_DOMAIN, `*.${WILDCARD_DOMAIN}`],
});
log(`Ordering certificate for ${WILDCARD_DOMAIN}`);

2
packages/core/acme-client/examples/http-01/http-01.js
View File

@ -51,7 +51,7 @@ async function getCertOnDemand(client, servername, attempt = 0) {
/* Create CSR */
log(`Creating CSR for ${servername}`);
const [key, csr] = await acme.crypto.createCsr({
commonName: servername,
altNames: [servername],
});
/* Order certificate */

2
packages/core/acme-client/examples/tls-alpn-01/tls-alpn-01.js
View File

@ -50,7 +50,7 @@ async function getCertOnDemand(client, servername, attempt = 0) {
/* Create CSR */
log(`Creating CSR for ${servername}`);
const [key, csr] = await acme.crypto.createCsr({
commonName: servername,
altNames: [servername],
});
/* Order certificate */

20
packages/core/acme-client/package.json
View File

@ -2,7 +2,7 @@
"name": "acme-client",
"description": "Simple and unopinionated ACME client",
"author": "nmorsman",
"version": "5.3.0",
"version": "5.3.1",
"main": "src/index.js",
"types": "types/index.d.ts",
"license": "MIT",
@ -15,23 +15,23 @@
"types"
],
"dependencies": {
"@peculiar/x509": "^1.9.7",
"@peculiar/x509": "^1.10.0",
"asn1js": "^3.0.5",
"axios": "^1.6.5",
"axios": "^1.7.2",
"debug": "^4.1.1",
"node-forge": "^1.3.1"
},
"devDependencies": {
"@types/node": "^20.11.5",
"@types/node": "^20.12.12",
"chai": "^4.4.1",
"chai-as-promised": "^7.1.1",
"eslint": "^8.56.0",
"chai-as-promised": "^7.1.2",
"eslint": "^8.57.0",
"eslint-config-airbnb-base": "^15.0.0",
"eslint-plugin-import": "^2.29.1",
"jsdoc-to-markdown": "^8.0.0",
"mocha": "^10.2.0",
"nock": "^13.5.0",
"tsd": "^0.30.4"
"jsdoc-to-markdown": "^8.0.1",
"mocha": "^10.4.0",
"nock": "^13.5.4",
"tsd": "^0.31.0"
},
"scripts": {
"build-docs": "jsdoc2md src/client.js > docs/client.md && jsdoc2md src/crypto/index.js > docs/crypto.md && jsdoc2md src/crypto/forge.js > docs/forge.md",

28
packages/core/acme-client/src/client.js
View File

@ -58,7 +58,7 @@ const defaultOpts = {
* ```js
* const client = new acme.Client({
* directoryUrl: acme.directory.letsencrypt.staging,
* accountKey: 'Private key goes here'
* accountKey: 'Private key goes here',
* });
* ```
*
@ -70,7 +70,7 @@ const defaultOpts = {
* accountUrl: 'Optional account URL goes here',
* backoffAttempts: 10,
* backoffMin: 5000,
* backoffMax: 30000
* backoffMax: 30000,
* });
* ```
*
@ -81,8 +81,8 @@ const defaultOpts = {
* accountKey: 'Private key goes here',
* externalAccountBinding: {
* kid: 'YOUR-EAB-KID',
* hmacKey: 'YOUR-EAB-HMAC-KEY'
* }
* hmacKey: 'YOUR-EAB-HMAC-KEY',
* },
* });
* ```
*/
@ -155,7 +155,7 @@ class AcmeClient {
* @example Create a new account
* ```js
* const account = await client.createAccount({
* termsOfServiceAgreed: true
* termsOfServiceAgreed: true,
* });
* ```
*
@ -163,7 +163,7 @@ class AcmeClient {
* ```js
* const account = await client.createAccount({
* termsOfServiceAgreed: true,
* contact: ['mailto:test@example.com']
* contact: ['mailto:test@example.com'],
* });
* ```
*/
@ -200,7 +200,7 @@ class AcmeClient {
* @example Update existing account
* ```js
* const account = await client.updateAccount({
* contact: ['mailto:foo@example.com']
* contact: ['mailto:foo@example.com'],
* });
* ```
*/
@ -286,8 +286,8 @@ class AcmeClient {
* const order = await client.createOrder({
* identifiers: [
* { type: 'dns', value: 'example.com' },
* { type: 'dns', value: 'test.example.com' }
* ]
* { type: 'dns', value: 'test.example.com' },
* ],
* });
* ```
*/
@ -638,7 +638,7 @@ class AcmeClient {
* ```js
* const certificate = { ... }; // Previously created certificate
* const result = await client.revokeCertificate(certificate, {
* reason: 4
* reason: 4,
* });
* ```
*/
@ -666,7 +666,7 @@ class AcmeClient {
* @example Order a certificate using auto mode
* ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* });
*
* const certificate = await client.auto({
@ -678,14 +678,14 @@ class AcmeClient {
* },
* challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
* // Clean up challenge here
* }
* },
* });
* ```
*
* @example Order a certificate using auto mode with preferred chain
* ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* });
*
* const certificate = await client.auto({
@ -694,7 +694,7 @@ class AcmeClient {
* termsOfServiceAgreed: true,
* preferredChain: 'DST Root CA X3',
* challengeCreateFn: async () => {},
* challengeRemoveFn: async () => {}
* challengeRemoveFn: async () => {},
* });
* ```
*/

11
packages/core/acme-client/src/crypto/forge.js
View File

@ -342,29 +342,30 @@ function formatCsrAltNames(altNames) {
* @example Create a Certificate Signing Request
* ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* });
* ```
*
* @example Certificate Signing Request with both common and alternative names
* > *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
* ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({
* keySize: 4096,
* commonName: 'test.example.com',
* altNames: ['foo.example.com', 'bar.example.com']
* altNames: ['foo.example.com', 'bar.example.com'],
* });
* ```
*
* @example Certificate Signing Request with additional information
* ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({
* commonName: 'test.example.com',
* altNames: ['test.example.com'],
* country: 'US',
* state: 'California',
* locality: 'Los Angeles',
* organization: 'The Company Inc.',
* organizationUnit: 'IT Department',
* emailAddress: 'contact@example.com'
* emailAddress: 'contact@example.com',
* });
* ```
*
@ -373,7 +374,7 @@ function formatCsrAltNames(altNames) {
* const certificateKey = await acme.forge.createPrivateKey();
*
* const [, certificateRequest] = await acme.forge.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* }, certificateKey);
*/

13
packages/core/acme-client/src/crypto/index.js
View File

@ -413,29 +413,30 @@ function createSubjectAltNameExtension(altNames) {
* @example Create a Certificate Signing Request
* ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* });
* ```
*
* @example Certificate Signing Request with both common and alternative names
* > *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
* ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* keySize: 4096,
* commonName: 'test.example.com',
* altNames: ['foo.example.com', 'bar.example.com']
* altNames: ['foo.example.com', 'bar.example.com'],
* });
* ```
*
* @example Certificate Signing Request with additional information
* ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com',
* altNames: ['test.example.com'],
* country: 'US',
* state: 'California',
* locality: 'Los Angeles',
* organization: 'The Company Inc.',
* organizationUnit: 'IT Department',
* emailAddress: 'contact@example.com'
* emailAddress: 'contact@example.com',
* });
* ```
*
@ -444,8 +445,9 @@ function createSubjectAltNameExtension(altNames) {
* const certificateKey = await acme.crypto.createPrivateEcdsaKey();
*
* const [, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com'
* altNames: ['test.example.com'],
* }, certificateKey);
* ```
*/
exports.createCsr = async (data, keyPem = null) => {
@ -516,6 +518,7 @@ exports.createCsr = async (data, keyPem = null) => {
* ```js
* const alpnKey = await acme.crypto.createPrivateEcdsaKey();
* const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey);
* ```
*/
exports.createAlpnCertificate = async (authz, keyAuthorization, keyPem = null) => {

4
packages/core/acme-client/test/50-client.spec.js
View File

@ -110,8 +110,8 @@ describe('client', () => {
it('should generate certificate signing request', async () => {
[, testCsr] = await acme.crypto.createCsr({ commonName: testDomain }, await createKeyFn());
[, testCsrAlpn] = await acme.crypto.createCsr({ commonName: testDomainAlpn }, await createKeyFn());
[, testCsrWildcard] = await acme.crypto.createCsr({ commonName: testDomainWildcard }, await createKeyFn());
[, testCsrAlpn] = await acme.crypto.createCsr({ altNames: [testDomainAlpn] }, await createKeyFn());
[, testCsrWildcard] = await acme.crypto.createCsr({ altNames: [testDomainWildcard] }, await createKeyFn());
});
it('should resolve certificate issuers [ACME_CAP_ALTERNATE_CERT_ROOTS]', async function () {

3
packages/core/acme-client/test/70-auto.spec.js
View File

@ -307,8 +307,7 @@ describe('client.auto', () => {
it('should order wildcard certificate', async () => {
const [, csr] = await acme.crypto.createCsr({
commonName: testWildcardDomain,
altNames: [`*.${testWildcardDomain}`],
altNames: [testWildcardDomain, `*.${testWildcardDomain}`],
}, await createKeyFn());
const cert = await testClient.auto({