​

SSL/TLS Certificates

​

Certificate Sources

​

Let’s Encrypt (ACME)

​

How It Works

1. Set the proxy host’s SSL mode to letsencrypt in the admin UI
2. Aegis validates that the domain is configured as a proxy host (host policy check)
3. When a TLS handshake arrives for that domain, autocert requests a certificate from Let’s Encrypt
4. The HTTP-01 challenge is served on port 80 (the HTTP proxy listener handles /.well-known/acme-challenge/ paths)
5. The certificate is cached in the autocert cache directory (default .cache/ssl)
6. Renewal happens automatically before expiration

​

Requirements

• Port 80 must be reachable from the internet for HTTP-01 challenge validation
• The domain must resolve to the Aegis server’s public IP
• The proxy host must have ssl_mode set to letsencrypt

​

Configuration

# Start with custom SSL cache directory
AEGIS_SSL_CACHE_DIR=/var/lib/aegis/ssl aegis run

​

Cloudflare Origin CA

​

How It Works

1. Aegis generates a CSR (Certificate Signing Request) with the requested hostnames
2. The CSR is submitted to Cloudflare’s Origin CA API (/client/v4/certificates)
3. Cloudflare issues a signed certificate (valid up to 15 years)
4. Aegis stores the certificate and encrypted private key in SQLite
5. The certificate is loaded into the TLS configuration for SNI-based selection

​

Authentication Methods

​

Request Options

​

API Endpoint

POST /api/v1/certificates/cloudflare-origin

{
  "auth_method": "api_token",
  "api_token": "your-cloudflare-api-token",
  "hostnames": ["app.example.com", "*.example.com"],
  "request_type": "origin-rsa",
  "requested_validity": 5475
}

{
  "status": "created",
  "id": 1,
  "cloudflare_id": "cf-cert-id",
  "expires_on": "2041-03-23T00:00:00Z",
  "requested_zone": ""
}

​

Custom Certificate Upload

​

API Endpoint

POST /api/v1/certificates

{
  "domains": ["app.example.com"],
  "cert_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "key_pem": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
}

​

Validation

• The certificate and key must form a valid X.509 key pair
• The leaf certificate is parsed to extract the issuer, expiration, and subject
• The private key is encrypted with AES-256-GCM before storage

​

Assigning Certificates to Hosts

​

Let’s Encrypt

{
  "domain": "app.example.com",
  "ssl_mode": "letsencrypt",
  "force_https": true
}

​

Custom / Cloudflare Origin

• Inline PEM — provide ssl_cert_pem and ssl_key_pem directly in the host update (Aegis stores and encrypts them automatically)
• Certificate ID — reference an existing certificate by ssl_cert_id

{
  "domain": "app.example.com",
  "ssl_mode": "custom",
  "ssl_cert_id": 1,
  "force_https": true
}

​

SNI Certificate Selection

1. Host binding — if the proxy host has an ssl_cert_id, use that certificate
2. Domain match — check all stored custom certificates for a domain match
3. Autocert — attempt Let’s Encrypt certificate retrieval (for hosts with ssl_mode: letsencrypt)
4. Self-signed fallback — generate a self-signed certificate covering all configured domains

​

Private Key Encryption

• Key source — provided via AEGIS_SSL_KEY (64-char hex string) or auto-generated on first run
• Auto-generated keys are stored in the SQLite settings table
• Each key gets a unique random nonce (GCM nonce size)
• Decryption happens only when loading certificates into memory at startup or after a reload

​

Certificate Lifecycle

​

Host SSL Settings

​

API Reference

​

Certificate Object