Certificate Transparency for Android and JVM

When using the certificateTransparencyInterceptor, you can specify which hosts should bypass certificate transparency checks using a DSL.

• Use the minus operator (-) to exclude a domain or a wildcard pattern (e.g., "*.example.com").
• Use the plus operator (+) to explicitly include a specific subdomain, which overrides any broader exclusion patterns.

val interceptor = certificateTransparencyInterceptor {
    // Exclude any subdomain but not "appmattus.com" with no subdomain
    -"*.appmattus.com"

    // Exclude specified domain
    -"example.com"

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

For non-HTTPS connections, you can integrate Certificate Transparency verification by wrapping an existing X509TrustManager with the certificateTransparencyTrustManager function. This allows you to leverage the library's CT verification logic within standard Java/Android trust management flows.

val wrappedTrustManager = certificateTransparencyTrustManager(originalTrustManager)

To use Certificate Transparency checks with the Volley networking library, you must override the createConnection method when initializing your RequestQueue. This is done by providing a custom HurlStack implementation. Inside createConnection, wrap the existing hostnameVerifier of any HttpsURLConnection with certificateTransparencyHostnameVerifier.

val requestQueue = Volley.newRequestQueue(applicationContext, object : HurlStack() {
    override fun createConnection(url: URL): HttpURLConnection {
        val connection = super.createConnection(url)
        if (connection is HttpsURLConnection) {
            connection.hostnameVerifier = certificateTransparencyHostnameVerifier(connection.hostnameVerifier)
        }
        return connection
    }
})

When using certificateTransparencyHostnameVerifier, you can provide a configuration block to exclude certain domains or subdomains from CT enforcement.

Exclusion rules follow these patterns:

• -"*.domain.com": Excludes all subdomains of a domain.
• -"domain.com": Excludes a specific domain.
• +"sub.domain.com": Overrides an exclusion to allow a specific subdomain to be checked.

This is useful for interacting with legacy servers or specific hosts that do not support Certificate Transparency.

connection.hostnameVerifier = certificateTransparencyHostnameVerifier(connection.hostnameVerifier) {
    // Exclude any subdomain but not "appmattus.com" with no subdomain
    -"*.appmattus.com"

    // Exclude specified domain
    -"example.com"

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

Depending on your target platform, include the appropriate dependency in your build.gradle file.

For Android modules: Use the android dependency to ensure necessary ProGuard rules are included.

For Java library modules: Use the standard dependency.

Important Requirements:

• The library uses Java 8+ language features.
• If you need to support Android 7 (API 25) or lower, you must enable Desugaring.

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

// Java library modules
implementation("com.appmattus.certificatetransparency:certificatetransparency:<latest-version>")

To use Certificate Transparency with HttpURLConnection, you must wrap the existing hostnameVerifier of an HttpsURLConnection instance before calling connect(). This ensures that CT checks are performed alongside standard hostname verification.

Note: It is recommended to upgrade from HttpURLConnection to OkHttp if possible, as the version built into Android is static and does not receive security updates.

val connection = URL("https://www.appmattus.com").openConnection()
if (connection is HttpsURLConnection) {
    connection.hostnameVerifier = certificateTransparencyHostnameVerifier(connection.hostnameVerifier)
}

When using certificateTransparencyHostnameVerifier, you can provide a trailing lambda to define exclusions and inclusions for specific domains.

• Use the unary minus operator (-) to exclude a domain or a wildcard pattern (e.g., "*.example.com").
• Use the unary plus operator (+) to explicitly include a specific subdomain, which overrides any broader exclusion patterns.

connection.hostnameVerifier = certificateTransparencyHostnameVerifier(connection.hostnameVerifier) {
    // Exclude any subdomain but not "appmattus.com" with no subdomain
    "*.appmattus.com".unaryMinus()

    // Exclude specified domain
    "example.com".unaryMinus()

    // Override the exclusion by include a specific subdomain
    "allowed.appmattus.com".unaryPlus()
}