ACMEv2 Support in Apache

ACME Versions

ACME (or automated certificate management environment) is the name of the protocol that clients talk to Let's Encrypt (LE). They started to design and implement this initially as vital part of their mission for themselves. This was then named version 1, or ACMEv1.

Very early on, they also pushed ACME for standardization in the IETF and the results of that are now known as ACMEv2.

The main differences between these two protocol versions are:

• Interoperable Standard: ACMEv2 is implemented by more Certificate Authorities (CAs) than Let's Encrypt, giving users more options on how and where they want to secure their web sites with.
• ACMEv1 is frozen. All future innovation will happen in version 2 based services. LE will keep the v1 endpoint around for some time, but otherwise not touch it.
• The LE ACMEv2 endpoint offers the new tls-alpn-01 challenge method. This allows to obtain certificates by only using port 443 which allows sites to close the port 80 for good - should they want to.

mod_md and ACMEv2

As a rule of thumb: the 1.x versions of the module talk ACMEv1 to Let's Encrypt. The 2.x version will in addition also talk ACMEv2.

Initially, using ACMEv2 in Apache will require an opt-in by you:

Without this, the first 2.x versions of mod_md will continue to use the ACMEv1 endpoint at https://acme-v01.api.letsencrypt.org/directory.

With enough positive feedback from users, some future 2.x version will switch the default. If you are uncomfortable with this, you can configure the ACMEv1 endpoint explicitly already today, so future version of mod_md will not surprise you.

However, the automatic switch is in my opinion a service for the net, once we can establish the quality of its implementation.

Enabling tls-alpn-01

For this ACME challenge to work, you need not only a new mod_md, but also a patched mod_ssl module. For the Apache development trunk, this changes has already been applied, but there is not 2.4.x release with the change out - yet.

If patching and compiling mod_ssl yourself is not your cup of tea, then you'll need to wait for someone to make it available to you. Maybe a PPA will come that you are willing to install.

Assuming you managed to get a patched mod_ssl, you will need to enable an additional protocol in your server:

That last one, acme-tls/1, is the new protocol. This is how an ACMEv2 server, such as LE, will contact your server. If your server is not configured to accept this protocol, it will deny the connection attempt from LE and the ACMEv2 challenge fails. That means you will not get a certificate.

If you allow it with the configuration above, mod_md will detect this and use the tls-alpn-01 challenge method, when offered by the ACME server.

From version 1.99.4 on, the tls-alpn-01 challenge is the most preferred one and will be selected over any other (You can configure your own preference, but this is the default).

When this works for you, your server will no longer need port 80 to obtain new certificates.

Testing ACMEv2

If you want to test ACMEv2 on your server with minimal impact to your running domains, I describe a setup for a limited trial.

Choose a domain that you own but do not use for anything. That can be a subdomain of one you *do* use. Let's say you have something.net, when you could take acmev2-trial.something.net for this test.

Then point a DNS record for this domain to your server and add a virtual host with this ServerName for port 443 (and maybe also one for port 80 if you leave the tls-alpn-01 configuration out of this).

Then configure mod_md for this domain:

Restart the server and Apache will use ACMEv2 for only this one domain and leave the rest as before. This staging endpoint will not give you certificates that your browser likes - but they will be certificates from Let's Encrypt. LE calls staging their test environment that everyone can use from the outside.

When everything is working with staging, you can change the URL to the real one, https://acme-v02.api.letsencrypt.org/directory, and get valid certificates.

Summary

I hope you'll be happy with the changes and continuing improvements of Let's Encrypt support in your Apache Web Server. Feedback appreciated.