client.md

Classes

AcmeClient

AcmeClient

Objects

Client : object

ACME client

AcmeClient

AcmeClient

Kind: global class

• AcmeClient
  • new AcmeClient(opts)
  • .getTermsOfServiceUrl() ⇒ Promise.<(string|null)>
  • .getAccountUrl() ⇒ string
  • .createAccount([data]) ⇒ Promise.<object>
  • .updateAccount([data]) ⇒ Promise.<object>
  • .updateAccountKey(newAccountKey, [data]) ⇒ Promise.<object>
  • .createOrder(data) ⇒ Promise.<object>
  • .getOrder(order) ⇒ Promise.<object>
  • .finalizeOrder(order, csr) ⇒ Promise.<object>
  • .getAuthorizations(order) ⇒ Promise.<Array.<object>>
  • .deactivateAuthorization(authz) ⇒ Promise.<object>
  • .getChallengeKeyAuthorization(challenge) ⇒ Promise.<string>
  • .verifyChallenge(authz, challenge) ⇒ Promise
  • .completeChallenge(challenge) ⇒ Promise.<object>
  • .waitForValidStatus(item) ⇒ Promise.<object>
  • .getCertificate(order, [preferredChain]) ⇒ Promise.<string>
  • .revokeCertificate(cert, [data]) ⇒ Promise
  • .auto(opts) ⇒ Promise.<string>

new AcmeClient(opts)

Param	Type	Description
opts	object
opts.directoryUrl	string	ACME directory URL
opts.accountKey	buffer | string	PEM encoded account private key
[opts.accountUrl]	string	Account URL, default: null
[opts.externalAccountBinding]	object
[opts.externalAccountBinding.kid]	string	External account binding KID
[opts.externalAccountBinding.hmacKey]	string	External account binding HMAC key
[opts.backoffAttempts]	number	Maximum number of backoff attempts, default: 10
[opts.backoffMin]	number	Minimum backoff attempt delay in milliseconds, default: 5000
[opts.backoffMax]	number	Maximum backoff attempt delay in milliseconds, default: 30000

Example
Create ACME client instance

const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: 'Private key goes here',
});

Example
Create ACME client instance

const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: 'Private key goes here',
    accountUrl: 'Optional account URL goes here',
    backoffAttempts: 10,
    backoffMin: 5000,
    backoffMax: 30000,
});

Example
Create ACME client with external account binding

const client = new acme.Client({
    directoryUrl: 'https://acme-provider.example.com/directory-url',
    accountKey: 'Private key goes here',
    externalAccountBinding: {
        kid: 'YOUR-EAB-KID',
        hmacKey: 'YOUR-EAB-HMAC-KEY',
    },
});

acmeClient.getTermsOfServiceUrl() ⇒ Promise.<(string|null)>

Get Terms of Service URL if available

Kind: instance method of AcmeClient
Returns: Promise.<(string|null)> - ToS URL
Example
Get Terms of Service URL

const termsOfService = client.getTermsOfServiceUrl();

if (!termsOfService) {
    // CA did not provide Terms of Service
}

acmeClient.getAccountUrl() ⇒ string

Get current account URL

Kind: instance method of AcmeClient
Returns: string - Account URL
Throws:

• Error No account URL found

Example
Get current account URL

try {
    const accountUrl = client.getAccountUrl();
}
catch (e) {
    // No account URL exists, need to create account first
}

acmeClient.createAccount([data]) ⇒ Promise.<object>

Create a new account

https://datatracker.ietf.org/doc/html/rfc8555#section-7.3

Kind: instance method of AcmeClient
Returns: Promise.<object> - Account

Param	Type	Description
[data]	object	Request data

Example
Create a new account

const account = await client.createAccount({
    termsOfServiceAgreed: true,
});

Example
Create a new account with contact info

const account = await client.createAccount({
    termsOfServiceAgreed: true,
    contact: ['mailto:test@example.com'],
});

acmeClient.updateAccount([data]) ⇒ Promise.<object>

Update existing account

https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.2

Kind: instance method of AcmeClient
Returns: Promise.<object> - Account

Param	Type	Description
[data]	object	Request data

Example
Update existing account

const account = await client.updateAccount({
    contact: ['mailto:foo@example.com'],
});

acmeClient.updateAccountKey(newAccountKey, [data]) ⇒ Promise.<object>

Update account private key

https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.5

Kind: instance method of AcmeClient
Returns: Promise.<object> - Account

Param	Type	Description
newAccountKey	buffer | string	New PEM encoded private key
[data]	object	Additional request data

Example
Update account private key

const newAccountKey = 'New private key goes here';
const result = await client.updateAccountKey(newAccountKey);

acmeClient.createOrder(data) ⇒ Promise.<object>

Create a new order

https://datatracker.ietf.org/doc/html/rfc8555#section-7.4

Kind: instance method of AcmeClient
Returns: Promise.<object> - Order

Param	Type	Description
data	object	Request data

Example
Create a new order

const order = await client.createOrder({
    identifiers: [
        { type: 'dns', value: 'example.com' },
        { type: 'dns', value: 'test.example.com' },
    ],
});

acmeClient.getOrder(order) ⇒ Promise.<object>

Refresh order object from CA

https://datatracker.ietf.org/doc/html/rfc8555#section-7.4

Kind: instance method of AcmeClient
Returns: Promise.<object> - Order

Param	Type	Description
order	object	Order object

Example

const order = { ... }; // Previously created order object
const result = await client.getOrder(order);

acmeClient.finalizeOrder(order, csr) ⇒ Promise.<object>

Finalize order

https://datatracker.ietf.org/doc/html/rfc8555#section-7.4

Kind: instance method of AcmeClient
Returns: Promise.<object> - Order

Param	Type	Description
order	object	Order object
csr	buffer | string	PEM encoded Certificate Signing Request

Example
Finalize order

const order = { ... }; // Previously created order object
const csr = { ... }; // Previously created Certificate Signing Request
const result = await client.finalizeOrder(order, csr);

acmeClient.getAuthorizations(order) ⇒ Promise.<Array.<object>>

Get identifier authorizations from order

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5

Kind: instance method of AcmeClient
Returns: Promise.<Array.<object>> - Authorizations

Param	Type	Description
order	object	Order

Example
Get identifier authorizations

const order = { ... }; // Previously created order object
const authorizations = await client.getAuthorizations(order);

authorizations.forEach((authz) => {
    const { challenges } = authz;
});

acmeClient.deactivateAuthorization(authz) ⇒ Promise.<object>

Deactivate identifier authorization

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.2

Kind: instance method of AcmeClient
Returns: Promise.<object> - Authorization

Param	Type	Description
authz	object	Identifier authorization

Example
Deactivate identifier authorization

const authz = { ... }; // Identifier authorization resolved from previously created order
const result = await client.deactivateAuthorization(authz);

acmeClient.getChallengeKeyAuthorization(challenge) ⇒ Promise.<string>

Get key authorization for ACME challenge

https://datatracker.ietf.org/doc/html/rfc8555#section-8.1

Kind: instance method of AcmeClient
Returns: Promise.<string> - Key authorization

Param	Type	Description
challenge	object	Challenge object returned by API

Example
Get challenge key authorization

const challenge = { ... }; // Challenge from previously resolved identifier authorization
const key = await client.getChallengeKeyAuthorization(challenge);

// Write key somewhere to satisfy challenge

acmeClient.verifyChallenge(authz, challenge) ⇒ Promise

Verify that ACME challenge is satisfied

Kind: instance method of AcmeClient

Param	Type	Description
authz	object	Identifier authorization
challenge	object	Authorization challenge

Example
Verify satisfied ACME challenge

const authz = { ... }; // Identifier authorization
const challenge = { ... }; // Satisfied challenge
await client.verifyChallenge(authz, challenge);

acmeClient.completeChallenge(challenge) ⇒ Promise.<object>

Notify CA that challenge has been completed

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.1

Kind: instance method of AcmeClient
Returns: Promise.<object> - Challenge

Param	Type	Description
challenge	object	Challenge object returned by API

Example
Notify CA that challenge has been completed

const challenge = { ... }; // Satisfied challenge
const result = await client.completeChallenge(challenge);

acmeClient.waitForValidStatus(item) ⇒ Promise.<object>

Wait for ACME provider to verify status on a order, authorization or challenge

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.1

Kind: instance method of AcmeClient
Returns: Promise.<object> - Valid order, authorization or challenge

Param	Type	Description
item	object	An order, authorization or challenge object

Example
Wait for valid challenge status

const challenge = { ... };
await client.waitForValidStatus(challenge);

Example
Wait for valid authorization status

const authz = { ... };
await client.waitForValidStatus(authz);

Example
Wait for valid order status

const order = { ... };
await client.waitForValidStatus(order);

acmeClient.getCertificate(order, [preferredChain]) ⇒ Promise.<string>

Get certificate from ACME order

https://datatracker.ietf.org/doc/html/rfc8555#section-7.4.2

Kind: instance method of AcmeClient
Returns: Promise.<string> - Certificate

Param	Type	Default	Description
order	object		Order object
[preferredChain]	string	null	Indicate which certificate chain is preferred if a CA offers multiple, by exact issuer common name, default: null

Example
Get certificate

const order = { ... }; // Previously created order
const certificate = await client.getCertificate(order);

Example
Get certificate with preferred chain

const order = { ... }; // Previously created order
const certificate = await client.getCertificate(order, 'DST Root CA X3');

acmeClient.revokeCertificate(cert, [data]) ⇒ Promise

Revoke certificate

https://datatracker.ietf.org/doc/html/rfc8555#section-7.6

Kind: instance method of AcmeClient

Param	Type	Description
cert	buffer | string	PEM encoded certificate
[data]	object	Additional request data

Example
Revoke certificate

const certificate = { ... }; // Previously created certificate
const result = await client.revokeCertificate(certificate);

Example
Revoke certificate with reason

const certificate = { ... }; // Previously created certificate
const result = await client.revokeCertificate(certificate, {
    reason: 4,
});

acmeClient.auto(opts) ⇒ Promise.<string>

Auto mode

Kind: instance method of AcmeClient
Returns: Promise.<string> - Certificate

Param	Type	Description
opts	object
opts.csr	buffer | string	Certificate Signing Request
opts.challengeCreateFn	function	Function returning Promise triggered before completing ACME challenge
opts.challengeRemoveFn	function	Function returning Promise triggered after completing ACME challenge
[opts.email]	string	Account email address
[opts.termsOfServiceAgreed]	boolean	Agree to Terms of Service, default: false
[opts.skipChallengeVerification]	boolean	Skip internal challenge verification before notifying ACME provider, default: false
[opts.challengePriority]	Array.<string>	Array defining challenge type priority, default: ['http-01', 'dns-01']
[opts.preferredChain]	string	Indicate which certificate chain is preferred if a CA offers multiple, by exact issuer common name, default: null

Example
Order a certificate using auto mode

const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
    altNames: ['test.example.com'],
});

const certificate = await client.auto({
    csr: certificateRequest,
    email: 'test@example.com',
    termsOfServiceAgreed: true,
    challengeCreateFn: async (authz, challenge, keyAuthorization) => {
        // Satisfy challenge here
    },
    challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
        // Clean up challenge here
    },
});

Example
Order a certificate using auto mode with preferred chain

const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
    altNames: ['test.example.com'],
});

const certificate = await client.auto({
    csr: certificateRequest,
    email: 'test@example.com',
    termsOfServiceAgreed: true,
    preferredChain: 'DST Root CA X3',
    challengeCreateFn: async () => {},
    challengeRemoveFn: async () => {},
});

Client : object

ACME client

Kind: global namespace