Yumei
Yumei is FreeGateway’s ACME certificate management daemon. It obtains and renews X.509 (TLS) certificates automatically for any daemon that uses them, including HTTPS and IMAPS servers, and it works on a single server or across a cluster of geographically distributed servers. Yumei is written in C++ for FreeBSD and runs on your own hardware.
One renewal tool for all your daemons
Yumei supports every daemon that uses X.509 certificates, not only HTTPS. Its configuration file tells it, for each daemon, where to place the renewed certificate and how to restart or reload the daemon, so renewal needs no manual steps. FreeGateway’s own projects rely on it: Kojo, DTS and Kaigi all use Yumei to keep their certificates current.
Yumei runs just as well on its own. A configuration option puts it in standalone mode, so a single server can use it too.
The problem: renewal behind GeoDNS
What sets Yumei apart is that it can renew certificates for a hostname served by a cluster of geographically distributed servers, which ordinary ACME clients cannot do.
A globally distributed service, such as a website or a mail server, often runs on many servers that all answer to one hostname, such as www.example.com, with GeoDNS sending each user to the nearest server. That breaks ordinary certificate renewal.
When a server asks a certificate authority (CA) such as Let’s Encrypt for a certificate for that hostname, the CA must verify that the request is genuine. It does so by issuing a challenge: the requesting server must make a unique token available at a well-known URL for that hostname. The CA then looks up the hostname in DNS, connects to the server IP address it gets back, and checks for the token. With GeoDNS, the IP address the CA gets back depends on where the CA is, so the connection goes to whichever server is nearest to the CA, which is not necessarily the server that asked. A renewal requested by the server in Tokyo can end up being validated against the server in Toronto, which has never seen the token, so the challenge fails.
The CA’s check is also not a single connection. The CA may connect several times, from different places, and GeoDNS can send each connection to a different server. Even if the first connection happens to reach the right server, the others may not, so every server the CA reaches must be able to answer the challenge.
The solution: the cluster renews together
Yumei runs on every server in the cluster. It designates one server, the source, to start the renewal, and shares everything about the transaction, including its state and the challenge tokens, with all the other servers, the replicas. Whichever server the CA reaches can answer the challenge, so the CA sees a single server at a single IP address. When the certificate is issued, Yumei distributes the certificate and its private key to every server in the cluster.
The servers talk to each other over Yumei’s own peer-to-peer channel, built on the Sodium cryptographic library and pre-shared public keys. This channel is independent of TLS, so renewing a certificate never depends on the certificates being renewed.
If the source server fails, an administrator can designate any replica as the new source. Automatic failover is planned for a later release.
HTTP-01 only, by design
Yumei uses only the ACME HTTP-01 challenge, which is served from the /.well-known/ URI path defined in RFC 8615. This is deliberate. DNS is often the least reliable part of a distributed system, particularly when GeoDNS is involved, so Yumei does not depend on DNS records or DNS-based challenges to prove that you control a hostname.
About the name
Yumei (有名) is the Japanese word for “famous” or “well known”, a nod to the /.well-known/ path that ACME uses.