Files

403 lines
25 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<title>TSKPinningValidator Class Reference</title>
<link rel="stylesheet" type="text/css" href="../css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="../css/highlight.css" />
<meta charset="utf-8">
<script src="../js/jquery.min.js" defer></script>
<script src="../js/jazzy.js" defer></script>
<script src="../js/lunr.min.js" defer></script>
<script src="../js/typeahead.jquery.js" defer></script>
<script src="../js/jazzy.search.js" defer></script>
</head>
<body>
<a name="//apple_ref/objc/Class/TSKPinningValidator" class="dashAnchor"></a>
<a title="TSKPinningValidator Class Reference"></a>
<header class="header">
<p class="header-col header-col--primary">
<a class="header-link" href="../index.html">
TrustKit Docs
</a>
</p>
<p class="header-col--secondary">
<form role="search" action="../search.json">
<input type="text" placeholder="Search documentation" data-typeahead>
</form>
</p>
<p class="header-col header-col--secondary">
<a class="header-link" href="https://github.com/datatheorem/TrustKit">
<img class="header-icon" src="../img/gh.png"/>
View on GitHub
</a>
</p>
</header>
<p class="breadcrumbs">
<a class="breadcrumb" href="../index.html">TrustKit Reference</a>
<img class="carat" src="../img/carat.png" />
TSKPinningValidator Class Reference
</p>
<div class="content-wrapper">
<nav class="navigation">
<ul class="nav-groups">
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Initalizing TrustKit.html">Initalizing TrustKit</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Classes/TrustKit.html">TrustKit</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Implementing Pinning Validation.html">Implementing Pinning Validation</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Classes/TSKPinningValidator.html">TSKPinningValidator</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Enums/TSKTrustDecision.html">TSKTrustDecision</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Setting up a Validation Callback.html">Setting up a Validation Callback</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Setting up a Validation Callback.html#/c:TSKPinningValidatorCallback.h@T@TSKPinningValidatorCallback">TSKPinningValidatorCallback</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Classes/TSKPinningValidatorResult.html">TSKPinningValidatorResult</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Setting up a Validation Callback.html#/c:TSKPinningValidatorCallback.h@T@TKSDomainPinningPolicy">TKSDomainPinningPolicy</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Enums/TSKTrustEvaluationResult.html">TSKTrustEvaluationResult</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Global Configuration Keys.html">Global Configuration Keys</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Global Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKGlobalConfigurationKey">TSKGlobalConfigurationKey</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Global Configuration Keys.html#/c:@kTSKSwizzleNetworkDelegates">kTSKSwizzleNetworkDelegates</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Global Configuration Keys.html#/c:@kTSKPinnedDomains">kTSKPinnedDomains</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Global Configuration Keys.html#/c:@kTSKIgnorePinningForUserDefinedTrustAnchors">kTSKIgnorePinningForUserDefinedTrustAnchors</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Domain Configuration Keys.html">Domain Configuration Keys</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKPublicKeyHashes">kTSKPublicKeyHashes</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKEnforcePinning">kTSKEnforcePinning</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKIncludeSubdomains">kTSKIncludeSubdomains</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKExcludeSubdomainFromParentPolicy">kTSKExcludeSubdomainFromParentPolicy</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKReportUris">kTSKReportUris</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKDisableDefaultReportUri">kTSKDisableDefaultReportUri</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Domain Configuration Keys.html#/c:@kTSKExpirationDate">kTSKExpirationDate</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Other Constants.html">Other Constants</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@TrustKitVersion">TrustKitVersion</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@kTSKAlgorithmEcDsaSecp256r1">kTSKAlgorithmEcDsaSecp256r1</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@kTSKAlgorithmEcDsaSecp384r1">kTSKAlgorithmEcDsaSecp384r1</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@kTSKAlgorithmRsa2048">kTSKAlgorithmRsa2048</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@kTSKAlgorithmRsa4096">kTSKAlgorithmRsa4096</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Constants.html#/c:@kTSKPublicKeyAlgorithms">kTSKPublicKeyAlgorithms</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="../Other Type Definitions.html">Other Type Definitions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="../Other Type Definitions.html#/c:TSKTrustKitConfig.h@T@TSKSupportedAlgorithm">TSKSupportedAlgorithm</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="main-content">
<section class="section">
<div class="section-content">
<h1>TSKPinningValidator</h1>
<div class="declaration">
<div class="language">
<pre class="highlight objective_c"><code><span class="k">@interface</span> <span class="nc">TSKPinningValidator</span> <span class="p">:</span> <span class="nc">NSObject</span></code></pre>
</div>
</div>
<p>A <code>TSKPinningValidator</code> instance can be used to verify a server&rsquo;s identity against an SSL pinning policy.</p>
<p>In specific scenarios, TrustKit cannot intercept outgoing SSL connections and automatically validate the server&rsquo;s identity against the pinning policy:</p>
<ul>
<li>All connections within an App that disables TrustKit&rsquo;s network delegate swizzling by setting the <code><a href="../Global Configuration Keys.html#/c:@kTSKSwizzleNetworkDelegates">kTSKSwizzleNetworkDelegates</a></code> configuration key to <code>NO</code>.</li>
<li>Connections that do not rely on the <code>NSURLConnection</code> or <code>NSURLSession</code> APIs:
<ul>
<li><code>WKWebView</code> connections.</li>
<li>Connections leveraging low-level network APIs (such as <code>NSStream</code>).</li>
<li>Connections initiated using a third-party SSL library such as OpenSSL.</li>
</ul></li>
</ul>
<p>For these connections, pin validation must be manually triggered using one of the two available methods within <code>TSKPinningValidator</code>.</p>
</div>
</section>
<section class="section">
<div class="section-content">
<div class="task-group">
<div class="task-name-container">
<a name="/High-level%20Validation%20Method"></a>
<a name="//apple_ref/objc/Section/High-level Validation Method" class="dashAnchor"></a>
<a href="#/High-level%20Validation%20Method">
<h3 class="section-name">High-level Validation Method</h3>
</a>
</div>
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/c:objc(cs)TSKPinningValidator(im)handleChallenge:completionHandler:"></a>
<a name="//apple_ref/objc/Method/-handleChallenge:completionHandler:" class="dashAnchor"></a>
<a class="token" href="#/c:objc(cs)TSKPinningValidator(im)handleChallenge:completionHandler:">-handleChallenge:completionHandler:</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Helper method for handling authentication challenges received within a <code>NSURLSessionDelegate</code>, <code>NSURLSessionTaskDelegate</code> or <code>WKNavigationDelegate</code>.</p>
<p>This method will evaluate the server trust within the authentication challenge against the global SSL pinning policy previously configured, and then call the <code>completionHandler</code> with the corresponding <code>disposition</code> and <code>credential</code>. For example, this method can be leveraged in a NSURLSessionDelegate challenge handler method:</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">URLSession</span><span class="p">:(</span><span class="n">NSURLSession</span> <span class="o">*</span><span class="p">)</span><span class="nv">session</span>
<span class="nf">task</span><span class="p">:(</span><span class="n">NSURLSessionTask</span> <span class="o">*</span><span class="p">)</span><span class="nv">task</span>
<span class="nf">didReceiveChallenge</span><span class="p">:(</span><span class="n">NSURLAuthenticationChallenge</span> <span class="o">*</span><span class="p">)</span><span class="nv">challenge</span>
<span class="nf">completionHandler</span><span class="p">:(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="n">NSURLSessionAuthChallengeDisposition</span> <span class="n">disposition</span><span class="p">,</span> <span class="n">NSURLCredential</span> <span class="o">*</span><span class="n">credential</span><span class="p">))</span><span class="nv">completionHandler</span> <span class="p">{</span>
<span class="p">{</span>
<span class="n">TSKPinningValidator</span> <span class="o">*</span><span class="n">pinningValidator</span> <span class="o">=</span> <span class="p">[[</span><span class="n">TrustKit</span> <span class="nf">sharedInstance</span><span class="p">]</span> <span class="nf">pinningValidator</span><span class="p">];</span>
<span class="c1">// Pass the authentication challenge to the validator; if the validation fails, the connection will be blocked</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="p">[</span><span class="n">pinningValidator</span> <span class="nf">handleChallenge</span><span class="p">:</span><span class="n">challenge</span> <span class="nf">completionHandler</span><span class="p">:</span><span class="n">completionHandler</span><span class="p">])</span>
<span class="p">{</span>
<span class="c1">// TrustKit did not handle this challenge: perhaps it was not for server trust</span>
<span class="c1">// or the domain was not pinned. Fall back to the default behavior</span>
<span class="n">completionHandler</span><span class="p">(</span><span class="n">NSURLSessionAuthChallengePerformDefaultHandling</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre>
<p>@exception NSException Thrown when TrustKit has not been initialized with a pinning policy.</p>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="n">BOOL</span><span class="p">)</span><span class="nf">handleChallenge</span><span class="p">:(</span><span class="n">NSURLAuthenticationChallenge</span> <span class="o">*</span><span class="n">_Nonnull</span><span class="p">)</span><span class="nv">challenge</span>
<span class="nf">completionHandler</span><span class="p">:</span>
<span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">_Nonnull</span><span class="p">)(</span><span class="n">NSURLSessionAuthChallengeDisposition</span><span class="p">,</span>
<span class="n">NSURLCredential</span> <span class="o">*</span><span class="n">_Nullable</span><span class="p">))</span><span class="n">completionHandler</span><span class="p">;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">func</span> <span class="nf">handle</span><span class="p">(</span><span class="n">_</span> <span class="nv">challenge</span><span class="p">:</span> <span class="kt">URLAuthenticationChallenge</span><span class="p">,</span> <span class="nv">completionHandler</span><span class="p">:</span> <span class="kd">@escaping</span> <span class="p">(</span><span class="kt">URLSession</span><span class="o">.</span><span class="kt">AuthChallengeDisposition</span><span class="p">,</span> <span class="kt">URLCredential</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">Void</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Bool</span></code></pre>
</div>
</div>
<div>
<h4>Parameters</h4>
<table class="graybox">
<tbody>
<tr>
<td>
<code>
<em>challenge</em>
</code>
</td>
<td>
<div>
<p>The authentication challenge, supplied by the URL loading system to the delegate&rsquo;s challenge handler method.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>completionHandler</em>
</code>
</td>
<td>
<div>
<p>A block to invoke to respond to the challenge, supplied by the URL loading system to the delegate&rsquo;s challenge handler method.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div>
<h4>Return Value</h4>
<p><code>YES</code> if the challenge was handled and the <code>completionHandler</code> was successfuly invoked. <code>NO</code> if the challenge could not be handled because it was not for server certificate validation (ie. the challenge&rsquo;s <code>authenticationMethod</code> was not <code>NSURLAuthenticationMethodServerTrust</code>).</p>
</div>
</section>
</div>
</li>
</ul>
</div>
<div class="task-group">
<div class="task-name-container">
<a name="/Low-level%20Validation%20Method"></a>
<a name="//apple_ref/objc/Section/Low-level Validation Method" class="dashAnchor"></a>
<a href="#/Low-level%20Validation%20Method">
<h3 class="section-name">Low-level Validation Method</h3>
</a>
</div>
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/c:objc(cs)TSKPinningValidator(im)evaluateTrust:forHostname:"></a>
<a name="//apple_ref/objc/Method/-evaluateTrust:forHostname:" class="dashAnchor"></a>
<a class="token" href="#/c:objc(cs)TSKPinningValidator(im)evaluateTrust:forHostname:">-evaluateTrust:forHostname:</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Evaluate the supplied server trust against the SSL pinning policy previously configured. If the validation fails, a pin failure report will be sent.</p>
<p>When using the <code>NSURLSession</code> or <code>WKWebView</code> network APIs, the <code>handleChallenge:completionHandler:</code> method should be called instead, as it is simpler to use.</p>
<p>When using low-level network APIs (such as <code>NSStream</code>), instructions on how to retrieve the connection&rsquo;s <code>serverTrust</code> are available at <a href="https://developer.apple.com/library/mac/documentation/NetworkingInternet/Conceptual/NetworkingTopics/Articles/OverridingSSLChainValidationCorrectly.html">https://developer.apple.com/library/mac/documentation/NetworkingInternet/Conceptual/NetworkingTopics/Articles/OverridingSSLChainValidationCorrectly.html</a> .</p>
<div class="aside aside-warning">
<p class="aside-title">Warning</p>
<p>If no SSL pinning policy was configured for the supplied <em>serverHostname</em>, this method has no effect and will return <code>TSKTrustDecisionDomainNotPinned</code> without validating the supplied <em>serverTrust</em> at all. This means that the server&rsquo;s <em>serverTrust</em> object <strong>must</strong> be verified against the device&rsquo;s trust store using <code>SecTrustEvaluate()</code>. Failing to do so will <strong>disable SSL certificate validation</strong>.</p>
</div>
<p>@exception NSException Thrown when TrustKit has not been initialized with a pinning policy.</p>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="n"><a href="../Enums/TSKTrustDecision.html">TSKTrustDecision</a></span><span class="p">)</span><span class="nf">evaluateTrust</span><span class="p">:(</span><span class="n">SecTrustRef</span> <span class="n">_Nonnull</span><span class="p">)</span><span class="nv">serverTrust</span>
<span class="nf">forHostname</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="n">_Nonnull</span><span class="p">)</span><span class="nv">serverHostname</span><span class="p">;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">func</span> <span class="nf">evaluateTrust</span><span class="p">(</span><span class="n">_</span> <span class="nv">serverTrust</span><span class="p">:</span> <span class="kt">SecTrust</span><span class="p">,</span> <span class="n">forHostname</span> <span class="nv">serverHostname</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt"><a href="../Enums/TSKTrustDecision.html">TSKTrustDecision</a></span></code></pre>
</div>
</div>
<div>
<h4>Parameters</h4>
<table class="graybox">
<tbody>
<tr>
<td>
<code>
<em>serverTrust</em>
</code>
</td>
<td>
<div>
<p>The trust object representing the server&rsquo;s certificate chain. The trust&rsquo;s evaluation policy is always overridden using <code>SecTrustSetPolicies()</code> to ensure all the proper SSL checks (expiration, hostname validation, etc.) are enabled.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>serverHostname</em>
</code>
</td>
<td>
<div>
<p>The hostname of the server whose identity is being validated.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div>
<h4>Return Value</h4>
<p>A <code><a href="../Enums/TSKTrustDecision.html">TSKTrustDecision</a></code> which describes whether the SSL connection should be allowed or blocked, based on the configured pinning policy.</p>
</div>
</section>
</div>
</li>
</ul>
</div>
</div>
</section>
</article>
</div>
<section class="footer">
<p>&copy; 2019 <a class="link" href="https://datatheorem.github.io" target="_blank" rel="external">Data Theorem</a>. All rights reserved. (Last updated: 2019-08-03)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.10.0</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</body>
</div>
</html>