Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
SSLCertificatePinning
README.md

README.md

The SSL Conservatory: iOS Certificate Pinning

When an iOS application only needs to communicate to a well-defined set of servers over SSL or HTTPS, the security of the app's network communications can be improved through SSL pinning. By requiring a specific certificate to be part of the server's certificate chain, the threat of a rogue CA or a CA compromise is significantly reduced.

The ISPCertificatePinning class

Description

This class allows developers to whitelist a list of certificates for a given domain in order to require at least one these "pinned" certificates to be part of the server's certificate chain received when connecting to the domain over SSL or HTTPS.

This gives developers the flexibility to pin the CA/anchor certificate, the server/leaf certificate, or any intermediate certificate for a given domain. Each option has different advantages and limitations; for example, pinning the server/leaf certificate provides the best security but this certificate is going to change more often than the CA/anchor certificate.

A change in the certificate presented by the server (for example because the previous certificate expired) will result in the application being unable to connect to the server until its pinned certificate has been updated as well. To address this scenario, multiple certificates can be pinned to a single domain. This gives developers the ability to transition from an expiring certificate to a new one by releasing a new version of their application that pins both certificates to the server's domain.

API

The ISPCertificatePinning class exposes two methods:

+(BOOL)setupSSLPinsUsingDictionnary:(NSDictionary*)domainsAndCertificates

This method takes a dictionary with domain names as keys and arrays of DER-encoded certificates as values, and stores them in a pre-defined location on the filesystem. The ability to specify multiple certificates for a single domain is useful when transitioning from an expiring certificate to a new one

+(BOOL)verifyPinnedCertificateForTrust:(SecTrustRef)trust andDomain:(NSString*)domain

This method accesses the certificates previously loaded using the setupSSLPinsUsingDictionnary: method and inspects the trust object's certificate chain in order to find at least one certificate pinned to the given domain. SecTrustEvaluate() should always be called before this method to ensure that the certificate chain is valid.

Convenience delegate classes for NSURLConnection and NSURLSession

This library also provides convenience classes for connections relying on NSURLConnection and NSURLSession. The ISPPinnedNSURLConnectionDelegate and ISPPinnedNSURLSessionDelegate implement the connection authentication methods within respectively the NSURLConnectionDelegate and NSURLSessionDelegate protocols, in order to automatically validate the server's certificate based on SSL pins loaded using the setupSSLPinsUsingDictionnary: method.

To implement certificate pinning in their Apps, developers should simply extend these classes when creating their own connection delegates.

Sample code

The Xcode unit tests within SSLCertificatePinningTests contain sample code demonstrating how to implement certificate pinning when using NSURLConnection and NSURLSession.

Changelog

  • v3: Turned the Xcode project into a static library. Added certificate pinning delegate class for NSURLSession connections.
  • v2: Added the ability to pin multiple certificates to a single domain.
  • v1: Initial release.

License

See ../LICENSE.

Author

Alban Diquet - https://github.com/nabla-c0d3