Prepare Android Apps for ISRG Let’s Encrypt Expiry of “DST Root CA X3” Cross-Signature

Starting January 21, 2021 and ending September 1, 2021, sites using TLS/SSL certificates issued by ISRG‘s Let’s Encrypt service will be transitioning to a certificate chain based on the ISRG Root X1 certificate instead of IdenTrust‘s DST Root X3. After the DST Root X3 certificate expiry on September 30, 2021, it will no longer be usable to bootstrap ISRG in legacy trusted root certificate stores.

This affects Android prior to 7.1.1.

Developers of Android apps can use Network Security Configuration to enable their apps to be compatible with sites using Let’s Encrypt after January 21, 2021.

1. Add android:networkSecurityConfig="@xml/network_security_config" as an attribute of the <application> tag in AndroidManifest.xml.
2. Create a res/xml/network_security_config.xml file with the following contents:

<?xml version="1.0" encoding="utf-8"?>

<network-security-config>
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="@raw/isrg_root_x2" />
            <certificates src="@raw/isrg_root_x1" />
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

3. Download ISRG Root X1 and store it in res/raw/isrg_root_x1.der
4. Download ISRG Root X2 and store it in res/raw/isrg_root_x2.der
5. If your app connects over cleartext in addition to TLS, change cleartextTrafficPermitted in the network_security_config.xml above to true.

Instead of adding ISRG’s roots to the existing system root store, you may be considering replacing it entirely with an up-to-date root store such as Mozilla Firefox‘s or Google Chrome’s upcoming root store. Use caution — browser root store programs implement additional controls through custom certificate verification code which will not be implementable using a Network Security Configuration.

Notes:

1. Network Security Configuration may only fully work with Android 7.0+. Fortunately for me, Android Nougat 7.0 is the oldest version of Android supported by the apps I’m actively involved in maintaining.
2. Let’s Encrypt’s blog post indicates a DST Root X3 expiration date of September 1, 2021 instead of September 30, 2021. This may indicate the last date for which a cross-signature has been arranged, or it may be due to an error.