V2Design

Version 2 Design

The next version of mod_md will have two major new features:

1. ACMEv2 (wildcards, tls-alpn challenge)
2. OCSP Stapling (alternative to mod_ssl)

This page describes what the features will mean for the users of Apache httpd. You are encouraged to give feedback on them in the issues I created for ACMEv2 and OCSPv2.

ACMEv2 Support

Version 1 of mod_md uses version 1 of the ACME protocol. That is the version that Let's Encrypt(LE) started with and it existed before the standardisation of ACME at the IETF in RFC 8555. The standard became known as ACMEv2.

There are subtle differences between the procotols where mod_md needs to adapt. From a user's point of view they are not very relevant, however:

• wildcard certificates from Let's Encrypt are only available via ACMEv2.
• TLS challenges will only be available in version 2.

wildcard certificates

Let's Encrypt offers wildcard certificates since January 2018. But only via ACMEv2 and only when the challenge dns-01 is used. This is not really a protocol restriction, but a policy by LE. Other CAs could handle that differently, but for LE it is so.

The challenge method dns-01 requires, as the name cleverly implies, that you have ownership of the domain in question via the DNS system. A sub-record of the domain needs to show a specific challenge value (that varies every time).

Apache mod_md will provide a way for you to configure a command for this. It will be invoked with setup or teardown, the domain name and the challenge value. Some DNS providers have already started to offer APIs for such manipulations, you have to ask them about this.

Or you may run your own DNS server. There are blogs on how to set this up only for your ACME challenges. Google and duckduckgo are your friends.

tls challenges

The ACMEv1 protocol originally had a TLS challenge method (by that I mean LE opens a TLS connection against your Apache and expects certain things), but common setups at shared hosting providers made it possible to steal domain certificates from other users. So that was then quickly disabled for most users.

And that left only http-01 challenges available to users. Which means your Apache has to listen on port 80 for outside requests. Some people do not want that for various reasons and had been rather sad when TLS based challenges disappeared.

A new TLS challenge was invented named tls-alpn-01 which overcomes the previous weakness and that is used by LE in ACMEv2 and, as @cpu pointed out, ACMEv1. But 1.x mod_md does not support it. This will then also be available in mod_md version 2.

OCSP Stapling

OCSP Stapling is available in the Apache web server for quite some time, built into the mod_ssl module itself. That implementation has several weaknesses, mainly in the area of reliability. If the OCSP responder at a CA you use becomes unresponsive at the wrong moment, your Apache will run out of valid OCSP answers and browsers will refuse to connect people to your domain.

Some recap: OCSP is a cryptographic proof that the CA, which issued your certificate, still vouches for it. And that proof is valid for a rather short period of time. Could be 3 days, for example. Your Apache sends this proof together with the certificate to the browser. The browser checks that certificate and proof match and that the proof has not expired. Only then it will continue.

The current implementation in Apache gets a new OCSP proof when it has no valid one. Should the OCSP responder not answer (service outage, sharks eating cables, etc.), it has nothing to send back to users. Your site becomes de facto unavailable. This is happening and not a theoretical problem.

In mod_md version 2, an alternate OCSP implementation will be made available. As with certificates, it will scan all domains that require OCSP answer and check availability and expiration time. And as with certificates, it will renew OCSP answer ahead of time by a configurable percentage of lifetime. Say an answer is valid for 3 days and the renewal is set a 30%, mod_md would start contacting the CA one day before expiration. That would mean an OCSP outage of almost 24 hours will not affect your site.

Also, OCSP responses in mod_md will be stored in the file system and survive server restarts.

The new OCSP stapling implementation will be available as an alternative to the existing one in mod_ssl. Because we want to ship this in an Apache 2.4.x release that needs to stay backward compatible. Also, a new implementation may have a bug or two, so sites admins may want to enable it in a controlled way, for a chosen number of their domains at first.

The new OCSP stapling will use existing configuration of mod_md. For example, the proxy settings will apply.