How appmattus/certificatetransparency works
Project type and purpose
• This is an open-source Kotlin/Java library providing certificate transparency and revocation support on Android and JVM.
• It comprises three primary modules:
• certificatetransparency (core JVM library)
• certificatetransparency-android (Android integration, caching, provider, chain cleaner)
• sampleapp (Android sample application demonstrating usage)
• Additional modules include buildSrc (custom Gradle tasks), ThreatDragonModels (security threat models), and documentation under docs/.
File structure highlights
• Top-level Gradle settings (settings.gradle.kts, gradle/…, build.gradle.kts) orchestrate a multi-module build.
• certificatetransparency/src/main/kotlin holds the core logic:
– Loglist fetching/parsing/caching
– ASN.1 parsing utilities
– CT and CR interceptors, trust managers, hostname verifiers
– Serialization & exceptions
• certificatetransparency-android adds AndroidDiskCache, CT/CR loggers, chain cleaner, and provider installation.
• sampleapp shows integration points for OkHttp, Retrofit, HttpURLConnection, WebView, and X509TrustManager.
a. Core library (certificatetransparency)
• LogListService → network (HTTP GET of compressed log list) → JSON parser → in-memory & disk cache
• CTInterceptor / CTTrustManager → chain cleaner → ASN.1 utilities → SCT signature verifier
b. Android integration (certificatetransparency-android)
• installCertificateTransparencyProvider → injects a Java Security Provider
• AndroidDiskCache ↔ local storage (SQLite/files)
• BasicAndroidCTLogger / BasicAndroidCRLogger → Android Logcat or custom sink
c. Certificate revocation
• CRInterceptor → static CRL entries configured at build time
d. Sample application
• Consumes Android CT library via:
• OkHttp interceptor
• Retrofit client
• HttpURLConnection wrapper
• Direct provider calls
• Displays results in UI screens
e. External services
• Google’s public CT log list endpoint
• CRL distribution point URLs (hard-coded or configured)
Architectural patterns & design principles
• Modularization: clear separation between core JVM logic and Android platform extensions
• Layered interceptors: network-level (OkHttp/HTTPURLConnection), trust-manager level, provider level
• Strategy/Builder: extensible builders for CTInterceptor, CRInterceptor, hostname verifiers
• Caching: pluggable cache layers (in-memory, disk) behind DataSource factory
• Parser/Transformer: separate JSON parsing, model transformation, and verification layers
Essential details
• Both CT and CR flows side by side
• Caching layers (in-memory vs. disk) and eviction
• Provider injection point for WebViews and generic HTTPS calls
• Build modules and their Gradle linkage