Certificates & PKI

Athena runs its own internal certificate authority. On first start the server generates a self-signed Root CA and stores it on disk; from then on every agent that enrolls is issued a per-machine X.509 client certificate signed by that CA, and the server's own gRPC TLS certificate is signed by it too. There is nothing to buy, no public CA to reach, and no internet dependency — the whole trust chain lives inside your network, which is exactly what an air-gapped deployment needs.

The Root CA#

When the PKI subsystem initializes, the server looks for a CA certificate and private key on disk. If they exist it loads them. If they are missing on a fresh install (no agents enrolled and no encrypted secrets stored yet) it creates a new self-signed Root CA. If they are missing on a server that already has agents or stored secrets, the server refuses to start rather than silently minting a replacement. The generated CA is a standard certificate authority:

The CA is stored under the server's PKI directory (see the CertificatesPath setting below). The CA private key is generated and kept on the server with restricted permissions and never leaves it — only the public CA certificate is ever handed out to agents.

The CA key also protects stored secrets#

The Root CA private key does more than sign agent certificates. Athena derives the encryption key for its stored secrets from it, so the same key protects:

• passwords in the Credential Vault;
• per-agent RustDesk access passwords;
• BitLocker recovery passwords, and the startup PINs set by BitLocker policies or per-agent PIN overrides (when the BitLocker module is in use).

In practice this means the database and the PKI are a matched pair. A database paired with a different CA still holds those secrets, but nothing can decrypt them, and the enrolled agents' certificates no longer chain to the server's CA. Back up the PKI directory together with the database, and restore them together — on the virtual appliance, back up /data/athena and /data/pki together. See Data Directories & Backup and Database Restore & Recovery.

If the CA is missing at startup#

If the CA certificate or its private key is missing when the server starts, Athena first checks whether the database depends on the old CA, meaning it holds any agent or any encrypted secret from the list above.

• Nothing depends on it (a genuinely fresh install): a new Root CA is created as usual.
• Something depends on it: the server refuses to start. It logs a fatal message beginning "Root CA files are missing … but the database holds agents and/or encrypted secrets. Refusing to start" and exits with code 1, instead of coming up with an empty trust chain.

This usually means the database came back without its PKI, for example a restore that skipped the PKI directory, or a storage volume that failed to attach. The fix is to restore the PKI directory from the same backup as the database and start the server again. The log message tells you exactly what is missing.

Per-agent certificates#

During enrollment (after the registration token is validated) the server generates a fresh RSA key pair for the agent and issues it a client certificate signed by the Root CA. The certificate has:

• Subject CN=<hostname>, O=Athena Agent, with the hostname also set as a DNS Subject Alternative Name.
• Enhanced Key Usage = Client Authentication (OID 1.3.6.1.5.5.7.3.2) — these certificates authenticate the agent to the server, not the other way around.
• An RSA key of the configured leaf key size (default 2048-bit), SHA-256 signature, and a validity of the configured agent certificate lifetime (default 30 days).

The issuance response contains the certificate, its private key, and the CA certificate. The private key is returned to the agent only once at issuance — the server stores just the public certificate (PEM), thumbprint, serial number, and validity dates in its database. Issuing a certificate also stamps the agent's CertificateThumbprint and CertificateExpires fields.

How a certificate is validated#

On every authenticated agent connection the server validates the presented certificate. A certificate is accepted only when all of these hold:

• It chains to — and was issued by — this server's Root CA (issuer matches the CA subject).
• The current time is within its ValidFrom…ValidUntil window.
• It is present in the server database and not revoked.

Otherwise validation fails with a specific reason — no certificate provided, invalid format, not signed by the CA, expired, not yet valid, revoked, agent not found, or certificate not found. Revocation is checked against the database (the server tracks revoked certificates itself), so a revoked certificate stops working immediately.

Renewal & auto-renewal#

Because agent certificates are short-lived (30 days by default), they are renewed continuously. An agent renews by presenting its current certificate to POST api/pki/renew (certificate authentication, not a JWT). The server verifies the current certificate belongs to that agent, issues a brand-new certificate, and then revokes the old one with the reason "Renewed".

Automatic renewal is enabled by default (EnableAutoRenewal), driven by two settings: certificates are renewed once they are within 7 days of expiry (AutoRenewBeforeDays), and the check runs every 6 hours (AutoRenewalCheckIntervalHours). In normal operation you never renew agent certificates by hand.

Revoking certificates#

An administrator can revoke all certificates for an agent with POST api/pki/agents/{agentId}/revoke and a reason. Revocation:

• Marks every non-revoked certificate for that agent as revoked, recording the reason, who revoked it, and when.
• Sets the agent's status to Revoked.
• Disconnects the agent if it is currently connected, and writes an audit entry.

A revoked agent can no longer authenticate and must re-register to rejoin the fleet. Revoked certificates remain queryable via GET api/pki/revoked for the audit trail.

Extending vs. regenerating the CA#

The Root CA has a long life, but it will eventually approach expiry. There are two very different operations for renewing it — choose carefully:

What regenerate does to stored secrets#

Because the stored secrets depend on the CA key, regenerating the CA carries them over to the new key. Regenerate (from Settings → Security → Certificate, POST api/pki/ca/regenerate, or Invoke-AthenaCACertificateRegenerate) works in this order:

1. Every stored secret is read with the current key first. If any secret cannot be decrypted, or secrets exist but the server cannot read them at all, regenerate is refused and nothing changes: same CA, same key, same agent certificates. Over REST the call returns HTTP 500 with a message starting "CA NOT regenerated" that says how many secrets were affected; in the console you see "Failed to regenerate Root CA certificate".
2. The new CA is created.
3. In a single database transaction, every agent certificate is revoked (reason "CA certificate regenerated - all certificates invalidated") and every stored secret is re-encrypted under the new key.
4. The new CA goes live immediately. The old CA certificate and key are kept beside it as .bak files, and the server uses the new key without a restart.

Two audit events are written: VaultReencrypted (the description gives the number of secrets re-encrypted) followed by CARegenerated (the number of agent certificates revoked). Saved credentials, RustDesk passwords and BitLocker recovery passwords and PINs keep working after a regenerate. Only the agents need attention: they must re-enroll.

Monitoring expiry#

To stay ahead of renewals, list certificates expiring soon with GET api/pki/expiring?withinDays=7 (default 7 days). The CA's own metadata — subject, thumbprint, serial, key size, and validity dates — is available from GET api/pki/ca/info, which also flags the CA as expiring soon when it is within one year of expiry. In the console, the Root CA card lives under Settings → Security → Certificate.

Configuration#

PKI behavior is controlled by the Pki configuration section. The defaults are sensible for most deployments:

See Configuration for how to set these values.

Roles#

CA download and info (api/pki/ca, ca/download, ca/info) are anonymous — agents need them before they hold a certificate. Agent registration (api/pki/register) is gated by a valid registration token. Renewal (api/pki/renew) and my-certificates require the agent's own certificate authentication. Everything else is gated by a permission: pki.view to list an agent's certificates and view expiring or revoked certificates, pki.revoke to revoke an agent's certificates, and pki.manage to extend or regenerate the CA. Of the built-in roles, only Admin holds these permissions. Callers without the permission receive 403; unauthenticated callers receive 401. See Roles & Permissions and Permission Model & Role Bundles.

REST API#

PowerShell#

The Athena module ships cmdlets for the CA and certificate operations:

# Export the CA and push it to a domain via GPO (Windows .cer)
Save-AthenaCACertificate -Path "C:\pki\athena-root-ca.cer" -Format cer

# See what's expiring in the next two weeks
Get-AthenaExpiringCertificates -Days 14

# Revoke a decommissioned host's certificates
Revoke-AthenaAgentCertificate -AgentId $id -Reason "Decommissioned" -Force

See the PowerShell Module reference for full cmdlet details.