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 are missing it creates a new self-signed Root CA; if they exist it loads them. 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.

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:

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 — listing an agent's certificates, revoking, viewing expiring/revoked certificates, and extending or regenerating the CA — requires the Admin role. Callers without Admin receive 403; unauthenticated callers receive 401. See Roles & Permissions.

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.