# google/conscrypt architecture

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

- Interactive diagram: https://gitdiagram.com/google/conscrypt
- Repository: https://github.com/google/conscrypt

## Overview

##### Project type and purpose
- Conscrypt is a multi‐module, multi‐platform Java security provider library (JSP).
- It implements JCE (Java Cryptography Extension) and JSSE (Java Secure Sockets) using BoringSSL via JNI.
- It targets Android (API ≥19) and OpenJDK (Java 8+) and ships as platform‐specific and uber JARs.
- It also provides stubs (android‐stub, libcore‐stub) for compilation, doc generation (api‐doclet), benchmarks (Caliper & JMH), constants generation, testing, and release automation.

##### File structure
- Top-level Gradle build files and settings define a multi-project build.
- Key modules:
- common – core Java engine, JNI bindings, native C++ glue, BoringSSL calls
- android, platform, openjdk – platform-specific wrappers and provider implementations
- android‐stub, libcore-stub – compile-only stubs for Android framework classes
- openjdk-uber – aggregator that packages all native libs
- api-doclet – Kotlin doclet generating API HTML
- constants – C++ generator for compile-time constants
- benchmark-* – Caliper & JMH benchmarks, graph generator
- testing – test utilities and VeryBasicHttpServer for integration tests
- release – Dockerfiles and scripts for packaging

##### README for additional insights
- Confirms use of BoringSSL for cryptographic primitives and TLS.
- Describes Maven/Gradle usage, native classifiers, and uber-jar packaging.
- Points to BUILDING.md for build instructions.

a. Main components
1. Application layer: Java applications on Android/OpenJDK
2. Security API (JCE/JSSE): standard Java calls (e.g., SSLContext.getInstance)
3. Conscrypt Provider modules:
– common (AbstractConscryptEngine, OpenSSLProvider, etc.)
– android/platform/openjdk wrappers (NativeCryptoJni, Platform classes)
4. JNI glue (jniutil, jniload in common/src/jni)
5. Native BoringSSL library (built via CMake in common/src/jni/main/cpp)
6. Stub modules (android-stub, libcore-stub) – compile‐time placeholders
7. Build & packaging (Gradle, release scripts, constants generator)
8. Documentation & tooling:
– api-doclet (Kotlin doclet)
– benchmarks (Caliper/JMH modules)
– testing modules

b. Relationships & interactions
- Provider classes invoke JNI methods → JNI glue → BoringSSL native library
- Platform modules depend on common; openjdk-uber packages all native libs for distribution
- Stubs feed into android/platform modules at compile time only
- Gradle orchestrates multi‐module build; constants module generates C++ header data used by native code
- api-doclet reads Java sources → emits HTML docs
- benchmark modules depend on provider and testing utilities
- release module assembles artifacts and Docker images

c. Architectural patterns & design principles
- Layered design: API → provider implementation → native backend
- Modular Gradle multi‐project (separation of concerns per module)
- Adapter/Provider pattern for JSSE/JCE (Provider classes register algorithms and SSL context)
- JNI as the boundary crossing from managed Java to native C++ (BoringSSL)
- Stub modules as ports for framework dependence injection

d. Key technologies/frameworks
- Java (JCE, JSSE SPI), Kotlin (api-doclet)
- JNI/C++ (BoringSSL integration), CMake for native build
- Gradle multiproject build, os-detector plugins
- Caliper & JMH for benchmarks
- Docker for release images
- Traditional Gradle/Wrapping for Android AAR

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    subgraph "Runtime Components"
        Application["Java Application"]:::runtime
        JSSE["JSSE/JCE SPI"]:::runtime
        subgraph "Provider Implementation"
            Common["Common Provider"]:::runtime
            AndroidWrap["Android Platform Wrapper"]:::runtime
            OpenJdkWrap["OpenJDK Platform Wrapper"]:::runtime
        end
        JNI["JNI Layer"]:::native
        BoringSSL["BoringSSL Native Library"]:::native
    end

    %% Compile-time Stubs
    subgraph "Compile-time Stubs"
        AndroidStub["Android-stub (compile-time only)"]:::stub
        LibcoreStub["Libcore-stub (compile-time only)"]:::stub
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        Gradle["Gradle Build (multi-project)"]:::build
        Uber["OpenJDK-Uber"]:::build
        ApiDoclet["API Doclet"]:::tooling
        Constants["Constants Generator"]:::tooling
        Benchmarks["Benchmarks (Caliper & JMH)"]:::tooling
        Testing["Testing & Integration Server"]:::tooling
        Release["Release Automation"]:::build
    end

    %% Relationships
    Application -->|uses| JSSE
    JSSE -->|provides to| Common
    Common -->|invokes JNI| JNI
    JNI -->|calls| BoringSSL
    Common -->|dependency| AndroidWrap
    Common -->|dependency| OpenJdkWrap

    AndroidStub -.->|compile-time only| AndroidWrap
    LibcoreStub -.->|compile-time only| AndroidWrap

    Gradle -->|orchestrates build| Common
    Gradle -->|orchestrates build| AndroidWrap
    Gradle -->|orchestrates build| OpenJdkWrap
    Gradle -->|orchestrates build| AndroidStub
    Gradle -->|orchestrates build| LibcoreStub
    Gradle -->|orchestrates build| Uber
    Gradle -->|orchestrates build| ApiDoclet
    Gradle -->|orchestrates build| Constants
    Gradle -->|orchestrates build| Benchmarks
    Gradle -->|orchestrates build| Testing
    Gradle -->|orchestrates build| Release

    Constants -->|generates headers for| Common
    ApiDoclet -->|reads sources from| Common
    Benchmarks -->|depend on| Common
    Testing -->|uses| Common
    Uber -->|packages native libs from| OpenJdkWrap
    Release -->|packages artifacts| Uber

    %% Click Events
    click Common "https://github.com/google/conscrypt/tree/master/common/"
    click AndroidWrap "https://github.com/google/conscrypt/blob/master/android/src/main/java/org/conscrypt/NativeCryptoJni.java"
    click AndroidWrap "https://github.com/google/conscrypt/blob/master/android/src/main/java/org/conscrypt/Platform.java"
    click OpenJdkWrap "https://github.com/google/conscrypt/blob/master/openjdk/src/main/java/org/conscrypt/NativeLibraryLoader.java"
    click AndroidStub "https://github.com/google/conscrypt/tree/master/android-stub/"
    click LibcoreStub "https://github.com/google/conscrypt/tree/master/libcore-stub/"
    click Uber "https://github.com/google/conscrypt/blob/master/openjdk-uber/build.gradle"
    click ApiDoclet "https://github.com/google/conscrypt/tree/master/api-doclet/src/main/kotlin/org/conscrypt/doclet/"
    click Constants "https://github.com/google/conscrypt/blob/master/constants/src/gen/cpp/generate_constants.cc"
    click BenchmarkAndroid "https://github.com/google/conscrypt/tree/master/benchmark-android/"
    click BenchmarkBase "https://github.com/google/conscrypt/tree/master/benchmark-base/"
    click BenchmarkGraphs "https://github.com/google/conscrypt/tree/master/benchmark-graphs/"
    click BenchmarkJmh "https://github.com/google/conscrypt/tree/master/benchmark-jmh/"
    click Testing "https://github.com/google/conscrypt/tree/master/testing/src/main/java/org/conscrypt/"
    click Release "https://github.com/google/conscrypt/tree/master/release/Dockerfile"
    click Gradle "https://github.com/google/conscrypt/blob/master/settings.gradle"

    %% Styles
    classDef runtime fill:#cce5ff,stroke:#2b7de9;
    classDef native fill:#d4edda,stroke:#28a745;
    classDef stub fill:#e2e3e5,stroke:#6c757d,stroke-dasharray: 5 5;
    classDef build fill:#fff3cd,stroke:#f0ad4e;
    classDef tooling fill:#ffe5b4,stroke:#fd7e14;
```
