# datatheorem/trustkit architecture

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

- Interactive diagram: https://gitdiagram.com/datatheorem/trustkit
- Repository: https://github.com/datatheorem/trustkit

## Overview

##### Project type and purpose
- TrustKit is an open‐source SSL public‐key‐pinning and reporting framework for iOS/macOS/tvOS/watchOS apps (Objective-C/Swift).
- It provides a Core framework (pinning validator, configuration utilities, swizzling hooks, reporting), a Demo app illustrating integration (Objective-C & Swift), a test suite (unit and end-to-end), and documentation.

##### File structure
- Top level:
– Core framework: TrustKit/…
– Demo application: TrustKitDemo/…
– Tests: TrustKitTests/…
– Documentation: docs/…
– Support scripts: generate_test_certificates.py, get_pin_from_certificate.py
- In TrustKit/:
– Pinning: TSKPinningValidator, ssl_pin_verifier, SPKI hash cache, public-key algorithms.
– Swizzling: NSURLConnection/NSURLSession delegate proxies to auto-inject validation.
– Reporting: background reporter, rate limiter, failure report generation.
– Configuration: parse_configuration, configuration_utils, TrustKitConfig.
– Dependencies: domain_registry (trie search + registry tables), RSSwizzle (method swizzling helper).
– Public API headers in TrustKit/public/.
- TrustKitDemo/: a client app showcasing both Obj-C and Swift integration, using CocoaPods/Swift Package Manager.
- TrustKitTests/: uses OCMock and generated certificates to validate pinning behavior.

##### README for additional insights
- Describes features: easy API, Subject Public Key Info pinning, reporting, auto-pinning via swizzling.
- Notes supported platforms, configuration via Info.plist or programmatic init, and callback-based custom handling.

##### Main components and interactions
a. Core Framework Components
– Configuration Manager (parse_configuration, configuration_utils)
– Swizzling Module (RSSwizzle + delegate proxies)
– Pinning Validator (TSKPinningValidator + ssl_pin_verifier)
– Reporting Engine (TSKBackgroundReporter, rate limiter, report generation)
– Dependencies: domain_registry (pin lookup), RSSwizzle.
– Public API façade (TrustKit.h, TSKTrustKitConfig.h, TSKPinningValidator.h)
b. Host Application (TrustKitDemo or any App)
– Network layers (NSURLSession, NSURLConnection)
– Delegate callbacks intercepted by the Swizzling Module
– Developer code optionally invoking TSKPinningValidator directly
c. Testing Harness
– OCMock stubs for network sessions
– Test certificates and registry tables
– Unit tests calling into Pinning Validator and Reporting

Data flow / interactions:
1. App launches → TrustKit.initSharedInstance(withConfiguration) → Configuration Manager loads policy.
2. Swizzling Module hooks NSURLSessionDelegate & NSURLConnectionDelegate callbacks.
3. When the network layer issues an auth challenge, delegate call is routed to TSKPinningValidator.handleChallenge.
4. Pinning Validator consults domain_registry to match domain → validates SPKI hashes → returns pass/fail.
5. On failure, Reporting Engine builds a JSON report and sends it in the background.
6. Control returns to the network layer to enforce or ignore the connection.

##### Architectural patterns & design principles
- Modular separation: configuration, swizzling, validation, reporting.
- Dependency injection via swizzling (RSSwizzle) for zero-code integration.
- Single-instance (singleton) TrustKit façade.
- Extensibility: Public APIs expose callbacks, custom reporters.
- Cross-platform packaging: CocoaPods, Carthage, SwiftPM, Xcode targets.

##### Elements
– From Host App → Public API → Configuration/Validator.
– From Swizzling Module → Pinning Validator.
– From Validator → domain_registry.
– From Validator → Reporting Engine → External Report Server.
– External components (App, Report Server) in another.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "TrustKit Core Framework"
        CM["Configuration Manager"]:::core
        SW["Swizzling Module"]:::core
        PV["Pinning Validator"]:::core
        RE["Reporting Engine"]:::core
        DR["Domain Registry"]:::core
        API["Public API Facade"]:::core
    end

    App["Host Application"]:::external
    Server["External Report Server"]:::external
    Tests["Test Harness"]:::test

    App -->|"initSharedInstance"| API
    API -->|"load policy"| CM
    App -->|"network auth challenge"| SW
    SW -->|"handleChallenge"| PV
    PV -->|"lookup domain"| DR
    PV -->|"validate SPKI"| PV
    PV -->|"fail → report"| RE
    RE -->|"send report"| Server

    Tests --> PV
    Tests --> RE
    Tests --> SW
    Tests --> CM

    %% Click Events Configuration Manager
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/parse_configuration.h"
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/parse_configuration.m"
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/configuration_utils.h"
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/configuration_utils.m"
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/TSKTrustKitConfig.m"
    click CM "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKTrustKitConfig.h"

    %% Click Events Swizzling Module
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Swizzling/TSKNSURLConnectionDelegateProxy.h"
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Swizzling/TSKNSURLConnectionDelegateProxy.m"
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Swizzling/TSKNSURLSessionDelegateProxy.h"
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Swizzling/TSKNSURLSessionDelegateProxy.m"
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/RSSwizzle/RSSwizzle.h"
    click SW "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/RSSwizzle/RSSwizzle.m"

    %% Click Events Pinning Validator
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/TSKPinningValidator.m"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/TSKPinningValidator_Private.h"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/ssl_pin_verifier.h"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/ssl_pin_verifier.m"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/pinning_utils.h"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/pinning_utils.m"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/TSKPublicKeyAlgorithm.h"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/TSKSPKIHashCache.h"
    click PV "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Pinning/TSKSPKIHashCache.m"

    %% Click Events Reporting Engine
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKBackgroundReporter.h"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKBackgroundReporter.m"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKPinFailureReport.h"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKPinFailureReport.m"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKReportsRateLimiter.h"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/TSKReportsRateLimiter.m"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/reporting_utils.h"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/reporting_utils.m"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/vendor_identifier.h"
    click RE "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Reporting/vendor_identifier.m"

    %% Click Events Domain Registry
    click DR "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/domain_registry/domain_registry.h"
    click DR "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/domain_registry/private/trie_search.c"
    click DR "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/domain_registry/private/registry_search.c"
    click DR "https://github.com/datatheorem/trustkit/blob/master/TrustKit/Dependencies/domain_registry/registry_tables_genfiles/registry_tables.h"

    %% Click Events Public API Façade
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TrustKit.h"
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKPinningValidator.h"
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKPinningValidatorCallback.h"
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKPinningValidatorResult.h"
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKTrustDecision.h"
    click API "https://github.com/datatheorem/trustkit/blob/master/TrustKit/public/TSKTrustKitConfig.h"

    %% Click Events Host Application
    click App "https://github.com/datatheorem/trustkit/tree/master/TrustKitDemo/TrustKitDemo-ObjC/"
    click App "https://github.com/datatheorem/trustkit/tree/master/TrustKitDemo/TrustKitDemo-Swift/"
    click App "https://github.com/datatheorem/trustkit/tree/master/TrustKitDemo/Podfile"
    click App "https://github.com/datatheorem/trustkit/blob/master/TrustKitDemo/Podfile.lock"

    %% Click Events Testing Harness
    click Tests "https://github.com/datatheorem/trustkit/tree/master/TrustKitTests/"
    click Tests "https://github.com/datatheorem/trustkit/tree/master/TrustKitTests/Certificates/"
    click Tests "https://github.com/datatheorem/trustkit/tree/master/TrustKitTests/Dependencies/OCMock/"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKPinningValidatorTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKReporterTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKEndToEndNSURLSessionTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKSwizzlingTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKReportsRateLimiterTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKPublicKeyAlgorithmTests.m"
    click Tests "https://github.com/datatheorem/trustkit/blob/master/TrustKitTests/TSKPinConfigurationTests.m"

    classDef core fill:#f9f,stroke:#333,stroke-width:2px
    classDef external fill:#bbf,stroke:#333,stroke-width:2px
    classDef test fill:#bfb,stroke:#333,stroke-width:2px
```
