github
/
certd
mirror of https://github.com/certd/certd
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
certd/packages/core/acme-client/docs/client.md

17 KiB
Raw Blame History

Classes

AcmeClient

AcmeClient

Objects

Client : object

ACME client

AcmeClient

AcmeClient

Kind: global class

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