Top Related Projects
Blackbox tool to disable SSL certificate validation - including certificate pinning - within iOS and macOS applications.
Tools to bootstrap CAs, certificate requests, and signed certificates.
A simple zero-config tool to make locally trusted development certificates with any names you'd like.
CFSSL: Cloudflare's PKI and TLS toolkit
Quick Overview
TrustKit is an open-source framework for iOS, macOS, tvOS, and Android that makes it easy to validate the SSL/TLS certificates of your app's network connections. It provides a simple API to enable SSL/TLS certificate pinning, a security feature that helps protect your app against man-in-the-middle attacks.
Pros
- Simplified SSL/TLS Certificate Pinning: TrustKit abstracts the complex process of SSL/TLS certificate pinning, making it easy for developers to implement this security feature in their apps.
- Cross-Platform Support: TrustKit supports iOS, macOS, tvOS, and Android, allowing developers to use the same code across multiple platforms.
- Flexible Configuration: TrustKit provides a flexible configuration system that allows developers to customize the pinning behavior to fit their specific needs.
- Automatic Certificate Rotation: TrustKit automatically handles the rotation of SSL/TLS certificates, reducing the maintenance burden for developers.
Cons
- Increased Complexity: Implementing SSL/TLS certificate pinning can add complexity to an app's codebase, which may not be suitable for all projects.
- Potential for Deployment Issues: Incorrect configuration of TrustKit can lead to connectivity issues or even app crashes, which can be challenging to diagnose and resolve.
- Dependency on External Libraries: TrustKit relies on several external libraries, which can introduce additional maintenance overhead and potential security vulnerabilities.
- Limited Documentation: The project's documentation, while generally good, could be more comprehensive and provide more detailed examples and use cases.
Code Examples
Enabling SSL/TLS Certificate Pinning
// Swift
let trustKitConfig: [String: Any] = [
kTSKPinnedDomains: [
"example.com": [
kTSKEnforcePinning: true,
kTSKPublicKeyHashes: ["base64EncodedSha256Hash1", "base64EncodedSha256Hash2"]
]
]
]
TrustKit.initSharedInstance(withConfiguration: trustKitConfig)
Handling SSL/TLS Certificate Pinning Failures
// Swift
TrustKit.sharedInstance().pinningValidatorBlock = { (_, _, _, _, _) in
// Handle pinning validation failures here
return true // Return true to allow the connection, false to block it
}
Updating SSL/TLS Certificate Hashes
// Swift
let trustKitConfig: [String: Any] = [
kTSKPinnedDomains: [
"example.com": [
kTSKEnforcePinning: true,
kTSKPublicKeyHashes: ["newBase64EncodedSha256Hash1", "newBase64EncodedSha256Hash2"]
]
]
]
TrustKit.sharedInstance().updatePinnedDomains(trustKitConfig)
Getting Started
To get started with TrustKit, follow these steps:
-
Add the TrustKit framework to your project using CocoaPods, Carthage, or manually.
-
Initialize TrustKit with your SSL/TLS certificate pinning configuration:
// Swift let trustKitConfig: [String: Any] = [ kTSKPinnedDomains: [ "example.com": [ kTSKEnforcePinning: true, kTSKPublicKeyHashes: ["base64EncodedSha256Hash1", "base64EncodedSha256Hash2"] ] ] ] TrustKit.initSharedInstance(withConfiguration: trustKitConfig)
-
Optionally, handle SSL/TLS certificate pinning failures by setting a custom
pinningValidatorBlock
:// Swift TrustKit.sharedInstance().pinningValidatorBlock = { (_, _, _, _, _) in // Handle pinning validation failures here return true // Return true to allow the connection, false to block it }
Competitor Comparisons
Blackbox tool to disable SSL certificate validation - including certificate pinning - within iOS and macOS applications.
Pros of ssl-kill-switch2
- Simpler to use for disabling SSL certificate validation
- Designed specifically for SSL/TLS testing and debugging
- Supports a wider range of iOS versions
Cons of ssl-kill-switch2
- Less comprehensive SSL/TLS security features
- Not actively maintained (last update in 2021)
- Limited to SSL/TLS interception, lacks additional security functionalities
Code Comparison
TrustKit:
NSDictionary *trustKitConfig =
@{
kTSKSwizzleNetworkDelegates: @YES,
kTSKPinnedDomains: @{
@"www.example.com": @{
kTSKPublicKeyAlgorithms : @[kTSKAlgorithmRsa2048],
kTSKPublicKeyHashes : @[
@"public_key_hash_1",
@"public_key_hash_2",
],
},
}
};
[TrustKit initializeWithConfiguration:trustKitConfig];
ssl-kill-switch2:
#import "SSLKillSwitch.h"
- (void)viewDidLoad {
[super viewDidLoad];
[SSLKillSwitch enableSSLKillSwitch];
}
TrustKit offers more comprehensive SSL/TLS security features, including certificate pinning and reporting capabilities. It's actively maintained and provides a robust solution for enhancing app security. ssl-kill-switch2, on the other hand, is simpler to use and focused specifically on disabling SSL certificate validation for testing purposes. However, it lacks the advanced security features of TrustKit and hasn't been updated recently.
Tools to bootstrap CAs, certificate requests, and signed certificates.
Pros of certstrap
- Written in Go, offering better performance and cross-platform compatibility
- Focused on certificate authority (CA) management and certificate generation
- Simpler to use for basic PKI tasks and certificate creation
Cons of certstrap
- Limited to certificate management, lacking broader SSL/TLS pinning features
- Less comprehensive security features compared to TrustKit
- May require additional tools for full SSL/TLS implementation in applications
Code Comparison
TrustKit (Objective-C):
[TrustKit initSharedInstanceWithConfiguration:@{
kTSKSwizzleNetworkDelegates: @YES,
kTSKPinnedDomains: @{
@"www.example.com": @{
kTSKPublicKeyAlgorithms : @[kTSKAlgorithmRsa2048],
kTSKPublicKeyHashes : @[
@"public_key_hash_1",
@"public_key_hash_2",
],
},
}
}];
certstrap (Go):
key, err := pkix.CreateRSAKey(2048)
crt, err := pkix.CreateCertificateAuthority(key, "CN=Example CA", time.Now(), time.Now().AddDate(5, 0, 0), "Example Organization", "Example Country")
While TrustKit focuses on SSL pinning configuration, certstrap provides straightforward certificate generation functionality. TrustKit offers more comprehensive SSL/TLS security features, while certstrap is more specialized for certificate management tasks.
A simple zero-config tool to make locally trusted development certificates with any names you'd like.
Pros of mkcert
- Simple and user-friendly local certificate authority for development purposes
- Supports multiple platforms (Windows, macOS, Linux) and browsers
- Automatically installs the root CA in the system trust store
Cons of mkcert
- Limited to local development environments, not suitable for production use
- Lacks advanced features for SSL pinning and certificate validation
- Does not provide runtime security checks or reporting capabilities
Code Comparison
mkcert:
mkcert example.com "*.example.com" localhost 127.0.0.1 ::1
TrustKit:
let trustKitConfig = [
kTSKSwizzleNetworkDelegates: false,
kTSKPinnedDomains: [
"www.example.com": [
kTSKPublicKeyAlgorithms: [kTSKAlgorithmRsa2048],
kTSKPublicKeyHashes: [
"HXXQgxueCIU5TTLHob/bPbwcKOKw6DkfsTWYHbxbqTY=",
"0SDf3cRToyZJaMsoS17oF72VMavLxj/N7WBNasNuiR8="
]
]
]
]
Summary
mkcert is a lightweight tool for generating locally-trusted certificates, ideal for development environments. TrustKit, on the other hand, is a more comprehensive SSL pinning library for iOS and macOS applications, offering advanced security features and runtime checks. While mkcert simplifies local certificate management, TrustKit provides robust protection against man-in-the-middle attacks in production environments.
CFSSL: Cloudflare's PKI and TLS toolkit
Pros of cfssl
- More comprehensive PKI/TLS toolkit with broader functionality
- Supports multiple platforms and can be used as a CLI tool
- Active development with regular updates and contributions
Cons of cfssl
- Steeper learning curve due to wider feature set
- May be overkill for simple SSL pinning needs
- Requires more setup and configuration for basic use cases
Code Comparison
TrustKit (Objective-C):
[TrustKit initSharedInstanceWithConfiguration:@{
kTSKSwizzleNetworkDelegates: @YES,
kTSKPinnedDomains: @{
@"example.com": @{
kTSKPublicKeyHashes : @[
@"public_key_hash_1",
@"public_key_hash_2",
],
},
}
}];
cfssl (Go):
c := cli.Config{
CFG: &config.Config{},
Root: cfsslConfig,
}
err := c.Start([]string{"serve", "-address=localhost", "-port=8888"})
if err != nil {
log.Fatal(err)
}
TrustKit focuses on SSL pinning for iOS and macOS apps, while cfssl provides a more comprehensive set of PKI and TLS tools. TrustKit offers a simpler setup for certificate pinning, whereas cfssl requires more configuration but offers greater flexibility for various PKI operations.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
TrustKit
TrustKit is an open source framework that makes it easy to deploy SSL public key pinning and reporting in any iOS 12+, macOS 10.13+, tvOS 12+ or watchOS 4+ App; it supports both Swift and Objective-C Apps.
If you need SSL pinning/reporting in your Android App. we have also released TrustKit for Android at https://github.com/datatheorem/TrustKit-Android.
Overview
TrustKit provides the following features:
- Simple API to configure an SSL pinning policy and enforce it within an App. The policy settings are heavily based on the HTTP Public Key Pinning specification.
- Sane implementation by pinning the certificate's Subject Public Key Info, as opposed to the certificate itself or the public key bits.
- Reporting mechanism to notify a server about pinning validation failures happening within the App, when an unexpected certificate chain is detected. This is similar to the report-uri directive described in the HPKP specification. The reporting mechanism can also be customized within the App by leveraging pin validation notifications sent by TrustKit.
- Auto-pinning functionality by swizzling the App's NSURLConnection and NSURLSession delegates in order to automatically add pinning validation to the App's HTTPS connections; this allows deploying TrustKit without even modifying the App's source code.
Getting Started
- Read the Getting Started guide.
- Check out the API documentation.
- TrustKit was initially released at Black Hat USA 2015 and was also featured on PayPal's engineering blog.
Sample Usage
Deploying SSL pinning in the App 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 =
@{
kTSKSwizzleNetworkDelegates: @NO,
kTSKPinnedDomains : @{
@"www.datatheorem.com" : @{
kTSKExpirationDate: @"2017-12-01",
kTSKPublicKeyHashes : @[
@"HXXQgxueCIU5TTLHob/bPbwcKOKw6DkfsTWYHbxbqTY=",
@"0SDf3cRToyZJaMsoS17oF72VMavLxj/N7WBNasNuiR8="
],
kTSKEnforcePinning : @NO,
},
@"yahoo.com" : @{
kTSKPublicKeyHashes : @[
@"TQEtdMbmwFgYUifM4LDF+xgEtd0z69mPGmkp014d6ZY=",
@"rFjc3wG7lTZe43zeYTvPq8k4xdDEutCmIhI5dn4oCeE=",
],
kTSKIncludeSubdomains : @YES
}
}};
[TrustKit initSharedInstanceWithConfiguration:trustKitConfig];
The policy can also be set programmatically in Swift Apps:
let trustKitConfig = [
kTSKSwizzleNetworkDelegates: false,
kTSKPinnedDomains: [
"yahoo.com": [
kTSKExpirationDate: "2017-12-01",
kTSKPublicKeyHashes: [
"JbQbUG5JMJUoI6brnx0x3vZF6jilxsapbXGVfjhN8Fg=",
"WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="
],]]] as [String : Any]
TrustKit.initSharedInstance(withConfiguration:trustKitConfig)
After TrustKit has been initialized, a
TSKPinningValidator
instance
can be retrieved from the TrustKit singleton, and can be used to perform SSL pinning validation
in the App's network delegates. For example in an NSURLSessionDelegate:
- (void)URLSession:(NSURLSession *)session
task:(NSURLSessionTask *)task
didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential *credential))completionHandler {
{
TSKPinningValidator *pinningValidator = [[TrustKit sharedInstance] pinningValidator];
// Pass the authentication challenge to the validator; if the validation fails, the connection will be blocked
if (![pinningValidator handleChallenge:challenge completionHandler:completionHandler])
{
// TrustKit did not handle this challenge: perhaps it was not for server trust
// or the domain was not pinned. Fall back to the default behavior
completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
}
}
For more information, see the Getting Started guide.
Credits
TrustKit is a joint-effort between the mobile teams at Data Theorem and Yahoo. See AUTHORS
for details.
License
TrustKit is released under the MIT license. See LICENSE
for details.
Top Related Projects
Blackbox tool to disable SSL certificate validation - including certificate pinning - within iOS and macOS applications.
Tools to bootstrap CAs, certificate requests, and signed certificates.
A simple zero-config tool to make locally trusted development certificates with any names you'd like.
CFSSL: Cloudflare's PKI and TLS toolkit
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot