Configuration / TLS and certificates

TLS and certificates

This page shows how to give your sites certificates, either automatically through ACME or from files you manage, and how to change the TLS defaults when you have a reason to. It also covers client certificates, keeping private keys out of the worker process, and what Encrypted Client Hello support exists today.

What you get without configuring anything

  • TLS 1.3 only. TLS 1.0 and 1.1 cannot be enabled at all. TLS 1.2 is off unless you turn it on for a site.
  • Post-quantum hybrid key exchange first. The server offers X25519MLKEM768, which combines classic X25519 with the ML-KEM-768 post-quantum algorithm, so recorded traffic stays protected even if large quantum computers arrive later. Clients that do not support it fall back to X25519, P-256 or P-384.
  • HTTP/3, HTTP/2 and HTTP/1.1 on every HTTPS listener unless you set protocols on listen.

Every HTTPS listener needs a certificate source: an acme block, a cert and key pair, or the key daemon. Without one, check warns with W015 and miraserve run refuses to start unless you pass --dev-tls.

Automatic certificates with ACME

ACME is the protocol Let's Encrypt and other certificate authorities use to issue certificates automatically. Add an acme block with a contact email and MiraServe requests, stores and renews a certificate for every host name in your site blocks:

server {
    listen ":443"
    listen ":80" redirect-https=#true

    tls {
        acme {
            email "[email protected]"
        }
    }
}

site "example.com" "www.example.com" {
    root "/var/www/example"
}

This config passes check --strict. Before you start it, make sure the DNS records for every host name point at this server and that the ports below are reachable from the internet.

Challenge types

The certificate authority must confirm that you control each host name. That confirmation is called a challenge:

  • "tls-alpn-01" (default) is answered inside the TLS handshake on port 443. Port 443 must be reachable from the internet.
  • "http-01" is answered over plain HTTP on port 80. You need a listener with redirect-https=#true on port 80; it answers challenge requests under /.well-known/acme-challenge/ before it redirects anything else.
  • "dns-01" is rejected with E106. MiraServe has no DNS provider integration yet.

Because only HTTP and TLS challenges are available, MiraServe cannot obtain wildcard certificates. Wildcard hosts such as "*.example.com" and the name localhost are skipped by ACME; give a wildcard site its own cert and key.

Short-lived certificates and ARI

With short-lived on (the default), MiraServe asks the certificate authority for its shortlived profile, which issues certificates valid for about six days. A short lifetime limits how long a stolen key stays useful. If the authority does not offer that profile, MiraServe logs this and accepts its normal lifetime.

ARI (ACME Renewal Information, RFC 9773) is a way for the certificate authority to tell each server when to renew, for example earlier than planned after a mass revocation. With ari on (the default), MiraServe follows that advice. Independently of ARI, it renews when less than a third of the lifetime remains, and never later than 24 hours before expiry for short-lived certificates or 72 hours for normal ones.

Where ACME state lives

The ACME account key and issued certificates are stored with owner-only permissions in the directory given by miraserve run --acme-dir. Without that option the directory is .miraserve-acme inside the directory the server was started from. The Linux packages pass --acme-dir /var/lib/miraserve/acme. Use an absolute path, and keep this directory between restarts; otherwise every restart orders new certificates and can hit the authority's rate limits. miraserve check --fs --acme-dir /var/lib/miraserve/acme confirms that the directory is writable.

To test against the Let's Encrypt staging service first, set directory. The URL must use https://:

tls {
    acme {
        email "[email protected]"
        challenge "http-01"
        directory "https://acme-staging-v02.api.letsencrypt.org/directory"
    }
}

Certificates from files

To use certificates you obtain elsewhere, give PEM file paths. A cert and key in server.tls are the default for every site; a tls block in a site overrides them for that site's host names:

server {
    listen ":443"

    tls {
        cert "/etc/miraserve/certs/default.crt"
        key "/etc/miraserve/certs/default.key"
    }
}

site "example.com" {
    tls {
        cert "/etc/miraserve/certs/example.com.crt"
        key "/etc/miraserve/certs/example.com.key"
    }
    root "/var/www/example"
}

site "example.org" {
    root "/var/www/example-org"
}

The certificate file should contain the full chain, leaf first. cert and key must always be set together (E105 otherwise). After you replace the files, run miraserve reload. miraserve check --fs confirms that the files are readable and that each certificate and key belong together, and miraserve cert inspect prints a certificate's names and validity dates.

Development certificates

For local testing there are two options. Neither certificate is trusted by browsers, so never use them in production.

  • miraserve run --dev-tls creates a self-signed certificate in memory at startup when no other certificate is configured.
  • miraserve cert generate-dev writes a self-signed ECDSA P-256 certificate and key to files. The names localhost, 127.0.0.1 and ::1 are always included. Existing files are not overwritten unless you add --force.
$ miraserve cert generate-dev --hosts example.test --cert dev-cert.pem --key dev-key.pem
OK: generated self-signed ECDSA P-256 dev certificate 'dev-cert.pem' and key 'dev-key.pem'

Allowing TLS 1.2 for one site

Some old clients cannot speak TLS 1.3. Allow TLS 1.2 only on the site that needs it:

site "legacy.example.com" {
    tls {
        compat-tls-1-2 #true
    }
    root "/var/www/legacy"
}

This produces warning W002, so it fails check --strict on purpose. A TLS 1.2 connection that asks for any other site gets 421 Misdirected Request. Post-quantum key exchange exists only in TLS 1.3, so TLS 1.2 connections do not get it. Setting min-version "1.2" in server.tls opens TLS 1.2 for every site; prefer the per-site setting.

Client certificates (mTLS)

With mutual TLS (mTLS), the client also presents a certificate. Set client-ca to a PEM bundle of the certificate authorities you trust for client certificates, either in server.tls for all sites or in a site's tls block. A site's own client-ca replaces the global one for that site:

site "deploy.example.com" {
    tls {
        client-ca "/etc/miraserve/certs/deploy-clients-ca.pem"
    }
    root "/var/www/deploy"
}

Know exactly what this does today:

  • The server asks for a client certificate, but a client without one can still connect and use the site.
  • A client that does present a certificate must present one that chains to a configured CA, or the connection fails.
  • The verified identity is used by the publishing endpoint with auth="mtls" (see Publishing). client-ca alone does not restrict who can read a site.

For certificates that MiraServe presents to a backend, see upstream TLS.

Keeping private keys out of the worker

By default (key-isolation "in-process") the process that handles requests also holds the private keys. With key-isolation "split-daemon", the keys live in a separate process, miraserve keyd, which runs as its own user and only signs handshakes on request. A memory-disclosure bug in the request-handling process then cannot reveal the keys.

server {
    listen ":443"

    tls {
        key-isolation "split-daemon"
        keyd-socket "/run/miraserve-keyd/keyd.sock"
        cert "/etc/miraserve/certs/example.com.crt"
        key "/etc/miraserve/keys/example.com.key"
    }
}

site "example.com" {
    root "/var/www/example"
}

The key daemon reads the same config to find the key files, and allows only the worker's user to connect:

$ sudo -u miraserve-keyd miraserve keyd --config /etc/miraserve/conf/miraserve.kdl --socket /run/miraserve-keyd/keyd.sock --allow-peer-user miraserve

Rules the checker enforces:

  • split-daemon requires keyd-socket, and keyd-socket requires split-daemon (E105).
  • A keyd-socket of the form "tcp://…" must use a loopback address such as 127.0.0.1. Use a shared secret file with TCP; see Deployment.
  • ACME needs "in-process", because the worker must hold the keys it orders. With split-daemon, an acme block is an error (E106) unless every site already has a manual cert and key.
  • For TLS 1.2 sites, the key daemon signs TLS 1.2 handshakes only for keys whose site enables compat-tls-1-2 (or with miraserve keyd --allow-tls12).

Encrypted Client Hello

Encrypted Client Hello (ECH) hides the requested host name from network observers. MiraServe cannot terminate ECH yet, because the TLS library it uses has no server-side ECH support. Until that changes, the feature is switched off on purpose so that you cannot publish DNS records the server cannot honour:

  • ech #true, ech-public-name and ech-rotate in server.tls are rejected with E107. ech #false or leaving them out is fine.
  • miraserve cert ech-generate refuses to run:
$ miraserve cert ech-generate --public-name edge.example.com
error: `miraserve cert ech-generate` is disabled because server-side ECH decryption is not yet supported by rustls 0.23; refusing to print a DNS HTTPS ECH record that the server cannot decrypt

Reference

server.tls

DirectiveDefaultMeaning
min-version"1.3"Lowest TLS version for all sites: "1.3" or "1.2". "1.2" gives W002.
pqc-hybrid#trueOffer X25519MLKEM768 first. #false gives W001.
cert, keynoneDefault certificate chain and private key (PEM).
client-canoneCA bundle (PEM) for verifying client certificates.
key-isolation"in-process""in-process" or "split-daemon".
keyd-socketnoneUnix socket path or "tcp://127.0.0.1:port" of the key daemon. Only with split-daemon.
acme { … }noneAutomatic certificates; see below.
ech, ech-public-name, ech-rotate#false, none, "1h"Not supported yet; setting them is an error.

server.tls.acme

DirectiveDefaultMeaning
emailrequiredContact address for the ACME account.
challenge"tls-alpn-01""tls-alpn-01" or "http-01". "dns-01" is rejected.
short-lived#trueAsk for the authority's short-lived certificate profile.
ari#trueFollow the authority's renewal advice (RFC 9773).
directoryLet's Encrypt productionACME directory URL; must be https://.

site.tls

DirectiveDefaultMeaning
compat-tls-1-2#falseAllow TLS 1.2 for this site's host names. Gives W002.
pqc-hybridglobal valueOverride post-quantum key exchange for this site. #false gives W001.
cert, keyglobal valuesCertificate chain and key for this site.
client-caglobal valueCA bundle for client certificates on this site.

Pitfalls

  • Lost ACME state. In a container or under a service manager, the default .miraserve-acme directory may be on a temporary or read-only filesystem. Always pass --acme-dir pointing at persistent storage.
  • Port 80 closed with http-01. The challenge only works through a redirect-https listener on port 80 that the internet can reach.
  • Wildcard sites with ACME. Wildcard hosts get no ACME certificate. Without a manual certificate for them, clients see a certificate error.
  • Expecting client-ca to lock a site. It does not block visitors without a certificate. Restrict access by other means until you have checked the behaviour described above.
  • Turning on TLS 1.2 globally. min-version "1.2" weakens every site to help one. Use compat-tls-1-2 on the site that needs it.