Files
TrustKit/docs/documentation/Domain Configuration Keys.html
2019-08-03 19:48:16 -07:00

535 lines
28 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<title>Domain Configuration Keys 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/Section/Domain Configuration Keys" class="dashAnchor"></a>
<a title="Domain Configuration Keys 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" />
Domain Configuration Keys 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>Domain Configuration Keys</h1>
</div>
</section>
<section class="section">
<div class="section-content">
<div class="task-group">
<div class="task-name-container">
<a name="/Configuration%20Keys"></a>
<a name="//apple_ref/objc/Section/Configuration Keys" class="dashAnchor"></a>
<a href="#/Configuration%20Keys">
<h3 class="section-name">Configuration Keys</h3>
</a>
</div>
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey"></a>
<a name="//apple_ref/objc/Type/TSKDomainConfigurationKey" class="dashAnchor"></a>
<a class="token" href="#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A domain-specific configuration key (to defined for a domain under the <code><a href="Global Configuration Keys.html#/c:@kTSKPinnedDomains">kTSKPinnedDomains</a></code>
key) that can be set in the 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">typedef</span> <span class="n">NSString</span> <span class="o">*</span><span class="n">TSKDomainConfigurationKey</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">typealias</span> <span class="kt">TSKDomainConfigurationKey</span> <span class="o">=</span> <span class="kt">NSString</span></code></pre>
</div>
</div>
</section>
</div>
</li>
</ul>
</div>
<div class="task-group">
<div class="task-name-container">
<a name="/Domain-Specific%20Configuration%20Keys%20-%20Required"></a>
<a name="//apple_ref/objc/Section/Domain-Specific Configuration Keys - Required" class="dashAnchor"></a>
<a href="#/Domain-Specific%20Configuration%20Keys%20-%20Required">
<h3 class="section-name">Domain-Specific Configuration Keys - Required</h3>
</a>
</div>
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/c:@kTSKPublicKeyHashes"></a>
<a name="//apple_ref/objc/Constant/kTSKPublicKeyHashes" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKPublicKeyHashes">kTSKPublicKeyHashes</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>An array of SSL pins, where each pin is the base64-encoded SHA-256 hash of a certificate&rsquo;s
Subject Public Key Info.</p>
<p>TrustKit will verify that at least one of the specified pins is found in the server&rsquo;s
evaluated certificate chain.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKPublicKeyHashes</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKPublicKeyHashes</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
</ul>
</div>
<div class="task-group">
<div class="task-name-container">
<a name="/Domain-Specific%20Configuration%20Keys%20-%20Optional"></a>
<a name="//apple_ref/objc/Section/Domain-Specific Configuration Keys - Optional" class="dashAnchor"></a>
<a href="#/Domain-Specific%20Configuration%20Keys%20-%20Optional">
<h3 class="section-name">Domain-Specific Configuration Keys - Optional</h3>
</a>
</div>
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/c:@kTSKEnforcePinning"></a>
<a name="//apple_ref/objc/Constant/kTSKEnforcePinning" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKEnforcePinning">kTSKEnforcePinning</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A boolean. If set to <code>NO</code>, TrustKit will not block SSL connections that caused a pin or
certificate validation error; default value is <code>YES</code>.</p>
<p>When a pinning failure occurs, pin failure reports will always be sent to the configured
report URIs regardless of the value of <code>kTSKEnforcePinning</code>.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKEnforcePinning</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKEnforcePinning</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:@kTSKIncludeSubdomains"></a>
<a name="//apple_ref/objc/Constant/kTSKIncludeSubdomains" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKIncludeSubdomains">kTSKIncludeSubdomains</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A boolean. If set to <code>YES</code>, also pin all the subdomains of the specified domain; default
value is <code>NO</code>.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKIncludeSubdomains</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKIncludeSubdomains</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:@kTSKExcludeSubdomainFromParentPolicy"></a>
<a name="//apple_ref/objc/Constant/kTSKExcludeSubdomainFromParentPolicy" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKExcludeSubdomainFromParentPolicy">kTSKExcludeSubdomainFromParentPolicy</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A boolean. If set to <code>YES</code>, TrustKit will not pin this specific domain if <code><a href="Domain Configuration Keys.html#/c:@kTSKIncludeSubdomains">kTSKIncludeSubdomains</a></code>
was set for this domain&rsquo;s parent domain.</p>
<p>This allows excluding specific subdomains from a pinning policy that was applied to a
parent domain.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKExcludeSubdomainFromParentPolicy</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKExcludeSubdomainFromParentPolicy</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:@kTSKReportUris"></a>
<a name="//apple_ref/objc/Constant/kTSKReportUris" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKReportUris">kTSKReportUris</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>An array of URLs to which pin validation failures should be reported.</p>
<p>To minimize the performance impact of sending reports on each validation failure, the reports
are uploaded using the background transfer service and are also rate-limited to one per day
and per type of failure. For HTTPS report URLs, the HTTPS connections will ignore the SSL
pinning policy and use the default certificate validation mechanisms, in order to maximize
the chance of the reports reaching the server. The format of the reports is similar to the
one described in RFC 7469 for the HPKP specification:</p>
<p>{
<q>app-bundle-id</q>: <q>com.datatheorem.testtrustkit2</q>,
<q>app-version</q>: <q>1</q>,
<q>app-vendor-id</q>: <q>599F9C00-92DC-4B5C-9464-7971F01F8370</q>,
<q>app-platform</q>: <q>IOS</q>,
<q>app-platform-version</q>: <q>10.2.0</q>,
<q>trustkit-version</q>: <q>1.3.1</q>,
<q>hostname</q>: <q>www.datatheorem.com</q>,
<q>port</q>: 0,
<q>noted-hostname</q>: <q>datatheorem.com</q>,
<q>include-subdomains</q>: true,
<q>enforce-pinning</q>: true,
<q>validated-certificate-chain</q>: [
pem1, &hellip; pemN
],
<q>known-pins</q>: [
<q>pin-sha256=\</q>d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=\<q>,
&ldquo;pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=\</q>
],
<q>validation-result</q>:1
}</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKReportUris</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKReportUris</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:@kTSKDisableDefaultReportUri"></a>
<a name="//apple_ref/objc/Constant/kTSKDisableDefaultReportUri" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKDisableDefaultReportUri">kTSKDisableDefaultReportUri</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A boolean. If set to <code>YES</code>, the default report URL for sending pin failure reports will
be disabled; default value is <code>NO</code>.</p>
<p>By default, pin failure reports are sent to a report server hosted by Data Theorem, for
detecting potential CA compromises and man-in-the-middle attacks, as well as providing a
free dashboard for developers; email <a href="mailto:info@datatheorem.com">info@datatheorem.com</a> if you&rsquo;d like a dashboard for
your App. Only pin failure reports are sent, which contain the App&rsquo;s bundle ID, the IDFV,
and the server&rsquo;s hostname and certificate chain that failed validation.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKDisableDefaultReportUri</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKDisableDefaultReportUri</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:@kTSKExpirationDate"></a>
<a name="//apple_ref/objc/Constant/kTSKExpirationDate" class="dashAnchor"></a>
<a class="token" href="#/c:@kTSKExpirationDate">kTSKExpirationDate</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>A string containing the date, in yyyy-MM-dd format, on which the domain&rsquo;s configured SSL
pins expire, thus disabling pinning validation. If the key is not set, then the pins do
not expire.</p>
<p>Expiration helps prevent connectivity issues in Apps which do not get updates to their
pin set, such as when the user disables App updates.</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">extern</span> <span class="k">const</span> <span class="n"><a href="Domain Configuration Keys.html#/c:TSKTrustKitConfig.h@T@TSKDomainConfigurationKey">TSKDomainConfigurationKey</a></span> <span class="n">kTSKExpirationDate</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">kTSKExpirationDate</span><span class="p">:</span> <span class="kt">String</span></code></pre>
</div>
</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>