Add warning about backup pin
@@ -127,6 +127,34 @@ corresponding certificates' public key algorithms. For example:
Some additional consideration in regards to the right pinning policy to deploy follow.
+#### Always start with pinning enforcement disabled
+
+To avoid locking out too many users from your App when deploying SSL pinning
+for the first time, it is advisable to set `kTSKEnforcePinning` to `NO`, so that SSL
+connections will succeed regardless of pin validation. This means that TrustKit
+will mirror iOS' default behavior.
+
+
+#### Always provide at least one backup pin
+
+In order to prevent accidentally locking users out of your site, make sure you
+have at least one backup pin and that you have procedures in place to
+transition to using the backup pin if your primary pin can no longer be used.
+For example, if you pin to the public key of your server's certificate, you
+should generate a backup key that is stored somewhere safe. If you pin to an
+intermediate CA or a root CA, then you should also select an alternative CA
+that you are willing to switch to if your current CA (or their intermediate CA)
+becomes invalid for some reason.
+
+If you do not have a backup pin, you could inadvertently prevent your app from
+working until you released a new version of your app, and your users updated
+it. [One such
+incident](https://cabforum.org/pipermail/public/2016-November/008989.html) led
+to a bank having to ask their CA to issue a new certificate using a deprecated
+intermediate CA in order to allow their users to use the app, or face weeks of
+the app being unusable.
+
+
#### Consider leveraging auto-swizzling for simple Apps
By setting `kTSKSwizzleNetworkDelegates` to `YES`, TrustKit will perform method
@@ -151,14 +179,6 @@ authentication handlers'; see the "Manual Pin Validation" section in this guide
instructions.
-#### Always start with pinning enforcement disabled
-
-To avoid locking out too many users from your App when deploying SSL pinning
-for the first time, it is advisable to set `kTSKEnforcePinning` to `NO`, so that SSL
-connections will succeed regardless of pin validation. This means that TrustKit
-will mirror iOS' default behavior.
-
-
#### Deploy a reporting server or use Data Theorem's free server
Adding a report URL using the `kTSKReportUris` setting to receive pin validation
