Skip to content

ACME client plugins

CertIntel plugins let an existing ACME client publish and remove DNS-01 challenge TXT values through CertIntel. The source repository records validation for all four clients; compatibility still depends on the host version and your environment. Choose the guide for your client:

Client Installation and configuration
simple-acme simple-acme guide
win-acme win-acme guide
Posh-ACME Posh-ACME guide
Certbot Certbot guide

Follow verified downloads before installing any package.

The ACME client continues to own certificate orders, private keys, storage, installation and renewal scheduling. No CertIntel Agent is needed. The plugins handle DNS validation only; add reporting scripts separately if you want check-ins and renewal results in CertIntel. Testing of the four DNS plugins does not imply that every optional reporting wrapper has been tested end-to-end.

Verify downloads

Use the signed release workflow introduced in plugin source version 0.1.1. This is a source baseline, not a claim that a particular version has been deployed. Legacy direct latest/*.dll, latest/*.ps1 and wheel URLs are retired by the publisher. Do not execute a downloaded installer or install a wheel before verification.

Obtain a trusted checkout of the CertIntel plugins repository, review its revision, and work from that repository's root. The verifier's trust keys must come from that trusted source, not from the same unauthenticated download being checked. On Windows:

# Choose simple-acme, win-acme, posh-acme, or certbot.
.\scripts\Get-CertIntelPackage.ps1 -Client simple-acme -Directory .\verified\simple-acme `
  -StatePath "$env:LOCALAPPDATA\CertIntel\Releases\simple-acme.json"
if (-not $?) { throw 'Release verification failed; do not use the downloaded files' }

The bootstrap pins the Authenticode certificate on the verifier before running it. The verifier authenticates an Ed25519-signed, time-limited manifest, then validates immutable URLs, exact sizes and hashes, rejects older releases using persistent state, and checks the client-specific signatures. Keep the protected state file between upgrades; deleting it weakens rollback protection.

For Linux/Unix Certbot, build the verifier from the same trusted source checkout using the Go version declared in release/go.mod:

cd release
go test ./...
go build -trimpath -o ../plugin-release ./cmd/plugin-release
cd ..
# Use an administrator-controlled state location that survives upgrades.
install -d -m 700 /opt/certintel-releases
./plugin-release fetch -client certbot -output ./verified/certbot \
  -state /opt/certintel-releases/certbot.json

Run subsequent installation only after a successful verifier exit. The Certbot wheel has a certificate-backed DSSE/in-toto attestation checked by this verifier; pip does not perform that authentication for you. Native DLLs, the Windows verifier and distributed PowerShell scripts use Authenticode.

The current signing certificate is self-signed. A pinned expected signer is different from public CA trust or SmartScreen reputation. Never disable signature checks, accept a different signer, or import an unverified certificate into a trust store just to clear a warning. A checksum downloaded beside an artifact detects corruption but does not independently authenticate its publisher.

See the source repository's verification contract for keys, expiry, rollback behavior and certificate-attestation details. If a manifest has expired, stop and obtain a new authorized release; do not turn back the clock.

Before you start

  1. In Delegated DNS-01, create a delegation for the certificate name. Save its UUID, update secret and full CNAME target.

  2. At your DNS provider, create the permanent CNAME supplied by CertIntel:

    _acme-challenge.example.com.  CNAME  YOUR-LABEL.dns01.certin.tel.

  3. Wait until the CNAME resolves publicly. With Cloudflare, use DNS only.

  4. Install the plugin and supply the delegation details using your client's guide. Use the update secret, or a CertIntel DNS API key explicitly granted access to the delegation. Reporting keys with renewals/checkins permissions are separate credentials.
  5. Test issuance and cleanup against a staging CA, then create a production order and test renewal under the account that will run the scheduler.

The API base defaults to https://api.certin.tel/api/v1. Any override must use HTTPS and include /api/v1.

example.com and *.example.com share one delegation. www.example.com needs its own exact mapping and CNAME. Mapping keys are certificate names without *. or _acme-challenge.; the generated CNAME target is not a certificate name.

Credentials and renewal

Client Where delegation configuration is kept
simple-acme / win-acme Native renewal settings with protected keys or host vault references; no separate JSON file
Posh-ACME Saved plugin arguments with SecureString credentials protected by Posh-ACME
Certbot Private JSON mapping file whose absolute path is saved in renewal configuration

Keep plugin files and credential paths available to the scheduled account. After rotating a delegation secret, update the corresponding saved credential and test renewal. Rotation does not change the delegation's UUID or permanent CNAME.

Delegation ownership

Use one issuing client/host per delegation. The plugins preserve other TXT values and remove their own, but the API replaces the whole TXT set and accepts at most two values. Local locks cannot coordinate another host, a native CertIntel Agent workflow, or dashboard edits. Avoid concurrent issuance against the same delegation, including staging tests during a production renewal.

If a crash leaves stale TXT values, confirm that no issuance is active before removing them in CertIntel and retrying. A CA may reuse valid authorizations, so successful renewal does not always publish a fresh challenge.