acme_client 2.0.0

ACME client which allows you to obtain a HTTPS Certificate from any ACME CA such as Lets Encrypt.

Dart Acme Client

An ACME V2 compatible client written in Dart.

Table of Contents

• Dart Acme Client
  • Table of Contents
  • Preamble
  • Install
    • pubspec.yaml
  • Import
  • Acme Client
    • Client Setup
  • Applying for Certificate Issuance
    • Place Order
    • Fetch Authorization Data
    • Get Challenge For Authorization
    • dns-persist-01
    • Self Test
    • Trigger Validation
    • Finalize Order
    • Fetch Certificate
  • Changelog
  • Copyright and license

Preamble

As this package is written in pure Dart, it can be used on all platforms on which dart is currently running. This includes the use of frameworks like Flutter, Angular Dart and many more. This package can also be used for command line tools or rest services compiled with dart2native.

Note: Feel free to contribute by creating pull requests or file an issue for bugs, questions and feature requests.

Warning: Let's Encrypt production enforces rate limits. While developing or testing, prefer AcmeConnection.staging or local Pebble rather than the production endpoint. Repeated failed experiments against production can temporarily block further certificate issuance for the same account, domain, or set of domains. See Let's Encrypt's rate limit documentation before running automated tests or retries against production.

Recommendation: If your CA supports dns-persist-01, prefer it over dns-01 and http-01. It gives you a stable delegated DNS validation record that can be published once and then reused for both initial issuance and renewals with the same ACME account.

Install

pubspec.yaml

Update pubspec.yaml and add the following line to your dependencies.

dependencies:
  acme_client: ^2.0.0

Import

Import the package with :

import 'package:acme_client/acme_client.dart';

Acme Connection

This is a simple ACME written in Dart based on the RFC 8555. The client should be able to communicate with every ACME server that is based on the mentioned RFC including Let's Encrypt.

Connection Setup

Create an AcmeConnection and either generate fresh AcmeAccountCredentials or restore previously persisted credentials.

  const connection = AcmeConnection(
    baseUrl: 'https://acme-server.com',
  );

  final credentials = AcmeAccountCredentials.generate(
    acceptTerms: true,
    contacts: ['mailto:[e-mail]'],
  );

• AcmeConnection.baseUrl = The ACME directory URL, such as Pebble's https://localhost:14000/dir.
• AcmeConnection(..., dio: ...) = Optional advanced transport override. Most production callers should not pass this. It is mainly useful for tests or special environments such as local Pebble, custom TLS trust, or proxies.
• AcmeAccountCredentials.privateKeyPem = The private key in PEM format.
• AcmeAccountCredentials.publicKeyPem = The public key in PEM format.
• AcmeAccountCredentials.acceptTerms = Accept terms and condition while creating / fetching an account.
• AcmeAccountCredentials.contacts = A list of email addresses. Each address should have the format mailto:[e-mail].

If you already persisted credentials, restore them with:

  final credentials = AcmeAccountCredentials.fromJson(jsonString);

If you are using the default Let's Encrypt production endpoint, you can omit the connection argument entirely.

Standard connection presets are available for common cases:

  const production = AcmeConnection.production;
  const staging = AcmeConnection.staging;
  const pebble = AcmeConnection.pebble();

Fetch the existing account:

  var account = await Account.fetch(credentials);

To force creation of a new account instead of looking up an existing one:

  var account = await Account.create(credentials);

To persist the account identity inputs needed to resume later operations such as renewals, round-trip AcmeAccountCredentials:

  final jsonString = credentials.toJson(pretty: true);

  // Persist `jsonString`, then later restore it.
  final restoredCredentials = AcmeAccountCredentials.fromJson(jsonString);
  final restoredAccount = await Account.fetch(
    restoredCredentials,
    connection: connection,
  );

Credential Storage

Store the private key outside your repository. This file identifies the ACME account, so it should be treated as a secret and restricted to the process or user that needs it.

• Linux: store it under a per-user config path such as ~/.config/acme_client/account-credentials.json with restrictive permissions like 0600, owned by the service user.
• macOS: prefer Keychain if you already use it, otherwise store the file under the user's home directory with user-only permissions.
• Windows: prefer DPAPI or Credential Manager if available, otherwise store the file under %APPDATA% with user-only ACLs.
• Containers and servers: mount the credentials from a secret store or locked-down config volume rather than baking them into the image or repository.
• Source control: never commit the ACME private key or embed it in source files, examples, or checked-in test fixtures.

For a complete load-or-create example, see example/fetch_account_example.dart.

If you already have an attached Account, you can derive the same credentials:

  final credentials = account.toAccountCredentials();

Certificate Credentials

Certificate issuance uses a separate keypair from the ACME account keypair. CertificateCredentials packages the certificate private key, public key, and CSR for a specific certificate request.

  final certificateCredentials = CertificateCredentials.generate(
    identifiers: [DomainIdentifier('example.com')],
  );

• CertificateCredentials.privateKeyPem = The certificate private key in PEM format.
• CertificateCredentials.publicKeyPem = The certificate public key in PEM format.
• CertificateCredentials.csrPem = The CSR in PEM format for finalizing the ACME order.
• CertificateCredentials.identifiers = The DNS names encoded into the CSR.

Persist certificate credentials the same way you persist account credentials: outside the repository, with restrictive permissions. For a complete load-or-create example, see example/certificate_credentials_example.dart.

Applying for Certificate Issuance

Place Order

Placing an order is done by asking the account for the challenge workflow you want to use and passing the list of domain identifiers.

  var newOrder = await account.createOrderForHttp(
    identifiers: [DomainIdentifier('example.com')],
  );

Fetch Authorization Data

To inspect what challenge types the CA offers for a given identifier, use the separate discovery API.

  var availableChallenges = await account.discoverAvailableChallenges(
    identifier: DomainIdentifier('example.com'),
  );

For a complete discovery workflow, see example/discovery_example.dart.

Get Challenge For Authorization

For each returned authorization there are multiple challenges. You can use one of these challenges to prove control over one identifier and fulfill the authorization request.

  var httpOrder = await account.createOrderForHttp(
    identifiers: [DomainIdentifier('example.com')],
  );
  var httpAuthorization = await httpOrder.getAuthorization(
    DomainIdentifier('example.com'),
  );
  var httpChallenge = httpAuthorization.getChallenge();
  var httpProof = httpChallenge.buildProof();

  var dnsOrder = await account.createOrderForDns(
    identifiers: [DomainIdentifier('example.com')],
  );
  var dnsAuthorization = await dnsOrder.getAuthorization(
    DomainIdentifier('example.com'),
  );
  var dnsChallenge = dnsAuthorization.getChallenge();
  var dnsProof = dnsChallenge.buildProof();

Complete typed examples are available in:

• example/http_challenge_example.dart
• example/dns_challenge_example.dart
• example/dns_persist_example.dart
• example/http_renewal_example.dart
• example/dns_renewal_example.dart
• example/dns_persist_renewal_example.dart

dns-persist-01

dns-persist-01 is the recommended challenge type when your CA supports it. Unlike dns-01, it is designed for a long-lived delegated TXT record, so the same DNS setup can usually be reused across both initial issuance and renewal.

Note: as of 2026-04 dns-persist-01 has not been released into production. It is anticipated it will be available by late 2026.

If the ACME server offers dns-persist-01, fetch the authorizations for the order, ask the order for the concrete DnsPersistChallenge, and then build the TXT record from that challenge.

  var order = await account.createOrderForDnsPersist(
    identifiers: [DomainIdentifier('example.com')],
  );
  var domainIdentifier = DomainIdentifier('example.com');
  var authorization = await order.getAuthorization(domainIdentifier);
  var challenge = authorization.getChallenge();
  var persistProof = challenge.buildProof();

  print(persistProof.toBindString());

The returned DnsPersistChallengeProof contains the TXT record to publish at _validation-persist.<fqdn>.

Treat that TXT record as tied to your ACME account identity.

• Keep using the same persisted AcmeAccountCredentials if you want to keep reusing the same dns-persist-01 record.
• If you create a different ACME account, the accounturi=... part of the TXT record changes and you must publish a new record before validating again.
• Rotating CertificateCredentials or generating a new CSR does not by itself change the dns-persist-01 TXT record. The certificate keypair is separate from the ACME account.
• If the domain name changes, or if the CA returns different proof parameters, publish the new TXT record returned by challenge.buildProof().

Self Test

It is recommended to check in advance that the published proof is publicly visible before asking the CA to validate it. Call selfTest() on the challenge. Via the maxAttempts parameter you can increase or decrease the amount of time it will try to observe the proof. The default is 15.

selfTest() reuses the bound AcmeConnection only for shared HTTP client configuration and logging. It does not contact the CA.

Note: The DNS self test uses the Google DNS Rest API to fetch the resource records.

  var self = await challenge.selfTest(); // DnsChallenge
  if (!self) {
    print('Selftest failed, no DNS record found');
  }

  var self = await challenge.selfTest(); // HttpChallenge
  if (!self) {
    print('Selftest failed, no file found or content missmatch');
  }

The same challenge.selfTest() flow also applies to dns-persist-01.

Trigger Validation

To tell the ACME server to check the challenge, call validate() on the challenge itself. This will trigger the validation and check every 4 seconds for the authorization status to change to valid. Via the maxAttempts parameter you can increase or decrease the amount of time it will poll the status. The default is 15.

  var authValid = await challenge.validate();
  if (!authValid) {
    print('Authorization failed, exit');
  }

Finalize Order

If every authorization has the status valid, check that the order is ready and then finalize it by sending the CSR from your CertificateCredentials to the ACME server. The CSR is automatically formatted according to the RFC rules (base64url encoded without headers).

var ready = await newOrder.isReady();
if (!ready) {
  print('Order is not ready');
}

final certificateCredentials = CertificateCredentials.generate(
  identifiers: [DomainIdentifier('example.com')],
);

await newOrder.finalize(certificateCredentials);

Fetch Certificate

A list of certificates can then be fetched directly from the finalized order.

var certs = await newOrder.getCertificates();

Renewals

For renewals, keep using the same AcmeAccountCredentials. That is your ACME account identity and should normally be long-lived.

If you are using dns-persist-01, keeping the same ACME account is especially important because the persistent TXT record is tied to that account's URI. If you switch to a different account later, you must publish the new TXT record before validation can succeed.

For CertificateCredentials, you have two valid choices:

• Reuse the same stored CertificateCredentials if you want the renewed certificate to keep the same private key.
• Generate new CertificateCredentials for the renewal if you want certificate key rotation.

In both cases, the CSR must match the identifiers on the renewal order. If the set of names changes, generate new CertificateCredentials for that new set of identifiers.

Renewal examples are available in:

• example/http_renewal_example.dart
• example/dns_renewal_example.dart
• example/dns_persist_renewal_example.dart

Changelog

Pebble Integration

For local integration testing with Pebble and challtestsrv, see tool/pebble/README.md. The repository includes:

• a local Docker Compose harness
• a Pebble config file
• end-to-end acquisition and renewal tests for http-01, dns-01, and dns-persist-01 in test/pebble_integration_test.dart

For live Let's Encrypt staging inspection and dns-persist-01 system tests, see tool/le-staging/README.md. The staging test reads its settings from an untracked YAML file at tool/le-staging/le-staging.local.yaml.

For a detailed changelog, see the CHANGELOG.md file

Copyright and license

MIT License

Copyright (c) 2021 Ephenodrom

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.