GCXTrustPolicy

SSL-pinning and trust validation framework for iOS. 💻 <- 👮 -> ☁️

Optimized for Swift and working from plain old Objective-C as well.

Abstract

Users, developers and applications expect end-to-end security on their secure channels, but some secure channels are not meeting the expectation. Specifically, channels built using well known protocols such as VPN, SSL and TLS can be vulnerable to a number of attacks. This is where SSL-validation come into play as it prevents from Man-in-The-Middle attacks and other vulnerabilities. This framework is intended as customizable drop-in-solution that makes SSL-validation more comfortable and reliable secure.

General

When a TLS certificate is verified, the operating system verifies its chain of trust. If that chain of trust contains only valid certificates and ends at a known (trusted) anchor certificate, then the certificate is considered valid. If it does not, it is considered invalid. When using a commercially signed certificate from a major vendor, the certificate should “just work”. When using a self-signed certificate, connecting to a host by IP address (where the networking stack cannot determine the server’s host name) or providing service for multiple domains within a single certificate that is not trusted for those domains the certificate will not operate and you will have to do some extra work.

Installation

If you encounter problems check our troubleshooting section or file an Issue.

We will give our best trying to help you out. 🙂

Carthage

github "grandcentrix/GCXTrustPolicy"

Cocoapods

use_frameworks!

pod 'GCXTrustPolicy'

Manual

Start a new XCode Workspace.
Create new App
Import GCXTrustPolicy.xcodeproj into your Workspace
Go to "Project Settings" -> "General Tab"
Add GCXTrustPolicy.framework to the "Embedded Binaries" section
Build and Run

Example

General Steps

Add the certificate(s) to pin to your project
Create a validation policy
Perform a URL request using a secure connection (such as https)
URLSessionDelegate receives an authentication challenge
Validate the policy against the remote trust

Simple example

// create a policy for the host:
let policy = trustManager.create(type: .pinPublicKey, hostName: "pinnedHost.com")

// >>> perform URL request to remot host <<<

// In URLSessionDelegate or NSURLConnectionDelegate callbacks retrieve the remote trust on authentication challenge:
guard let serverTrust = challenge.protectionSpace.serverTrust else { /* handle case ... */ }

// Let the policy validate the given trust:
let isTrusted = pinningPolicy.validate(trust: serverTrust)

// Reject connection to suspicious servers
if isTrusted {
// Success! Server trust has been established.
} else {
// Fail! Non-trustable server!
}

Validation types

GCXTrustPolicy offers multiple validation types:

Pin a Certificate's Public Key
Pin a Certificate
Use a complete custom validation
Use default validation of the operation system
Disable validation for a given host

Detailed examples

For detailed examples please refer to Examples or source code examples for Swift and ObjC in Integration Tests.

Documentation

Please see source code documentation in TrustPolicy.swift for detailed information.

Glossary

TLS

Transport Layer Security (TLS) is a cryptographic protocols designed to provide communications security over a computer network

SSL

Secure Sockets Layer (SSL) is a cryptographic protocol that is deprecated and has been replaced by TLS

Certificate

A certificate is a digital file that is usable for SSL or TLS. The certificate assists with authenticating and verifying the identity of a host or website. It also enables the encryption of the exchanged information.

X.509

A standard defining a Public Key Infrastructure (PKI) to verify that a public key belongs to the identity contained within the certificate.

Troubleshooting

If running an Objective-C project and encounter dyld: Library not loaded: @rpath/libswiftCore.dylib error try to setting the Xcode build option 'Embedded Content Contains Swift Code' to 'YES'.

Further reference

Apple developer documentation covering enhanced trust authentication: Performing Manual Server Trust Authentication

The following OWASP page gives an detailed overview about Transport Layer Protection and the whole process of Pinning at a glance.

The following informative blog post provides some information on which keys to pin and what the trade-offs are: https://noncombatant.org/2015/05/01/about-http-public-key-pinning/.

Credits

The underlying code is based on the suggestions and implementation strategies of OWASP's chapter on Certificate and Public Key Pinning. Unit Test approaches in Swift are inspired from the well-known Alamofire and TrustKit.

License

Copyright 2017 grandcentrix GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

grandcentrix / GCXTrustPolicy