Coking Plant, Zeche Zollverein, Essen

#acme4j

Access alternate certificates with acme4j

On January 11 2021, Let's Encrypt will change the default intermediate certificate from the cross-sign IdenTrust DST Root X3 certificate to their own ISRG Root X1 certificate.

The good news: The ISRG certificate is widely trusted by browsers by now, so the transition will be unnoticed by most users.

The bad news: The ISRG certificate is not included in Android devices before "Nougat" 7.1. These devices will show an error when trying to access sites that are signed with the new intermediate certificate. According to Let's Encrypt, stunning 34% of the Android devices out there shall be affected.

To mitigate the problem, Let's Encrypt provides an alternate certificate that is still cross-signed with the IdenTrust DST Root X3 certificate. If you have a web service that is accessed by a relevant number of older Android devices, you may want to use that alternate certificate. It will be available until September 29 2021. The IdenTrust DST Root X3 certificate itself will expire after that date, so this is a hard limit. Let's hope that the problem is going to be solved on Android side in time.

As acme4j fully implements the RFC 8555, it is easy to change your code so it will use the alternate certificate. Based on the acme4j example, this code block will use the first alternate certificate if present, and falls back to the main certificate if not:

Certificate certificate = order.getCertificate();
certificate = certificate.getAlternateCertificates().stream()
        .findFirst()
        .orElse(certificate);

Remember to remove the workaround after September 29 2021 January 2024, so you won't accidentally use other alternate certificates that may become available in the future.

PS: getAlternateCertificates() was added to the latest acme4j v2.11. If you have an older version, fear not: you just need to have a Login object, so you can bind the alternate certificate yourself. This is how it would look like in the example client:

Login login = session.login(acct.getLocation(), userKeyPair);

Certificate certificate = order.getCertificate();
certificate = certificate.getAlternates().stream()
        .map(login::bindCertificate)
        .findFirst()
        .orElse(certificate);

UPDATE: Let's Encrypt found a way to extend the Android compatibility until January 2024. However, this extension may only work for Android devices. To quote the article:

The new cross-sign will be somewhat novel because it extends beyond the expiration of DST Root CA X3. This solution works because Android intentionally does not enforce the expiration dates of certificates used as trust anchors.

How acme4j handles POST-as-GET requests

In the latest ACME draft 15, Let's Encrypt introduced POST-as-GET requests. It is a breaking change that is not downward compatible to previous drafts.

This brought me into an uncomfortable position. While the Pebble server enforces the use of POST-as-GET, other servers don't support it yet, like the Let's Encrypt server. For this reason, acme4j needs to support both the pre-draft-15 GET requests and the post-draft-15 POST-as-GET requests. Luckily I have found a solution that is totally transparent to the user, at least as long as no other ACME server is used.

This is how acme4j v2.4 works:

  • If you connect to Boulder via an acme://letsencrypt.org URI, acme4j falls back to a compatibility mode that still sends GET requests. Let's Encrypt has announced a sunset date for GET requests on November 1st, 2019. You are safe to use acme4j v2.4 (and older versions) up to this date.
  • If you connect to a Pebble server via an acme://pebble URI, the new POST-as-GET requests are used.
  • If you connect to a different server implementation via http: or https: URI, acme4j sends POST-as-GET requests now. This is likely going to fail at runtime, if the server you connect to does not support draft-15 yet.
  • As a temporary workaround, you can add a postasget=false parameter to the server URI (e.g. https://localhost:14000/dir?postasget=false) to make acme4j enter the fallback mode and send GET requests again.

As soon as Let's Encrypt supports POST-as-GET on their production servers, I will remove the fallback mode from acme4j again. It just clutters the code, and I also have no proper way to test it after that.

Hint: Before updating acme4j, always have a look at the migration guide. It will show you where you can expect compatibility issues.