Certificate transparency for Android and JVM

To protect our apps from man-in-the-middle attacks one of the first things that usually springs to mind is certificate pinning. However, the issues of certificate pinning are numerous. Firstly deciding on a reliable set of keys to pin against is tough. Once you made that decision if your expectations don't match reality your users suffer from not being able to access your app or website. Smashing Magazine learnt about this the hard way in late 2016 when they blocked users access for up to a year because of a mismatch between the pins and the certificates. On mobile fixing an invalid pin means pushing out a new version of an app which can still take a while to reach every user.

So with certificate pinning falling out of favour, what should you do? The new kid in town is certificate transparency.

Security

We are open about the security of our library and provide a threat model in the source code, created using OWASP Threat Dragon. If you feel there is something we have missed please reach out so we can keep this up to date.

Getting started

For Android modules include the android dependency in your build.gradle file which ensures the necessary ProGuard rules are present:

implementation("com.appmattus.certificatetransparency:certificatetransparency-android:<latest-version>")

⚠️ The library uses Java 8+ language features and requires Desugaring to be enabled to run on Android 7 (API 25) or less.

For Java library modules include the dependency as follows:

implementation("com.appmattus.certificatetransparency:certificatetransparency:<latest-version>")

On Android it is recommended to configure certificate transparency through the provided Java Security Provider at app startup, which can be configured through installCertificateTransparencyProvider. The advantage of this setup is it should work across all network types including WebViews with no additional setup.

⚠️ Android's WebViews only allow you to override GET network requests through overriding the shouldInterceptRequest method. This means the only reliable way to implement certificate transparency in WebViews is to use the Java Security Provider documented here. However, if you are using WebViews on Android 6.0 (API 23) or lower then installCertificateTransparencyProvider will cause issues and should be avoided.

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        installCertificateTransparencyProvider {
            // Setup a logger
            logger = BasicAndroidCTLogger(BuildConfig.DEBUG)

            // Setup disk cache
            diskCache = AndroidDiskCache(applicationContext)

            // Exclude any subdomain but not "appmattus.com" with no subdomain
            -"*.appmattus.com"

            // Exclude specified domain
            -"example.com"

            // Override the exclusion by including a specific subdomain
            +"allowed.appmattus.com"
        }
    }
}

Take a look at the advanced configuration for documentation on all the available options and Using Certificate Transparency in SDKs for guidance on usage in SDKs especially when using the Java Security Provider.

⚠️ Using the Java Security Provider may not work on all JVMs so if you are not on Android you are recommended to use one of the alternatives documented below.

Certificate transparency can also be setup in specific network connections, instructions are available for:

• OkHttp
• Retrofit
• HttpURLConnection
• Volley
• X509TrustManager If you are dealing with non-HTTPS connections you can also use the library to verify the certificates by wrapping a X509TrustManager and using that.

Currently, there is no support in the library for Apache HttpClient.

Certificate revocation

Unfortunately in Android there is no built-in support for certificate revocation, which means you're basically on your own. This is an incredibly hard to solve problem and it is worth reading revocation is broken for more background. Needless to say I would argue that revocation is flawed along with the broken implementations in mobile and web browsers.

For our purposes we've added certificateRevocationInterceptor to this library:

certificateRevocationInterceptor {
    addCrl(
        issuerDistinguishedName = "ME0xCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxJzAlBgNVBAMTHkRpZ2lDZXJ0IFNIQTIgU2VjdXJlIFNlcnZlciBDQQ==",
        serialNumbers = listOf("Aa8e+91erglSMgsk/mtVaA==", "A3G1iob2zpw+y3v0L5II/A==")
    )
}

It is worth highlighting that the list of revoked certificates would need to be built into the app and so would require pushing out an app update should you want to add a revocation in. This does mean there's a small window for any attacks using a revoked certificate.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE.md file for details