Certificates

A certificate in aethercert is the definition of an identity plus everything needed to keep it valid: which names it covers, which authority signs it, where it is installed, and when it should be renewed. The control plane owns that definition; the agent owns the key.

Managed and external certificates#

The certificate list holds two kinds of record, and they behave very differently.

Everything below applies to managed certificates unless it says otherwise. External certificates have their own section further down.

Identity: common name and SANs#

A certificate carries one common name and any number of subject alternative names. Modern clients validate against the SAN list, so a certificate covering example.com and www.example.com needs both - the common name alone is not enough.

With a verified domain selected on the certificate job, you enter only the label (app) and the domain is appended. That is not just convenience: it makes it impossible to produce a hostname the selected domain's DNS-01 credentials could not cover, which is one of the more common ways an issuance fails.

Wildcards (*.example.com) require DNS-01 validation, which requires a DNS provider connected to the domain. See Domains and DNS validation.

Key types#

The key is generated fresh on the agent for every issuance, including every renewal.

The Free plan is limited to EC-256. Some AD CS templates enforce a minimum RSA size of their own, which overrides your choice at the CA.

Statuses#

A failed job is retried automatically up to three times before it is marked failed. See Troubleshooting for what the common failures mean.

Renewal#

Auto-renew is on by default. The control plane queues the renewal job a configurable number of days before the not-after date - 30 by default - and the agent then does exactly what it did at first issuance: new key, new CSR, validation, deployment.

Two things follow from that:

• Renewal is a reissue, not an extension. The new certificate has a new key and a new serial. Anything that pinned the old fingerprint needs to stop doing that.
• The renewal window is your safety margin. With 30 days, a failing renewal has 30 days of retries and 30 days of your attention before anything breaks. Shortening it saves nothing and removes the margin.

Renew now on a certificate queues a renewal immediately, regardless of the schedule. Use it after fixing whatever made the last attempt fail, rather than waiting for the next scheduled attempt.

Editing and reissuing#

Editing a certificate - changing its SANs, its authority, its deploy target - reissues it with the new configuration. There is no way to change the names on a certificate already signed; a different set of names is a different certificate.

Moving a certificate to a different agent is the same story: delete it and create it against the other agent. If several servers need the same certificate, that is what agent groups are for, rather than moving one certificate repeatedly.

Revocation and deletion#

These are different actions with different consequences.

• Revoke calls the authority's real revocation operation - ACME revokeCert, or the internal REST equivalent. The certificate stops being trusted by clients that check revocation. Use it when a key may have been exposed.
• Delete removes the record from aethercert. The certificate itself keeps working wherever it is installed until it expires. Use it when you no longer want to manage the certificate, not when you need it to stop working.

Neither reaches onto the host to remove a deployed file or a store entry. Nothing aethercert does retracts a certificate a server is already serving.

External certificates#

Agents from version 0.8.0 also inventory certificates that were already installed on their host - whoever put them there - and report them. They appear under Manage > Certificates with the source External, next to the ones aethercert issued.

The point is coverage. A certificate imported by hand two years ago, one issued by a tool that has since been retired, one inherited with the server: all of them get an expiry date and a warning before they lapse.

What is scanned#

The operating system's own trust store is deliberately skipped. Those are hundreds of root CAs nobody installed for that host to serve with, and listing them would bury the certificates that matter.

What you get#

Everything inside the certificate: subject and issuer broken out attribute by attribute, every SAN by kind, validity, serial, SHA-256 and SHA-1 fingerprints, public key and signature algorithms, key usage and extended key usage, basic constraints, key identifiers, policy OIDs, OCSP/CRL/AIA endpoints, and the certificate's own PEM. Plus where the agent found it, and whether the host holds a private key for it.

Limits and tuning#

External certificates are read-only. aethercert has neither their private key nor their issuance configuration, so there is nothing to renew, revoke or edit. Remove one from the host and it disappears from the list at the next scan. To take one over, create an ordinary certificate job for the same names.

A scan runs at most every six hours and uploads only when something changed, so it adds essentially nothing to an agent's traffic. Two settings in the agent's config.json tune it: