# appmattus/certificatetransparency architecture

> Architecture diagram of the GitHub repository appmattus/certificatetransparency, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/appmattus/certificatetransparency
- Repository: https://github.com/appmattus/certificatetransparency

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    CTLogs["Google CT Log Endpoint"]:::external
    CRLEndpoints["CRL Distribution Points"]:::external

    %% Core Library Module
    subgraph "Core Library" 
        direction TB
        CLService["LogListService"]:::core
        JSONParser1["LogListJsonParser"]:::core
        JSONParserV3["LogListJsonParserV3"]:::core
        InMemoryCache["InMemoryCache"]:::core
        DiskCache["DiskCache"]:::core
        ASN1Utils["ASN.1 Utilities"]:::core
        LogSigVerifier["LogSignatureVerifier"]:::core
        CTInterceptorBuilder["CTInterceptorBuilder"]:::core
        CTTrustManagerBuilder["CTTrustManagerBuilder"]:::core
        CTHostnameVerifierBuilder["CTHostnameVerifierBuilder"]:::core
        CRInterceptorBuilder["CRInterceptorBuilder"]:::core
        CRHostnameVerifierBuilder["CRHostnameVerifierBuilder"]:::core
        CertRevoker["CertificateRevocationInterceptor"]:::core
        CTProvider["CTProvider"]:::core

        CTLogs -->|"GET log_list.zip"| CLService
        CLService -->|"parse log list"| JSONParser1
        CLService -->|"parse v3 log list"| JSONParserV3
        JSONParser1 --> InMemoryCache
        JSONParserV3 --> InMemoryCache
        InMemoryCache --> DiskCache
        DiskCache --> CTInterceptorBuilder
        DiskCache --> CRInterceptorBuilder
        CTInterceptorBuilder --> ASN1Utils
        ASN1Utils --> LogSigVerifier
        LogSigVerifier --> CTInterceptorBuilder
        CTInterceptorBuilder --> CTTrustManagerBuilder
        CTInterceptorBuilder --> CTHostnameVerifierBuilder
        CTTrustManagerBuilder --> CTProvider
        CTHostnameVerifierBuilder --> CTProvider
        CRLEndpoints --> CRInterceptorBuilder
        CRInterceptorBuilder --> CertRevoker
        CertRevoker --> CRHostnameVerifierBuilder
        CRHostnameVerifierBuilder --> CTProvider
    end

    %% Android Integration Module
    subgraph "Android Integration" 
        direction TB
        AndroidDiskCache["AndroidDiskCache"]:::android
        BasicAndroidCTLogger["BasicAndroidCTLogger"]:::android
        BasicAndroidCRLogger["BasicAndroidCRLogger"]:::android
        AndroidChainCleaner["AndroidCertificateChainCleaner"]:::android

        AndroidDiskCache --- DiskCache
        CTInterceptorBuilder --> BasicAndroidCTLogger
        CRInterceptorBuilder --> BasicAndroidCRLogger
        CTTrustManagerBuilder --> AndroidChainCleaner
    end

    %% Sample Application Module
    subgraph "SampleApp Demonstration" 
        direction TB
        MainActivity["MainActivity"]:::sample
        ExampleScreen["ExampleScreen"]:::sample
        WebViewScreen["WebViewScreen"]:::sample
        Examples["Examples (OkHttp, Retrofit, HTTPUrlConnection)"]:::sample

        MainActivity --> Examples
        Examples --> CTInterceptorBuilder
        Examples --> CRInterceptorBuilder
        Examples --> CTProvider
        WebViewScreen --> CTProvider
        ExampleScreen --> CTInterceptorBuilder
    end

    %% Build and Docs
    BuildSrc["buildSrc (Gradle Tasks)"]:::external
    ThreatModels["ThreatDragonModels"]:::external
    Docs["docs"]:::external

    %% Click Events
    click CLService "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/loglist/LogListService.kt"
    click JSONParser1 "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/internal/loglist/parser/LogListJsonParser.kt"
    click JSONParserV3 "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/internal/loglist/parser/LogListJsonParserV3.kt"
    click InMemoryCache "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/internal/loglist/InMemoryCache.kt"
    click DiskCache "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/cache/DiskCache.kt"
    click ASN1Utils "https://github.com/appmattus/certificatetransparency/tree/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/internal/utils/asn1"
    click CTInterceptorBuilder "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/CTInterceptorBuilder.kt"
    click CTTrustManagerBuilder "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/CTTrustManagerBuilder.kt"
    click CTHostnameVerifierBuilder "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/CTHostnameVerifierBuilder.kt"
    click CRInterceptorBuilder "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificaterevocation/CRInterceptorBuilder.kt"
    click CRHostnameVerifierBuilder "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificaterevocation/CRHostnameVerifierBuilder.kt"
    click CertRevoker "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificaterevocation/internal/revoker/CertificateRevocationInterceptor.kt"
    click LogSigVerifier "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/internal/verifier/LogSignatureVerifier.kt"
    click CTProvider "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency/src/main/kotlin/com/appmattus/certificatetransparency/CTProvider.kt"
    click AndroidDiskCache "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency-android/src/main/kotlin/com/appmattus/certificatetransparency/cache/AndroidDiskCache.kt"
    click BasicAndroidCTLogger "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency-android/src/main/kotlin/com/appmattus/certificatetransparency/BasicAndroidCTLogger.kt"
    click BasicAndroidCRLogger "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency-android/src/main/kotlin/com/appmattus/certificaterevocation/BasicAndroidCRLogger.kt"
    click AndroidChainCleaner "https://github.com/appmattus/certificatetransparency/blob/main/certificatetransparency-android/src/main/kotlin/com/appmattus/certificatetransparency/chaincleaner/AndroidCertificateChainCleaner.kt"
    click MainActivity "https://github.com/appmattus/certificatetransparency/blob/main/sampleapp/src/main/java/com/appmattus/certificatetransparency/sampleapp/MainActivity.kt"
    click ExampleScreen "https://github.com/appmattus/certificatetransparency/blob/main/sampleapp/src/main/java/com/appmattus/certificatetransparency/sampleapp/ExampleScreen.kt"
    click WebViewScreen "https://github.com/appmattus/certificatetransparency/blob/main/sampleapp/src/main/java/com/appmattus/certificatetransparency/sampleapp/WebViewScreen.kt"
    click Examples "https://github.com/appmattus/certificatetransparency/tree/main/sampleapp/src/main/java/com/appmattus/certificatetransparency/sampleapp/examples"
    click BuildSrc "https://github.com/appmattus/certificatetransparency/blob/main/buildSrc/src/main/kotlin/UpdateLogListTask.kt"
    click ThreatModels "https://github.com/appmattus/certificatetransparency/blob/main/ThreatDragonModels/certificate-transparency-android/certificate-transparency-android.json"
    click Docs "https://github.com/appmattus/certificatetransparency/tree/main/docs/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef android fill:#90EE90,stroke:#333,stroke-width:1px
    classDef sample fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
