How datatheorem/trustkit works
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.