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.