CertPathValidatorException connecting to a Let's Encrypt host on Android M or earlier

Question

[edit: If you are here for Let\'s Encrypt expiry event from January 2021, read this first https://letsencrypt.org/2020/12/21/extending-android-compatibility.html]

Answer 1

For Let's Encrypt expiry event from January 2021, this is no longer required.

Read https://letsencrypt.org/2020/12/21/extending-android-compatibility.html before applying.

Answer 2

[edit: If you are here for Let's Encrypt expiry event from January 2021, read this first https://letsencrypt.org/2020/12/21/extending-android-compatibility.html]

As generic advice, if you need to add an root CA to older Android devices, this example shows how this can work.

The issue relates to the known expiry of the ISRG root certificate for Let's encrypt in 2021. This (test) server is using the replacement certificate which is only supported on versions of Android N (7.1.1) and later.

The following code will work against the root certificate used by lets encrypt in future. It builds on okhttp-tls.

Note: none of this advice applies in combination with CertificatePinner, if you choose to also pin certificates, then please discuss your strategy with your in-house security team.

    boolean androidNorEarlier = Build.VERSION.SDK_INT <= 25;

    OkHttpClient.Builder builder = new OkHttpClient.Builder();

    if (androidNorEarlier) {
      // TODO: download fresh from https://letsencrypt.org/certs/isrgrootx1.pem
      String isgCert =
              "-----BEGIN CERTIFICATE-----\n" +
              "MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw\n" +
              "TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh\n" +
              "cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4\n" +
              "WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu\n" +
              "ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY\n" +
              "MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc\n" +
              "h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+\n" +
              "0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U\n" +
              "A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW\n" +
              "T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH\n" +
              "B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC\n" +
              "B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv\n" +
              "KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn\n" +
              "OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn\n" +
              "jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw\n" +
              "qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI\n" +
              "rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV\n" +
              "HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq\n" +
              "hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL\n" +
              "ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ\n" +
              "3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK\n" +
              "NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5\n" +
              "ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur\n" +
              "TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC\n" +
              "jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc\n" +
              "oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq\n" +
              "4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA\n" +
              "mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d\n" +
              "emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=\n" +
              "-----END CERTIFICATE-----";

      CertificateFactory cf = CertificateFactory.getInstance("X.509");
      Certificate isgCertificate = cf.generateCertificate(new ByteArrayInputStream(isgCert.getBytes("UTF-8")));

      HandshakeCertificates certificates = new HandshakeCertificates.Builder()
              .addTrustedCertificate((X509Certificate) isgCertificate)
              // Uncomment to allow connection to any site generally, but could possibly cause
              // noticeable memory pressure in Android apps.
//              .addPlatformTrustedCertificates()
              .build();

      builder.sslSocketFactory(certificates.sslSocketFactory(), certificates.trustManager());
    }

    OkHttpClient client = builder.build();

    Request request = new Request.Builder()
            .url("https://valid-isrgrootx1.letsencrypt.org/robots.txt")
            .build();
    try (Response response = client.newCall(request).execute()) {
      assertTrue(response.code() == 200 || response.code() == 404);
      assertEquals(Protocol.HTTP_2, response.protocol());
    }

The new host certificates are root signed by the ISRG Root X1 CA.

 ./cft --host valid-isrgrootx1.letsencrypt.org           
CN:     valid-isrgrootx1.letsencrypt.org
Pin:    sha256/489aa1610850a89c720217b9d9dbdc7f80918119f32b88c2dd3bcfaf1de29079
SAN:    valid-isrgrootx1.letsencrypt.org
Key Usage: DigitalSignature, KeyEncipherment
Ext Key Usage: serverAuth, clientAuth
Authority Info Access:
    ocsp: http://ocsp.int-x3.letsencrypt.org
    caIssuers: http://cert.int-x3.letsencrypt.org/
Valid:  2020-10-14T15:00:50Z..2021-01-12T15:00:50Z (1 months)
CA: false

CN:     Let's Encrypt Authority X3
Pin:    sha256/60b87575447dcba2a36b7d11ac09fb24a9db406fee12d2cc90180517616e8a18
SAN:    <N/A>
Key Usage: DigitalSignature, KeyCertSign, CRLSign
Authority Info Access:
    ocsp: http://ocsp.root-x1.letsencrypt.org/
    caIssuers: http://cert.root-x1.letsencrypt.org/
Valid:  2016-10-06T15:43:55Z..2021-10-06T15:43:55Z (10 months)
CA: true Max Intermediate: 0

CN:     ISRG Root X1 (signed by locally-trusted root)
Pin:    sha256/0b9fa5a59eed715c26c1020c711b4f6ec42d58b0015e14337a39dad301c5afc3
SAN:    <N/A>
Key Usage: KeyCertSign, CRLSign
Valid:  2015-06-04T11:04:38Z..2035-06-04T11:04:38Z (14 years)
CA: true

Strict Transport Security: max-age=604800

OCSP status: GOOD

Existing certificates are signed by DST Root CA X3 which expires in September 2021.

$  ./cft --host letsencrypt.org 
CN:     lencr.org
Pin:    sha256/b93116ebda5e22efe089e7710b221557eb80a2e13c60a58687c0ce0369afd68a
SAN:    lencr.org, letsencrypt.org, www.lencr.org, www.letsencrypt.org
Key Usage: DigitalSignature, KeyEncipherment
Ext Key Usage: serverAuth, clientAuth
Authority Info Access:
    ocsp: http://ocsp.int-x3.letsencrypt.org
    caIssuers: http://cert.int-x3.letsencrypt.org/
Valid:  2020-11-03T21:00:55Z..2021-02-01T21:00:55Z (2 months)
CA: false

CN:     Let's Encrypt Authority X3
Pin:    sha256/60b87575447dcba2a36b7d11ac09fb24a9db406fee12d2cc90180517616e8a18
SAN:    <N/A>
Key Usage: DigitalSignature, KeyCertSign, CRLSign
Authority Info Access:
    ocsp: http://isrg.trustid.ocsp.identrust.com
    caIssuers: http://apps.identrust.com/roots/dstrootcax3.p7c
Valid:  2016-03-17T16:40:46Z..2021-03-17T16:40:46Z (4 months)
CA: true Max Intermediate: 0

CN:     DST Root CA X3 (signed by locally-trusted root)
Pin:    sha256/563b3caf8cfef34c2335caf560a7a95906e8488462eb75ac59784830df9e5b2b
SAN:    <N/A>
Key Usage: KeyCertSign, CRLSign
Valid:  2000-09-30T21:12:19Z..2021-09-30T14:01:15Z (10 months)
CA: true

Strict Transport Security: max-age=31536000

OCSP status: GOOD

Available Fixes

Name	Versions	API level	ISRG Root X1	network security config	OkHttp 3.12 + Fix
No official codename	1	1
	1.1	2
Cupcake	1.5	3
Donut	1.6	4
Eclair	2.0 – 2.1	5 – 7
Froyo	2.2 – 2.2.3	8
Gingerbread	2.3 – 2.3.7	9 – 10			X
Honeycomb	3.0 – 3.2.6	11 – 13			X
Ice Cream Sandwich	4.0 – 4.0.4	14 – 15			X
Jelly Bean	4.1 – 4.3.1	16 – 18			X
KitKat	4.4 – 4.4.4	19 – 20			X
Lollipop	5.0 – 5.1.1	21 – 22			X
Marshmallow	6.0 – 6.0.1	23			X
Nougat	7.0 – 7.1.2	24 – 25	7.1.1+	X	X
Oreo	8.0 – 8.1	26 – 27	X	X	X
Pie	9	28	X	X	X
Android 10	10	29	X	X	X
Android 11	11	30	X	X	X

Answer 3

On Android Nougat (7) you can add/update android:networkSecurityConfig in AndroidManifest.xml to point to a local certificate.

https://www.danieldent.com/blog/android-apps-lets-encrypt-dst-root-expiry/

<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>

Answer 4

Alternative answer based on code from @Yuri Schimke that works with OkHttp 3.1.2, Volley and HttpsUrlConnection.

Since those don't have HandshakeCertificates class that does the heavy-lifting, you need to do it yourself:

public TrustManagerFactory getTrustManagerFactory() throws NoSuchAlgorithmException, KeyStoreException, IOException, CertificateException {
    //Note: hardcode it, because the device might not even have the certificate to download it over https
    String isgCert =
            "-----BEGIN CERTIFICATE-----\n" +
                    "MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw\n" +
                    "TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh\n" +
                    "cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4\n" +
                    "WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu\n" +
                    "ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY\n" +
                    "MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc\n" +
                    "h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+\n" +
                    "0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U\n" +
                    "A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW\n" +
                    "T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH\n" +
                    "B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC\n" +
                    "B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv\n" +
                    "KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn\n" +
                    "OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn\n" +
                    "jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw\n" +
                    "qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI\n" +
                    "rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV\n" +
                    "HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq\n" +
                    "hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL\n" +
                    "ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ\n" +
                    "3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK\n" +
                    "NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5\n" +
                    "ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur\n" +
                    "TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC\n" +
                    "jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc\n" +
                    "oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq\n" +
                    "4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA\n" +
                    "mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d\n" +
                    "emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=\n" +
                    "-----END CERTIFICATE-----";

    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    Certificate isgCertificate = cf.generateCertificate(new ByteArrayInputStream(isgCert.getBytes(StandardCharsets.UTF_8)));

    // Create a KeyStore containing our trusted CAs
    KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
    keyStore.load(null, null);
    keyStore.setCertificateEntry("isrg_root", isgCertificate);

    //Default TrustManager to get device trusted CA
    TrustManagerFactory defaultTmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
    defaultTmf.init((KeyStore) null);

    X509TrustManager trustManager = (X509TrustManager) defaultTmf.getTrustManagers()[0];
    int number = 0;
    for(Certificate cert : trustManager.getAcceptedIssuers()) {
        keyStore.setCertificateEntry(Integer.toString(number), cert);
        number++;
    }

    // Create a TrustManager that trusts the CAs in our KeyStore
    TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
    tmf.init(keyStore);
    return tmf;
}

Then you can configure it, for OkHttp:

public static OkHttpClient getHttpClient() throws CertificateException, IOException, KeyStoreException, NoSuchAlgorithmException, KeyManagementException {
    OkHttpClient.Builder builder = new OkHttpClient.Builder();

    if (Build.VERSION.SDK_INT <= 25) {
        TrustManagerFactory tmf = getTrustManagerFactory();
        SSLContext context = SSLContext.getInstance("TLS");
        context.init(null, tmf.getTrustManagers(), null);
        builder.sslSocketFactory(context.getSocketFactory(), (X509TrustManager) tmf.getTrustManagers()[0]);
    }
    return builder.build();
}

For Volley:

public RequestQueue configureRequestQueue(Context context) {
    if (Build.VERSION.SDK_INT <= 25) {
        try {
            TrustManagerFactory tmf = NetworkUtility.getTrustManagerFactory();
            // Create an SSLContext that uses our TrustManager
            SSLContext sslContext = SSLContext.getInstance("TLS");
            sslContext.init(null, tmf.getTrustManagers(), null);

            HurlStack httpStack = new HurlStack(null, sslContext.getSocketFactory());
            return Volley.newRequestQueue(context, httpStack);
        } catch (IOException | CertificateException | NoSuchAlgorithmException | KeyStoreException | KeyManagementException e) {
            e.printStackTrace();
        }
    }
    return Volley.newRequestQueue(context);
}

For HttpsUrlConnection:

public void configureHttpsUrlConnection() {
    if (Build.VERSION.SDK_INT <= 25) {
        try {
            TrustManagerFactory tmf = getTrustManagerFactory();
            SSLContext context = SSLContext.getInstance("TLS");
            context.init(null, tmf.getTrustManagers(), null);
            HttpsURLConnection.setDefaultSSLSocketFactory(context.getSocketFactory());
        } catch (NoSuchAlgorithmException | KeyManagementException | KeyStoreException | IOException | CertificateException e) {
            e.printStackTrace();
        }
    }
}

Answer 5

For Glide just register an OkHttp ModelLoaderFactory for GlideUrl model class.

@GlideModule
class GlobalGlideModule : AppGlideModule() {
    override fun registerComponents(context: Context, glide: Glide, registry: Registry) {
        if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.N_MR1) {
            try {

                val isrgRootX1 = ... // X509Certificate

                val handshakeCertificates = HandshakeCertificates.Builder()
                    .addTrustedCertificate(isrgRootX1)
                    .addPlatformTrustedCertificates()
                    .build()

                val okHttpClient = OkHttpClient.Builder()
                    .sslSocketFactory(handshakeCertificates.sslSocketFactory(), handshakeCertificates.trustManager())
                    .build()

                // use our custom okHttp instead of default HTTPUrlConnection
                registry.replace(
                    GlideUrl::class.java,
                    InputStream::class.java,
                    OkHttpUrlLoader.Factory(okHttpClient)
                )
            } catch (t: Throwable) {
                super.registerComponents(context, glide, registry)
            }
        } else {
            super.registerComponents(context, glide, registry)
        }
    }
}

See example in this PR.