TrustKit

TrustKit is an open source framework that makes it easy to deploy SSL public key pinning in any iOS or OS X App.

Overview

At a high level, TrustKit intercepts all outgoing SSL connections initiated by SecureTransport in order to perform additional validation against the server's certificate chain, based on an App-wide SSL pinning policy. This novel approach to SSL pinning gives us the following benefits:

• Easy to use: TrustKit can be deployed in minutes in any App. For iOS8+ and OS X Apps, TrustKit can be used without even modifying the App's source code.
• API-independent pinning by directly hooking Apple's SecureTransport: TrustKit works on NSURLSession, UIWebView, NSStream, etc. all the way down to BSD sockets.

Additionally, TrustKit provides the following features:

• Subject Public Key Info pinning, as opposed to certificate pinning or pinning the public key bits.
• Mechanism to report pinning failures, which allows Apps to send reports when an unexpected certificate chain is detected, similarly to the report-uri directive described in the HTTP Public Key Pinning specification.

TrustKit was open-sourced at Black Hat 2015 USA.

Getting Started

• Have a look at the Black Hat USA 2015 presentation.
• Read the Getting Started guide.
• Check out the API documentation.

Sample Usage

TrustKit can be deployed using CocoaPods, by adding the following line to your Podfile:

pod 'TrustKit'

Then run:

$ pod install

Then, enabling SSL pinning globally in the App only requires initializing TrustKit with a pinning policy (domains, Subject Public Key Info hashes, and additional settings).

The policy can be configured within the App's Info.plist:

Alternatively, the pinning policy can be set programmatically:

NSDictionary *trustKitConfig;
trustKitConfig = @{
                   @"www.datatheorem.com" : @{
                           kTSKPublicKeyAlgorithms : @[kTSKAlgorithmRsa2048],
                           kTSKPublicKeyHashes : @[
                                   @"HXXQgxueCIU5TTLHob/bPbwcKOKw6DkfsTWYHbxbqTY=",
                                   @"0SDf3cRToyZJaMsoS17oF72VMavLxj/N7WBNasNuiR8="
                                   ],
                           kTSKEnforcePinning : @NO,
                           kTSKReportUris : @[@"http://report.datatheorem.com/log_report"],
                           },
                   @"yahoo.com" : @{
                           kTSKPublicKeyAlgorithms : @[kTSKAlgorithmRsa4096],
                           kTSKPublicKeyHashes : @[
                                   @"TQEtdMbmwFgYUifM4LDF+xgEtd0z69mPGmkp014d6ZY=",
                                   @"rFjc3wG7lTZe43zeYTvPq8k4xdDEutCmIhI5dn4oCeE=",
                                   ],
                           kTSKIncludeSubdomains : @YES
                           }
                   };

[TrustKit initializeWithConfiguration:trustKitConfig];

Once TrustKit has been initialized, all SSL connections initiated by Apple frameworks within the App will verify the server' certificate chains against the supplied pinning policy. If report URIs have been configured, the App will also send reports to the specified URIs whenever a pin validation failure occurred.

For more information, see the Getting Started guide.

Credits

TrustKit is a joint-effort between the security teams at Data Theorem and Yahoo. See AUTHORS for details.

License

TrustKit is released under the MIT license. See LICENSE for details.