#tlsd

tlsd is a TLS certificate daemon protocol. It allows multiple clients to request TLS certificates and private keys to serve TLS connections.

#Motivation

Because getting a certificate from ACME requires listening on either port 80 or port 443, services like mail servers can't request one automatically (this would conflict with a web server). ACME also supports DNS challenges, but this isn't a viable solution as it requires the ACME client to support individually all existing DNS provider APIs.

Right now there are two main solutions used by users when setting up a TLS service:

• Using an utility like Certbot and cron jobs: this requires users to setup a Certbot or a cron job to retrieve and update the certificate. Forgetting to setup the cron job results in expired certificates. Additionally, if the cron job runs when the ACME infrastructure is down, the certificate won't be renewed.
• Using a daemon like Caddy: only Caddy can obtain certificates. Other services need to either be Caddy plugins or ask the user to configure Caddy to obtain a certificate.

None of these solutions allow services to provide zero-configuration TLS support.

tlsd aims to fix this issue by establishing a standard certificate protocol. Services like mail servers connect to a certificate daemon (which can be either a standalone daemon or a web server like Caddy). They register a domain name, and get an event when a new certificate is available. The certificate daemon is responsible for keeping certificates up-to-date.

#Protocol

tlsd uses Varlink. The interface definition is available at internal/fremersiontlsd/fr.emersion.tlsd.varlink.

#Usage

First choose and start a certificate daemon (see below). Then clients can connect and request certificates:

varlink call -m fr.emersion.tlsd.Register '{"domain":"example.org"}'

#tlsd-acme

tlsd-acme is a daemon that handles ACME negociation (e.g. with Let's Encrypt) and maintains fresh certificates.

By default, it listens on port 8080. Your HTTP server needs to be configured to forward ACME http-01 challenges to tlsd.

go build ./cmd/tlsd-acme
./tlsd-acme

Example NGINX config:

location /.well-known/acme-challenge/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
}

#tlsd-fs

tlsd-fs is a daemon that reads certificates from the filesystem. It can be used with existing tools like certbot or lego.

go build ./cmd/tlsd-fs
./tlsd-fs

#tlsd-caddy (TBD)

tlsd-caddy is a tlsd plugin for Caddy 2. Certificate retrieval and maintenance is offloaded to Caddy.

#License

MIT