TrustKit Class Reference

@interface TrustKit : NSObject

TrustKit is the main class for configuring an SSL pinning policy within an App.

For most Apps, TrustKit should be used as a singleton, where a global SSL pinning policy is configured for the App. In singleton mode, the policy can be set either:

By adding it to the App’s Info.plist under the TSKConfiguration key, or
By programmatically supplying it using the +initSharedInstanceWithConfiguration: method.

In singleton mode, TrustKit can only be initialized once so only one of the two techniques should be used.

For more complex Apps where multiple SSL pinning policies need to be used independently (for example within different frameworks), TrustKit can be used in multi-instance mode by leveraging the -initWithConfiguration: method described at the end of this page.

A TrustKit pinning policy is a dictionary which contains some global, App-wide settings (of type TSKGlobalConfigurationKey) as well as domain-specific configuration keys (of type TSKDomainConfigurationKey) to be defined under the kTSKPinnedDomains entry. The following table shows the keys and the types of the corresponding values, and uses indentation to indicate structure:

| Key                                          | Type       |
|----------------------------------------------|------------|
| TSKSwizzleNetworkDelegates                   | Boolean    |
| TSKIgnorePinningForUserDefinedTrustAnchors   | Boolean    |
| TSKPinnedDomains                             | Dictionary |
| __ <domain-name-to-pin-as-string>            | Dictionary |
| ____ TSKPublicKeyHashes                      | Array      |
| ____ TSKIncludeSubdomains                    | Boolean    |
| ____ TSKExcludeSubdomainFromParentPolicy     | Boolean    |
| ____ TSKEnforcePinning                       | Boolean    |
| ____ TSKReportUris                           | Array      |
| ____ TSKDisableDefaultReportUri              | Boolean    |

When setting the pinning policy programmatically, it has to be supplied to the initSharedInstanceWithConfiguration: method as a dictionary in order to initialize TrustKit. For example:

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

   [TrustKit initSharedInstanceWithConfiguration:trustKitConfig];
   trustKit = [TrustKit sharedInstance];

Similarly, the TrustKit singleton can be initialized in Swift:

       let trustKitConfig = [
           kTSKSwizzleNetworkDelegates: false,
           kTSKPinnedDomains: [
               "yahoo.com": [
                   kTSKExpirationDate: "2017-12-01",
                   kTSKPublicKeyHashes: [
                       "JbQbUG5JMJUoI6brnx0x3vZF6jilxsapbXGVfjhN8Fg=",
                       "WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="
                   ],]]] as [String : Any]

       TrustKit.initSharedInstance(withConfiguration:trustKitConfig)

After initialization, the TrustKit instance’s pinningValidator should be used to implement pinning validation within the App’s network authentication handlers.

Declaration

Objective-C

+ (void)initSharedInstanceWithConfiguration:
    (nonnull NSDictionary<TSKGlobalConfigurationKey, id> *)trustKitConfig;

Swift

class func initSharedInstance(withConfiguration trustKitConfig: [String : Any])

Parameters


                                trustKitConfig

A dictionary containing various keys for configuring the SSL pinning policy. @exception NSException Thrown when the supplied configuration is invalid or TrustKit has already been initialized.

Initialize the global TrustKit singleton with the supplied pinning policy.

Declaration

Objective-C

+ (void)initSharedInstanceWithConfiguration:
            (nonnull NSDictionary<TSKGlobalConfigurationKey, id> *)
                trustKitConfig
                  sharedContainerIdentifier:
                      (nullable NSString *)sharedContainerIdentifier;

Swift

class func initSharedInstance(withConfiguration trustKitConfig: [String : Any], sharedContainerIdentifier: String?)

Parameters

Declaration

Objective-C

+ (nonnull instancetype)sharedInstance;

Swift

class func sharedInstance() -> Self

Return Value

the shared TrustKit singleton

Retrieve the validator instance conforming to the pinning policy of this TrustKit instance.

The validator should be used to implement pinning validation within the App’s network authentication handlers.
Declaration
Objective-C
```
@property (assign, readwrite, nonatomic, nonnull)
    TSKPinningValidator *pinningValidator;
```

Register a block to be invoked for every request that is going through TrustKit’s pinning validation mechanism. See TSKPinningValidatorCallback for more information.

Declaration

Declaration

Objective-C

@property (assign, readwrite, nonatomic, null_resettable)
    dispatch_queue_t pinningValidatorCallbackQueue;

Swift

var pinningValidatorCallbackQueue: DispatchQueue! { get set }

Declaration

Objective-C

- (nonnull instancetype)initWithConfiguration:
    (nonnull NSDictionary<TSKGlobalConfigurationKey, id> *)trustKitConfig;

Swift

init(configuration trustKitConfig: [String : Any])

Parameters


                                trustKitConfig

A dictionary containing various keys for configuring the SSL pinning policy.

Initialize a local TrustKit instance with the supplied SSL pinning policy configuration.

This method is useful in scenarios where the TrustKit singleton cannot be used, for example within larger Apps that have split some of their functionality into multiple framework/SDK. Each framework can initialize its own instance of TrustKit and use it for pinning validation independently of the App’s other components.
Declaration
Objective-C
```
- (nonnull instancetype)
        initWithConfiguration:
            (nonnull NSDictionary<TSKGlobalConfigurationKey, id> *)
                trustKitConfig
    sharedContainerIdentifier:(nullable NSString *)sharedContainerIdentifier;
```
Swift
```
init(configuration trustKitConfig: [String : Any], sharedContainerIdentifier: String?)
```
Parameters

Set the global logger.

This method sets the global logger, used when any TrustKit instance needs to display a message to the developer.

If a global logger is not set, the default logger will be used, which will only print TrustKit log messages (using NSLog()) when the App is built in Debug mode. If the App was built for Release, the default logger will not print any messages at all.
Declaration
Objective-C
```
+ (void)setLoggerBlock:(nonnull void (^)(NSString *_Nonnull))block;
```
Swift
```
class func setLoggerBlock(_ block: @escaping (String) -> Void)
```