# TrustKit

    @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.

### Usage in Singleton Mode

- `+initSharedInstanceWithConfiguration:`

  See `+initSharedInstanceWithConfiguration:sharedContainerIdentifier:`

  #### 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.

- `+initSharedInstanceWithConfiguration:sharedContainerIdentifier:`

  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

  `trustKitConfig` | A dictionary containing various keys for configuring the SSL pinning policy.
  `sharedContainerIdentifier` | The container identifier for an app extension. This must be set in order for reports to be sent from an app extension. See https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1409450-sharedcontaineridentifier @exception NSException Thrown when the supplied configuration is invalid or TrustKit has already been initialized.

- `+sharedInstance`

  Retrieve the global TrustKit singleton instance. Raises an exception if `+initSharedInstanceWithConfiguration:` has not yet been invoked.

  #### Declaration

  Objective-C

      + (nonnull instancetype)sharedInstance;

  Swift

      class func sharedInstance() -> Self

  #### Return Value

  the shared TrustKit singleton

### Implementing Pinning Validation

- `pinningValidator`

  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;

  Swift

      var pinningValidator: TSKPinningValidator { get set }

### Configuring a Validation Callback

- `pinningValidatorCallback`

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

  #### Declaration

  Objective-C

      @property (assign, readwrite, nonatomic, nullable)
          TSKPinningValidatorCallback pinningValidatorCallback;

  Swift

      var pinningValidatorCallback: TSKPinningValidatorCallback? { get set }

- `pinningValidatorCallbackQueue`

  Queue on which to invoke the `pinningValidatorCallback`; default value is the main queue.

  #### Declaration

  Objective-C

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

  Swift

      var pinningValidatorCallbackQueue: DispatchQueue! { get set }

### Usage in Multi-Instance Mode

- `-initWithConfiguration:`

  See `-initWithConfiguration:sharedContainerIdentifier:`

  #### 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.

- `-initWithConfiguration:sharedContainerIdentifier:`

  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

  `trustKitConfig` | A dictionary containing various keys for configuring the SSL pinning policy.
  `sharedContainerIdentifier` | The container identifier for an app extension. This must be set in order for reports to be sent from an app extension. See https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1409450-sharedcontaineridentifier

### Other Settings

- `+setLoggerBlock:`

  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)