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 # Changelog
## v5.3.1 ## v5.3.1 (2024-05-22)
* `fixed` Allow `client.auto()` being called with an empty CSR common name * `fixed` Allow `client.auto()` being called with an empty CSR common name
* `fixed` Bug when calling `updateAccountKey()` with external account binding * `fixed` Bug when calling `updateAccountKey()` with external account binding

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

@ -10,7 +10,7 @@ This module is written to handle communication with a Boulder/Let's Encrypt-styl
## Compatibility ## Compatibility
| acme-client | Node.js | | | acme-client | Node.js | |
| ------------- | --------- | ----------------------------------------- | | ----------- | ------- | ----------------------------------------- |
| v5.x | >= v16 | [Upgrade guide](docs/upgrade-v5.md) | | v5.x | >= v16 | [Upgrade guide](docs/upgrade-v5.md) |
| v4.x | >= v10 | [Changelog](CHANGELOG.md#v400-2020-05-29) | | v4.x | >= v10 | [Changelog](CHANGELOG.md#v400-2020-05-29) |
| v3.x | >= v8 | [Changelog](CHANGELOG.md#v300-2019-07-13) | | v3.x | >= v8 | [Changelog](CHANGELOG.md#v300-2019-07-13) |
@ -49,7 +49,7 @@ const accountPrivateKey = '<PEM encoded private key>';
const client = new acme.Client({ const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging, directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey accountKey: accountPrivateKey,
}); });
``` ```
@ -75,8 +75,8 @@ const client = new acme.Client({
accountKey: accountPrivateKey, accountKey: accountPrivateKey,
externalAccountBinding: { externalAccountBinding: {
kid: 'YOUR-EAB-KID', 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({ const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging, directoryUrl: acme.directory.letsencrypt.staging,
accountKey: accountPrivateKey, 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 privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();
const [certificateKey, certificateCsr] = await acme.crypto.createCsr({ const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
commonName: '*.example.com', altNames: ['example.com', '*.example.com'],
altNames: ['example.com']
}); });
``` ```
@ -139,7 +138,7 @@ const autoOpts = {
email: 'test@example.com', email: 'test@example.com',
termsOfServiceAgreed: true, termsOfServiceAgreed: true,
challengeCreateFn: async (authz, challenge, keyAuthorization) => {}, challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
challengeRemoveFn: async (authz, challenge, keyAuthorization) => {} challengeRemoveFn: async (authz, challenge, keyAuthorization) => {},
}; };
const certificate = await client.auto(autoOpts); const certificate = await client.auto(autoOpts);
@ -156,7 +155,7 @@ To modify challenge priority, provide a list of challenge types in `challengePri
```js ```js
await client.auto({ 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 ```js
await client.auto({ 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 ```js
const account = await client.createAccount({ const account = await client.createAccount({
termsOfServiceAgreed: true, termsOfServiceAgreed: true,
contact: ['mailto:test@example.com'] contact: ['mailto:test@example.com'],
}); });
const order = await client.createOrder({ const order = await client.createOrder({
identifiers: [ identifiers: [
{ type: 'dns', value: 'example.com' }, { 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 = { acme.axios.defaults.proxy = {
host: '127.0.0.1', 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 ```js
const client = new acme.Client({ const client = new acme.Client({
directoryUrl: acme.directory.letsencrypt.staging, directoryUrl: acme.directory.letsencrypt.staging,
accountKey: 'Private key goes here' accountKey: 'Private key goes here',
}); });
``` ```
**Example** **Example**
@ -75,7 +75,7 @@ const client = new acme.Client({
accountUrl: 'Optional account URL goes here', accountUrl: 'Optional account URL goes here',
backoffAttempts: 10, backoffAttempts: 10,
backoffMin: 5000, backoffMin: 5000,
backoffMax: 30000 backoffMax: 30000,
}); });
``` ```
**Example** **Example**
@ -86,8 +86,8 @@ const client = new acme.Client({
accountKey: 'Private key goes here', accountKey: 'Private key goes here',
externalAccountBinding: { externalAccountBinding: {
kid: 'YOUR-EAB-KID', kid: 'YOUR-EAB-KID',
hmacKey: 'YOUR-EAB-HMAC-KEY' hmacKey: 'YOUR-EAB-HMAC-KEY',
} },
}); });
``` ```
<a name="AcmeClient+getTermsOfServiceUrl"></a> <a name="AcmeClient+getTermsOfServiceUrl"></a>
@ -145,7 +145,7 @@ https://datatracker.ietf.org/doc/html/rfc8555#section-7.3
Create a new account Create a new account
```js ```js
const account = await client.createAccount({ const account = await client.createAccount({
termsOfServiceAgreed: true termsOfServiceAgreed: true,
}); });
``` ```
**Example** **Example**
@ -153,7 +153,7 @@ Create a new account with contact info
```js ```js
const account = await client.createAccount({ const account = await client.createAccount({
termsOfServiceAgreed: true, termsOfServiceAgreed: true,
contact: ['mailto:test@example.com'] contact: ['mailto:test@example.com'],
}); });
``` ```
<a name="AcmeClient+updateAccount"></a> <a name="AcmeClient+updateAccount"></a>
@ -174,7 +174,7 @@ https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.2
Update existing account Update existing account
```js ```js
const account = await client.updateAccount({ const account = await client.updateAccount({
contact: ['mailto:foo@example.com'] contact: ['mailto:foo@example.com'],
}); });
``` ```
<a name="AcmeClient+updateAccountKey"></a> <a name="AcmeClient+updateAccountKey"></a>
@ -218,8 +218,8 @@ Create a new order
const order = await client.createOrder({ const order = await client.createOrder({
identifiers: [ identifiers: [
{ type: 'dns', value: 'example.com' }, { type: 'dns', value: 'example.com' },
{ type: 'dns', value: 'test.example.com' } { type: 'dns', value: 'test.example.com' },
] ],
}); });
``` ```
<a name="AcmeClient+getOrder"></a> <a name="AcmeClient+getOrder"></a>
@ -452,7 +452,7 @@ Revoke certificate with reason
```js ```js
const certificate = { ... }; // Previously created certificate const certificate = { ... }; // Previously created certificate
const result = await client.revokeCertificate(certificate, { const result = await client.revokeCertificate(certificate, {
reason: 4 reason: 4,
}); });
``` ```
<a name="AcmeClient+auto"></a> <a name="AcmeClient+auto"></a>
@ -479,7 +479,7 @@ Auto mode
Order a certificate using auto mode Order a certificate using auto mode
```js ```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}); });
const certificate = await client.auto({ const certificate = await client.auto({
@ -491,14 +491,14 @@ const certificate = await client.auto({
}, },
challengeRemoveFn: async (authz, challenge, keyAuthorization) => { challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
// Clean up challenge here // Clean up challenge here
} },
}); });
``` ```
**Example** **Example**
Order a certificate using auto mode with preferred chain Order a certificate using auto mode with preferred chain
```js ```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}); });
const certificate = await client.auto({ const certificate = await client.auto({
@ -507,7 +507,7 @@ const certificate = await client.auto({
termsOfServiceAgreed: true, termsOfServiceAgreed: true,
preferredChain: 'DST Root CA X3', preferredChain: 'DST Root CA X3',
challengeCreateFn: async () => {}, challengeCreateFn: async () => {},
challengeRemoveFn: async () => {} challengeRemoveFn: async () => {},
}); });
``` ```
<a name="Client"></a> <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 Create a Certificate Signing Request
```js ```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}); });
``` ```
**Example** **Example**
Certificate Signing Request with both common and alternative names 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 ```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
keySize: 4096, keySize: 4096,
commonName: 'test.example.com', commonName: 'test.example.com',
altNames: ['foo.example.com', 'bar.example.com'] altNames: ['foo.example.com', 'bar.example.com'],
}); });
``` ```
**Example** **Example**
Certificate Signing Request with additional information Certificate Signing Request with additional information
```js ```js
const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com', altNames: ['test.example.com'],
country: 'US', country: 'US',
state: 'California', state: 'California',
locality: 'Los Angeles', locality: 'Los Angeles',
organization: 'The Company Inc.', organization: 'The Company Inc.',
organizationUnit: 'IT Department', organizationUnit: 'IT Department',
emailAddress: 'contact@example.com' emailAddress: 'contact@example.com',
}); });
``` ```
**Example** **Example**
@ -270,8 +271,9 @@ Certificate Signing Request with ECDSA private key
const certificateKey = await acme.crypto.createPrivateEcdsaKey(); const certificateKey = await acme.crypto.createPrivateEcdsaKey();
const [, certificateRequest] = await acme.crypto.createCsr({ const [, certificateRequest] = await acme.crypto.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}, certificateKey); }, certificateKey);
```
<a name="createAlpnCertificate"></a> <a name="createAlpnCertificate"></a>
## createAlpnCertificate(authz, keyAuthorization, [keyPem]) ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code> ## 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 ```js
const alpnKey = await acme.crypto.createPrivateEcdsaKey(); const alpnKey = await acme.crypto.createPrivateEcdsaKey();
const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey); const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey);
```
<a name="isAlpnCertificateAuthorizationValid"></a> <a name="isAlpnCertificateAuthorizationValid"></a>
## isAlpnCertificateAuthorizationValid(certPem, keyAuthorization) ⇒ <code>boolean</code> ## 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 Create a Certificate Signing Request
```js ```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({ const [certificateKey, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}); });
``` ```
**Example** **Example**
Certificate Signing Request with both common and alternative names 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 ```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({ const [certificateKey, certificateRequest] = await acme.forge.createCsr({
keySize: 4096, keySize: 4096,
commonName: 'test.example.com', commonName: 'test.example.com',
altNames: ['foo.example.com', 'bar.example.com'] altNames: ['foo.example.com', 'bar.example.com'],
}); });
``` ```
**Example** **Example**
Certificate Signing Request with additional information Certificate Signing Request with additional information
```js ```js
const [certificateKey, certificateRequest] = await acme.forge.createCsr({ const [certificateKey, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com', altNames: ['test.example.com'],
country: 'US', country: 'US',
state: 'California', state: 'California',
locality: 'Los Angeles', locality: 'Los Angeles',
organization: 'The Company Inc.', organization: 'The Company Inc.',
organizationUnit: 'IT Department', organizationUnit: 'IT Department',
emailAddress: 'contact@example.com' emailAddress: 'contact@example.com',
}); });
``` ```
**Example** **Example**
@ -253,5 +254,5 @@ Certificate Signing Request with predefined private key
const certificateKey = await acme.forge.createPrivateKey(); const certificateKey = await acme.forge.createPrivateKey();
const [, certificateRequest] = await acme.forge.createCsr({ const [, certificateRequest] = await acme.forge.createCsr({
commonName: 'test.example.com' altNames: ['test.example.com'],
}, certificateKey); }, certificateKey);

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

@ -135,8 +135,7 @@ module.exports = async () => {
/* Finalize order */ /* Finalize order */
const [key, csr] = await acme.crypto.createCsr({ const [key, csr] = await acme.crypto.createCsr({
commonName: '*.example.com', altNames: ['example.com', '*.example.com'],
altNames: ['example.com'],
}); });
const finalized = await client.finalizeOrder(order, csr); 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 */ /* Create CSR */
const [key, csr] = await acme.crypto.createCsr({ const [key, csr] = await acme.crypto.createCsr({
commonName: 'example.com', altNames: ['example.com'],
}); });
/* Certificate */ /* 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}`); log(`Creating CSR for ${WILDCARD_DOMAIN}`);
const [key, csr] = await acme.crypto.createCsr({ const [key, csr] = await acme.crypto.createCsr({
commonName: WILDCARD_DOMAIN, altNames: [WILDCARD_DOMAIN, `*.${WILDCARD_DOMAIN}`],
altNames: [`*.${WILDCARD_DOMAIN}`],
}); });
log(`Ordering certificate for ${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 */ /* Create CSR */
log(`Creating CSR for ${servername}`); log(`Creating CSR for ${servername}`);
const [key, csr] = await acme.crypto.createCsr({ const [key, csr] = await acme.crypto.createCsr({
commonName: servername, altNames: [servername],
}); });
/* Order certificate */ /* 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 */ /* Create CSR */
log(`Creating CSR for ${servername}`); log(`Creating CSR for ${servername}`);
const [key, csr] = await acme.crypto.createCsr({ const [key, csr] = await acme.crypto.createCsr({
commonName: servername, altNames: [servername],
}); });
/* Order certificate */ /* Order certificate */

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

@ -2,7 +2,7 @@
"name": "acme-client", "name": "acme-client",
"description": "Simple and unopinionated ACME client", "description": "Simple and unopinionated ACME client",
"author": "nmorsman", "author": "nmorsman",
"version": "5.3.0", "version": "5.3.1",
"main": "src/index.js", "main": "src/index.js",
"types": "types/index.d.ts", "types": "types/index.d.ts",
"license": "MIT", "license": "MIT",
@ -15,23 +15,23 @@
"types" "types"
], ],
"dependencies": { "dependencies": {
"@peculiar/x509": "^1.9.7", "@peculiar/x509": "^1.10.0",
"asn1js": "^3.0.5", "asn1js": "^3.0.5",
"axios": "^1.6.5", "axios": "^1.7.2",
"debug": "^4.1.1", "debug": "^4.1.1",
"node-forge": "^1.3.1" "node-forge": "^1.3.1"
}, },
"devDependencies": { "devDependencies": {
"@types/node": "^20.11.5", "@types/node": "^20.12.12",
"chai": "^4.4.1", "chai": "^4.4.1",
"chai-as-promised": "^7.1.1", "chai-as-promised": "^7.1.2",
"eslint": "^8.56.0", "eslint": "^8.57.0",
"eslint-config-airbnb-base": "^15.0.0", "eslint-config-airbnb-base": "^15.0.0",
"eslint-plugin-import": "^2.29.1", "eslint-plugin-import": "^2.29.1",
"jsdoc-to-markdown": "^8.0.0", "jsdoc-to-markdown": "^8.0.1",
"mocha": "^10.2.0", "mocha": "^10.4.0",
"nock": "^13.5.0", "nock": "^13.5.4",
"tsd": "^0.30.4" "tsd": "^0.31.0"
}, },
"scripts": { "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", "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 * ```js
* const client = new acme.Client({ * const client = new acme.Client({
* directoryUrl: acme.directory.letsencrypt.staging, * 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', * accountUrl: 'Optional account URL goes here',
* backoffAttempts: 10, * backoffAttempts: 10,
* backoffMin: 5000, * backoffMin: 5000,
* backoffMax: 30000 * backoffMax: 30000,
* }); * });
* ``` * ```
* *
@ -81,8 +81,8 @@ const defaultOpts = {
* accountKey: 'Private key goes here', * accountKey: 'Private key goes here',
* externalAccountBinding: { * externalAccountBinding: {
* kid: 'YOUR-EAB-KID', * 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 * @example Create a new account
* ```js * ```js
* const account = await client.createAccount({ * const account = await client.createAccount({
* termsOfServiceAgreed: true * termsOfServiceAgreed: true,
* }); * });
* ``` * ```
* *
@ -163,7 +163,7 @@ class AcmeClient {
* ```js * ```js
* const account = await client.createAccount({ * const account = await client.createAccount({
* termsOfServiceAgreed: true, * termsOfServiceAgreed: true,
* contact: ['mailto:test@example.com'] * contact: ['mailto:test@example.com'],
* }); * });
* ``` * ```
*/ */
@ -200,7 +200,7 @@ class AcmeClient {
* @example Update existing account * @example Update existing account
* ```js * ```js
* const account = await client.updateAccount({ * 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({ * const order = await client.createOrder({
* identifiers: [ * identifiers: [
* { type: 'dns', value: 'example.com' }, * { type: 'dns', value: 'example.com' },
* { type: 'dns', value: 'test.example.com' } * { type: 'dns', value: 'test.example.com' },
* ] * ],
* }); * });
* ``` * ```
*/ */
@ -638,7 +638,7 @@ class AcmeClient {
* ```js * ```js
* const certificate = { ... }; // Previously created certificate * const certificate = { ... }; // Previously created certificate
* const result = await client.revokeCertificate(certificate, { * const result = await client.revokeCertificate(certificate, {
* reason: 4 * reason: 4,
* }); * });
* ``` * ```
*/ */
@ -666,7 +666,7 @@ class AcmeClient {
* @example Order a certificate using auto mode * @example Order a certificate using auto mode
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com' * altNames: ['test.example.com'],
* }); * });
* *
* const certificate = await client.auto({ * const certificate = await client.auto({
@ -678,14 +678,14 @@ class AcmeClient {
* }, * },
* challengeRemoveFn: async (authz, challenge, keyAuthorization) => { * challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
* // Clean up challenge here * // Clean up challenge here
* } * },
* }); * });
* ``` * ```
* *
* @example Order a certificate using auto mode with preferred chain * @example Order a certificate using auto mode with preferred chain
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com' * altNames: ['test.example.com'],
* }); * });
* *
* const certificate = await client.auto({ * const certificate = await client.auto({
@ -694,7 +694,7 @@ class AcmeClient {
* termsOfServiceAgreed: true, * termsOfServiceAgreed: true,
* preferredChain: 'DST Root CA X3', * preferredChain: 'DST Root CA X3',
* challengeCreateFn: async () => {}, * 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 * @example Create a Certificate Signing Request
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({ * 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 * @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 * ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({ * const [certificateKey, certificateRequest] = await acme.forge.createCsr({
* keySize: 4096, * keySize: 4096,
* commonName: 'test.example.com', * 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 * @example Certificate Signing Request with additional information
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.forge.createCsr({ * const [certificateKey, certificateRequest] = await acme.forge.createCsr({
* commonName: 'test.example.com', * altNames: ['test.example.com'],
* country: 'US', * country: 'US',
* state: 'California', * state: 'California',
* locality: 'Los Angeles', * locality: 'Los Angeles',
* organization: 'The Company Inc.', * organization: 'The Company Inc.',
* organizationUnit: 'IT Department', * 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 certificateKey = await acme.forge.createPrivateKey();
* *
* const [, certificateRequest] = await acme.forge.createCsr({ * const [, certificateRequest] = await acme.forge.createCsr({
* commonName: 'test.example.com' * altNames: ['test.example.com'],
* }, certificateKey); * }, 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 * @example Create a Certificate Signing Request
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ * 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 * @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 * ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* keySize: 4096, * keySize: 4096,
* commonName: 'test.example.com', * 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 * @example Certificate Signing Request with additional information
* ```js * ```js
* const [certificateKey, certificateRequest] = await acme.crypto.createCsr({ * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com', * altNames: ['test.example.com'],
* country: 'US', * country: 'US',
* state: 'California', * state: 'California',
* locality: 'Los Angeles', * locality: 'Los Angeles',
* organization: 'The Company Inc.', * organization: 'The Company Inc.',
* organizationUnit: 'IT Department', * 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 certificateKey = await acme.crypto.createPrivateEcdsaKey();
* *
* const [, certificateRequest] = await acme.crypto.createCsr({ * const [, certificateRequest] = await acme.crypto.createCsr({
* commonName: 'test.example.com' * altNames: ['test.example.com'],
* }, certificateKey); * }, certificateKey);
* ```
*/ */
exports.createCsr = async (data, keyPem = null) => { exports.createCsr = async (data, keyPem = null) => {
@ -516,6 +518,7 @@ exports.createCsr = async (data, keyPem = null) => {
* ```js * ```js
* const alpnKey = await acme.crypto.createPrivateEcdsaKey(); * const alpnKey = await acme.crypto.createPrivateEcdsaKey();
* const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey); * const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey);
* ```
*/ */
exports.createAlpnCertificate = async (authz, keyAuthorization, keyPem = null) => { 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 () => { it('should generate certificate signing request', async () => {
[, testCsr] = await acme.crypto.createCsr({ commonName: testDomain }, await createKeyFn()); [, testCsr] = await acme.crypto.createCsr({ commonName: testDomain }, await createKeyFn());
[, testCsrAlpn] = await acme.crypto.createCsr({ commonName: testDomainAlpn }, await createKeyFn()); [, testCsrAlpn] = await acme.crypto.createCsr({ altNames: [testDomainAlpn] }, await createKeyFn());
[, testCsrWildcard] = await acme.crypto.createCsr({ commonName: testDomainWildcard }, await createKeyFn()); [, testCsrWildcard] = await acme.crypto.createCsr({ altNames: [testDomainWildcard] }, await createKeyFn());
}); });
it('should resolve certificate issuers [ACME_CAP_ALTERNATE_CERT_ROOTS]', async function () { 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 () => { it('should order wildcard certificate', async () => {
const [, csr] = await acme.crypto.createCsr({ const [, csr] = await acme.crypto.createCsr({
commonName: testWildcardDomain, altNames: [testWildcardDomain, `*.${testWildcardDomain}`],
altNames: [`*.${testWildcardDomain}`],
}, await createKeyFn()); }, await createKeyFn());
const cert = await testClient.auto({ const cert = await testClient.auto({