TLS Configuration Reference

TLS and certificate management configuration for the Elide HTTP server.

Provides three modes of certificate provisioning:

1. Automatic ACME (auto = true, the default) — obtains and renews certificates automatically for every domain listed in ServerBlock.domains, using Let's Encrypt or a fallback CA. 2. Manual (certFile + keyFile) — uses static PEM certificate and key files that you provision and rotate yourself. 3. On-demand (onDemand) — issues certificates at TLS-handshake time for hostnames not known in advance. See OnDemandTls.

These modes can be combined: auto covers declared domains while onDemand handles dynamic hostnames.

See DnsChallenge for wildcard certificate support via DNS-01 and ClientAuth for mutual TLS (mTLS) client verification.

> This page is auto-generated from the PKL schema. See the guide for usage examples.

Types

TlsVersion

Minimum TLS protocol version accepted by listeners.

typealias TlsVersion = "1.2" | "1.3"

CipherSuitePreset

Named TLS cipher suite group applied during negotiation.

typealias CipherSuitePreset = "default" | "fips" | "legacy"

---

OnDemandTls

On-demand TLS issues a certificate at TLS-handshake time for hostnames that have not been pre-provisioned.

This avoids the need to enumerate all domains in config ahead of time, which is useful for multi-tenant platforms and wildcard-like setups. An authorization endpoint (ask) is strongly recommended to prevent abuse by arbitrary clients triggering certificate issuance.

ask

Authorization URL queried before issuing a certificate.

The server sends a GET request with a domain query parameter containing the requested hostname. A 200 OK response permits issuance; any other status code denies it. When null, all hostnames are permitted (use with caution).

maxPerWindow

Maximum number of certificates that may be issued per window.

When null, no rate limit is applied (not recommended in production).

burst

Burst allowance above maxPerWindow during short traffic spikes.

The effective limit becomes maxPerWindow + burst until the sliding window catches up. Default: 5.

window

Sliding window duration for the maxPerWindow rate limit.

Default: 1 hour.

---

DnsChallenge

DNS-01 ACME challenge configuration.

DNS-01 challenges prove domain ownership by creating a DNS TXT record. This is the only ACME challenge type that supports wildcard certificates (e.g., *.example.com). Use this when HTTP-01 challenges are not feasible (e.g., the server is not publicly reachable on port 80).

provider

DNS challenge provider that creates and cleans up TXT records.

config

Provider-specific key/value overrides.

Most providers read credentials from environment variables, so this mapping is typically empty. Use it for overrides such as a custom API endpoint, zone ID, or webhook secret.

propagationTimeout

Maximum time to wait for DNS TXT record propagation before the challenge is considered failed.

Default: 120 seconds.

pollInterval

How frequently to poll the DNS provider to check whether the TXT record has propagated.

Default: 5 seconds.

---

CertStorage

Persistent storage backend for certificates, OCSP staples, and ACME account keys.

path

Directory path for file-based certificate storage.

Linux/macOS: `~/.local/share/elide/certs`
Windows:     `%LOCALAPPDATA%\Elide\certs`

---

ClientAuth

Mutual TLS (mTLS) client-certificate authentication settings.

trustedCAs

Paths to PEM-encoded CA certificate files trusted for client certificate verification.

At least one CA file is required. Intermediate CAs should be included if clients present certificate chains.

required

Whether a valid client certificate is mandatory.

When true (default), connections without a valid client certificate are rejected at the TLS level. When false, a certificate is requested but the connection proceeds even if none is provided (useful for optional client identification).

---

TlsConfig

Top-level TLS configuration for the Elide HTTP server.

Controls certificate provisioning, protocol versions, cipher suites, OCSP stapling, and mutual TLS. Applies server-wide unless overridden at the server-block level via TlsBlockOverride.

Example (automatic ACME)

new TlsConfig {
  auto = true
  acmeEmail = "ops@example.com"
}

Example (manual certificate)

new TlsConfig {
  auto = false
  certFile = "/etc/ssl/example.com.pem"
  keyFile  = "/etc/ssl/example.com-key.pem"
}

auto

Enable automatic HTTPS via the ACME protocol.

When true (default), Elide obtains and renews certificates automatically for all domain names listed in ServerBlock.domains. The server must be reachable on port 80 (for HTTP-01 challenges) unless dnsChallenge is configured for DNS-01 challenges.

acmeCA

Primary ACME Certificate Authority directory URL.

`"https://acme-staging-v02.api.letsencrypt.org/directory"`

acmeCAFallback

Fallback ACME CA used when acmeCA is unreachable or returns an error.

Defaults to ZeroSSL. Set to null to disable fallback.

acmeEmail

Email address registered with the ACME CA.

Used for certificate expiry warnings and account recovery. Required by most public ACME CAs (Let's Encrypt, ZeroSSL).

onDemand

On-demand TLS configuration.

When set, certificates are issued at TLS-handshake time for hostnames not covered by ServerBlock.domains. When null (default), on-demand issuance is disabled. See OnDemandTls.

tailscale

Use the Tailscale certificate authority instead of a public ACME CA.

Requires tailscaled to be running and the machine to be enrolled in a Tailnet. Certificates are issued for the machine's Tailscale FQDN.

certFile

Path to a PEM-encoded certificate file for manual TLS provisioning.

When provided, this certificate is used instead of ACME for domains served from the root TLS config. Must be paired with keyFile.

keyFile

Path to the PEM-encoded private key file corresponding to certFile.

Required when certFile is set; ignored otherwise.

minVersion

Minimum TLS protocol version accepted by listeners.

cipherSuites

Named cipher-suite preset applied during TLS negotiation.

See CipherSuitePreset for available presets.

ocspStapling

Enable OCSP stapling.

When true (default), the server fetches and embeds OCSP responses in the TLS handshake, reducing client-side latency by eliminating a separate OCSP lookup.

storage

Persistent storage backend for certificates and ACME state.

See CertStorage for path configuration.

dnsChallenge

DNS-01 ACME challenge configuration.

When set (and auto = true), certificates are obtained via DNS TXT records instead of the default HTTP-01 challenge. Required for wildcard certificates. See DnsChallenge.

clientAuth

Mutual TLS (mTLS) client-certificate authentication.

Configures client certificate verification at the root TLS level. Per-server-block overrides can be set via TlsBlockOverride.clientAuth. See ClientAuth.

---