How to implement client certificates and server authentication for iOS - ios

Question

I have recently gone through an extremely arduous process to build something that should be very simple yet appears to be essentially un-findable in any one place. I’d like to try to put everything here to ask if I’m doing anything wrong and, if not, to help anyone who needs this information.
Background: The product/service for which I was trying to provide security is built around WCF services on a Windows server that are accessible only though custom client apps on a PC or an iPad. One server per customer, no browser access. Everything was already TLS secured with authentication and authorization using Windows standard mechanisms and certs from a commercial CA.
To further restrict access, client/server certificates were implemented for the Windows platform using self-signed certificates (commercial CAs are not required in cases where there is mutual authentication with no public/browser access – despite claims to the contrary - and they are harder to manage).
Getting all this to work for the iPad was a terribly documented nightmare with an amazing amount of disinformation or partially correct recommendations. In what follows, I have tried to link to the best sources but I apologize if I have inadvertently missed an attribution. Please comment if there is anything wrong/misleading about this post.
Thanks

Answer 1

The main steps are:
Create a system for generating certificates (easy but non-trivial if it’s a production system)
Transfer the certificates to an iPad (NOT embedded in the app store bundle!)
Save all the received credentials in the app keychain (where Apple says they belong)
Retrieve the saved credentials from the keychain for use in NSURLConnections
Actually authenticate server certificate and return client credentials
Step 1. Generate Certificates
Ref: http://developer-should-know.tumblr.com/post/127063737582/how-to-create-your-own-pki-with-openssl
You can use other methods but OpenSSL for Windows [http://slproweb.com/products.html] is pretty awesome, except that the standard interface is cmdline and the documentation is hard to follow.
What I wish someone had explained to me up front is obvious, yet not:
[a] The app installs to a root level directory and includes configuration files that are used by default for settings that are not specified at the command line
[b] the locations of the intermediate and output files should be specified in the configuration files
[c] certain files need to be created by hand before running the commands
[d] you should build a file/folder structure that suits what you are trying to do and then customize the cfg files accordingly.
In my case, this meant one RootCA for my company, an intermediate cert per customer (set to be good to only make client certificates), a server certificate per customer, and client certificates as required. (this is the minimum config, never use CA/client pairs, keep the root in a lockbox)
Here’s my file structure:
c:\sslcert
root
certs
YourCompany (duplicate this structure as required)
intermediate
server
client
crl (optional)
In top level sslcert folder
.rnd (empty file)
certindex.txt (empty file)
serial.txt (Text file seeded with the text “01”, hold the quotes)
In root folder
RootCA.cfg
In certs\template folder
IntermediateCA.cfg
Set working directory and launch OpenSSL
cd \sslcert
c:\OpenSSL-Win32\bin\openssl.exe
Create root key and certificate in one step
req -config ./root/RootCA.cfg -new -x509 -days 7300 -extensions v3_ca -keyout root/YourCompanyRootCAkey.pem -out root/YourCompanyRootCAcert.cer
NOTE for the beginner: the -extensions allows you to choose to apply one of several subsections in the same cfg file.
Check key and cert (optional)
x509 -noout -text -in root/YourCompanyRootCAcert.cer
Request a new intermediate certificate
req -config certs/YourCompany/IntermediateCA.cfg -new -keyout certs/YourCompany/intermediate/intermediateCAkey.pem -out certs/YourCompany/intermediate/intermediateCAreq.pem  
Sign intermediate certificate using root certificate found in root config
ca -config root/RootCA.cfg -extensions v3_intermediate_ca -days 3650 -notext -in certs/YourCompany/intermediate/intermediateCAreq.pem -out certs/YourCompany/intermediate/YourCompanyIntermediateCAcert.cer
Check key and cert (optional)
x509 -noout -text -in certs/YourCompany/intermediate/YourCompanyIntermediateCAcert.cer
Create the certificate chain file by concatenating the intermediate and root certificates (this is just a simple append from the command line - the new chain will be added to the final p12 package)
c:\sslcert> type c:\sslcert\certs\YourCompany\intermediate\YourCompanyIntermediateCAcert.cer c:\sslcert\root\YourCompanyRootCAcert.cer > c:\sslcert\certs\YourCompany\intermediate\YourCompanyCAchain.cer
Request a new client key and certificate
genrsa -aes256 -out certs/YourCompany/client/YourCompanyClientkey.pem 2048
req -config certs/YourCompany/IntermediateCA.cfg -key
certs/YourCompany/client/YourCompanyClientkey.pem -new -sha256 -out certs/YourCompany/client/YourCompanyClientreq.pem
Sign and test client certificate with intermediate authority
ca -config certs/YourCompany/IntermediateCA.cfg -extensions usr_cert -days 1095 -notext -md sha256 -in certs/YourCompany/client/YourCompanyClientreq.pem -out certs/YourCompany/client/YourCompanyClientcert.cer
x509 -noout -text -in certs/YourCompany/client/YourCompanyClientcert.cer
verify -CAfile certs/YourCompany/intermediate/YourCompanyCAchain.cer certs/YourCompany/client/YourCompanyClientcert.cer
Package client certificate
pkcs12 -export -in certs/YourCompany/client/YourCompanyClientcert.cer -name “YourCompany Smips Client” -inkey certs/YourCompany/client/YourCompanyClientkey.pem -certfile certs/YourCompany/intermediate/YourCompanyCAchain.cer -out certs/YourCompany/client/YourCompanyClientWithName.p12
Rename pkcs for import into iOS from email/iTunes
c:\sslcert> copy c:\sslcert\certs\YourCompany\client\YourCompanyClient.p12 c:\sslcert\certs\YourCompany\client\YourCompanyClient.yourext12
Request a new server key and certificate
genrsa -aes256 -out certs/YourCompany/server/YourCompanyServerkey.pem 2048
req -config certs/YourCompany/IntermediateCA.cfg -key certs/YourCompany/server/YourCompanyServerkey.pem -new -sha256 -out certs/YourCompany/server/YourCompanyServerreq.pem
Sign and test server certificate with intermediate authority
ca -config certs/YourCompany/IntermediateCA.cfg -extensions server_cert -days 1095 -notext -md sha256 -in certs/YourCompany/server/YourCompanyServerreq.pem -out certs/YourCompany/server/YourCompanyServercert.cer
x509 -noout -text -in certs/YourCompany/server/YourCompanyServercert.cer
verify -CAfile certs/YourCompany/intermediate/YourCompanyCAchain.cer certs/YourCompany/server/YourCompanyServercert.cer
Package server certificate
pkcs12 -export -in certs/YourCompany/server/YourCompanyServercert.cer -name “YourCompany Smips Server” -inkey certs/YourCompany/server/YourCompanyServerkey.pem -certfile certs/YourCompany/intermediate/YourCompanyCAchain.cer -out certs/YourCompany/server/YourCompanyServer.p12
Here are the cfg files:
Root
dir = .
[ ca ]
default_ca = CA_default
[ CA_default ]
serial = $dir/serial.txt
database = $dir/certindex.txt
new_certs_dir = $dir/certs
certs = $dir/certs
private_key = $dir/root/yourcompanyRootCAkey.pem
certificate = $dir/root/yourcompanyRootCAcert.cer
default_days = 7300
default_md = sha256
preserve = no
email_in_dn = no
nameopt = default_ca
certopt = default_ca
policy = policy_strict
[ policy_strict ]
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
[ req ]
default_bits = 4096 # Size of keys
default_keyfile = key.pem # name of generated keys
default_md = sha256 # message digest algorithm
string_mask = nombstr # permitted characters
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
[ req_distinguished_name ]
0.organizationName = Organization Name
organizationalUnitName = Organizational Unit Name
emailAddress = Email Address
emailAddress_max = 40
localityName = Locality Name (city, district)
stateOrProvinceName = State or Province Name (full name)
countryName = Country Name (2 letter code)
countryName_min = 2
countryName_max = 2
commonName = Common Name (hostname, IP, or your name)
commonName_max = 64
0.organizationName_default = yourcompany
organizationalUnitName_default = yourcompanyRoot Certification
emailAddress_default = info#yourcompany.com
localityName_default = Okeefenokee
stateOrProvinceName_default = Wisconsin
countryName_default = US
[ v3_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign
[ v3_intermediate_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true, pathlen:0
keyUsage = critical, digitalSignature, cRLSign, keyCertSign
[ crl_ext ]
authorityKeyIdentifier=keyid:always
Intermediate
dir = .
# [For non-command-line folks, everything is keyed to the working directory here (.) so if your working prompt says c:\sslcerts> then the cfg will look for serial.txt at c:\sslcerts\serial.txt and bomb if it doesn’t find things laid out accordingly. Thats why you set up a directory structure to match these entries]
[ ca ]
default_ca = CA_default
[ CA_default ]
serial = $dir/serial.txt
database = $dir/certindex.txt
crl_dir = $dir/certs/yourcompany/crl
new_certs_dir = $dir/certs
certs = $dir/certs
private_key = $dir/certs/yourcompany/intermediate/IntermediateCAkey.pem
certificate = $dir/certs/yourcompany/intermediate/yourcompanyIntermediateCAcert.cer
default_days = 3650
default_md = sha256
preserve = no
email_in_dn = no
nameopt = default_ca
certopt = default_ca
crlnumber = $dir/certs/yourcompany/crl/crlnumber
crl = $dir/certs/yourcompany/crl/crl.pem
crl_extensions = crl_ext
default_crl_days = 365
policy = policy_loose
[ policy_loose ]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
[ req ]
default_bits = 4096 # Size of keys
default_keyfile = $dir/certs/yourcompany/intermediate/IntermediateCAkey.pem
default_md = sha256 # message digest
# the old default was md1 - change this]
algorithm
string_mask = nombstr # permitted characters
distinguished_name = req_distinguished_name
x509_extensions = v3_intermediate_ca
[ req_distinguished_name ]
0.organizationName = Organization Name
organizationalUnitName = Organizational Unit Name
emailAddress = Email Address
emailAddress_max = 40
localityName = Locality Name (city, district)
stateOrProvinceName = State or Province Name (full name)
countryName = Country Name (2 letter code)
countryName_min = 2
countryName_max = 2
commonName = Common Name (hostname, IP, or your name)
commonName_max = 64
0.organizationName_default = yourcompany
organizationalUnitName_default = yourcompany Intermediate Certification
emailAddress_default = info#yourcompany.com
localityName_default = Okeefenokee
stateOrProvinceName_default = Wisconsin [should be spelled out]
countryName_default = US
[ v3_intermediate_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true, pathlen:0
keyUsage = critical, digitalSignature, cRLSign, keyCertSign
# Important - the pathlen parameter prevents this cert from being used to create new intermediate certs. The subsequent subsections for server and client certs allows you to specify their type and intended usage, as distinct from the intermediate cert, in the same cfg file
[ usr_cert ]
basicConstraints = CA:FALSE
nsCertType = client, email
nsComment = "OpenSSL Generated Client Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth, emailProtection
[ server_cert ]
basicConstraints = CA:FALSE
nsCertType = server
nsComment = "OpenSSL Generated Server Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
[ crl_ext ]
authorityKeyIdentifier = keyid:always
2. Transfer certificates to an iPad
Ref: how to register the app to open the pdf file in my app in ipad
Apple recommends registering a new file type handled by your app and transferring a p12 file renamed with the new custom extension to a device (manually or email) to install client certs. The p12 file should include the public cert chain as well as the client cert info as defined in step 1 above. When you try to open such a file, the device sends a start/wakeup to your app delegate which you need to handle (not in didload because it could be a wake).
This has changed a bit with v8 or 9 but I need to support 7 so this is for the deprecated handler. Same solution though and it starts with adding to the app plist file as shown in the screenshots below.
Note that you will need two new icons and file extension that is not likely to be claimed by another app
Next you need the delegate/handler which should be self-explanatory. Since this part has nothing to do with the normal control flow I am handling all the delegate processing in AppDelegate.m. (is this so wrong?) Set up the methods/variables as required and please ignore the paranoid extra check for file existence...
Ref: https://www.raywenderlich.com/6475/basic-security-in-ios-5-tutorial-part-1
- (BOOL) application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation {
if (url) {
self.p12Data = [NSData dataWithContentsOfFile:[url path]];
if (!p12Data) {
[self messageBox:#"Warning" : #"Failed to read data file, cancelling certificate import"];
}
else {
[self presentAlertViewForPassPhrase];
}
NSFileManager * fileManager = [NSFileManager defaultManager];
if ( [fileManager fileExistsAtPath:[url path]] ) {
[fileManager removeItemAtPath:[url path] error:NULL];
}
}
return YES;
}
- (void)presentAlertViewForPassPhrase {
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:#"Certificate Credentials"
message:#"Please enter the passphrase for your certificate"
delegate:self
cancelButtonTitle:#"Cancel"
otherButtonTitles:#"Done", nil];
[alert setAlertViewStyle:UIAlertViewStyleSecureTextInput];
[alert show];
}
- (void)alertView:(UIAlertView *)alertView didDismissWithButtonIndex:(NSInteger)buttonIndex {
if (buttonIndex == 1) { // User selected "Done"
UITextField *ppField = [alertView textFieldAtIndex:0];
if ([ppField.text length] > 0) {
[self loadCertificates:ppField.text];
}
//Handle Else
}
else
{ // User selected "Cancel"
[self messageBox:#"Information" : #"Certificate import cancelled"];
}
}
3. Save received credentials in the app keychain
Now that you have the raw p12 data it should be simple to figure out what to do next...NOT. All the documentation seems to be for name/pwd storage and a scary number of posters suggest saving the server cert to the file system, which is ok but makes absolutely no sense when you have the keychain and Apple says that's what it's for. Last but not least how do you distinguish between stored certs and how do you update them?
Long story short, I decided to do a complete delete/resave after trying all kinds of things that do not work to check if it should be an update or an initial load - besides that's what I wanted to do in the first place since it's my app chain. All this is CF stuff and I'm not using ARC because I refuse to port anything I don't have to. As near as I can tell, as long as you allocate CF, cast to NS, and CFRelease after use there are no warnings.
These are key references:
Enumerate all Keychain items in my iOS application
[essential to help visualize what your keychain looks like]
How to delete all keychain items accessible to an app?
What makes a keychain item unique (in iOS)?
http://help.sap.com/saphelp_smp307sdk/helpdata/en/7c/03830b70061014a937d8267bb3f358/content.htm
[https://developer.apple.com/library/ios/samplecode/AdvancedURLConnections/Listings/Credentials_m.html, which says:
// IMPORTANT: SecCertificateRef's are not uniqued (that is, you can get two
// different SecCertificateRef values that described the same fundamental
// certificate in the keychain), nor can they be compared with CFEqual. So
// we match up certificates based on their data values.
The summary is that (duh) the easiest thing to do is to assign a label to the cert so you can look it up uniquely and realize that if you save an identity it will be split up into key and cert automatically, which may - not sure - have led to some difficulty with replacement.
The code (explanation follows):
- (void) loadCertificates:(NSString *)passPhrase {
BOOL lastError = false;
NSMutableDictionary * p12Options = [[NSMutableDictionary alloc] init];
[p12Options setObject:passPhrase forKey:(id)kSecImportExportPassphrase];
CFArrayRef items = CFArrayCreate(NULL, 0, 0, NULL);
OSStatus err = SecPKCS12Import((CFDataRef)p12Data, (CFDictionaryRef)p12Options, &items);
if (err != noErr) {
[self messageBox:#"Error" : #"Unable to extract security information with the supplied credentials. Please retry"];
lastError = true;
}
if (!lastError && err == noErr && CFArrayGetCount(items) > 0) {
CFDictionaryRef identityDict = CFArrayGetValueAtIndex(items, 0);
//Clean-up
NSArray *secItemClasses = [NSArray arrayWithObjects:
(id)kSecClassCertificate,
(id)kSecClassKey,
(id)kSecClassIdentity,
nil];
for (id secItemClass in secItemClasses) {
NSDictionary *spec = #{(id)kSecClass: secItemClass};
err = SecItemDelete((CFDictionaryRef)spec);
}
//Client Identity & Certificate
SecIdentityRef clientIdentity = (SecIdentityRef)CFDictionaryGetValue(identityDict, kSecImportItemIdentity);
NSDictionary *addIdentityQuery = [NSDictionary dictionaryWithObjectsAndKeys:
kClientIdentityLabel, kSecAttrLabel,
(id)clientIdentity, kSecValueRef,
nil];
err = SecItemAdd((CFDictionaryRef)addIdentityQuery, NULL);
if (err == errSecDuplicateItem) {
NSLog(#"Duplicate identity");
}
if (err != noErr) {
[self messageBox:#"Warning" : #"Failed to save the new identity"];
lastError = true;
}
//Server Certificate
CFArrayRef chain = CFDictionaryGetValue(identityDict, kSecImportItemCertChain);
CFIndex N = CFArrayGetCount(chain);
BOOL brk = false;
for (CFIndex i=0; (i < N) && (brk == false); i++) {
SecCertificateRef cert = (SecCertificateRef)CFArrayGetValueAtIndex(chain, i);
CFStringRef summary = SecCertificateCopySubjectSummary(cert);
NSString* strSummary = [[NSString alloc] initWithString:(NSString *)summary];
if ([strSummary containsString:#"Root"] || (i == N)) {
NSDictionary *addCertQuery = [NSDictionary dictionaryWithObjectsAndKeys:
kServerCertificateLabel, kSecAttrLabel,
(id)cert, kSecValueRef,
nil];
err = SecItemAdd((CFDictionaryRef)addCertQuery, NULL);
if (err == errSecDuplicateItem) {
NSLog(#"Duplicate root certificate");
}
if (err != noErr) {
[self messageBox:#"Warning" : #"Failed to save the new server certificate"];
lastError = true;
}
brk = true;
}
[strSummary release];
CFRelease(summary);
}
}
else {
[self messageBox:#"Error" : #"Unable to extract security information with the supplied credentials. Please retry"];
lastError = true;
}
[p12Options release];
CFRelease(items);
if (!lastError) [self messageBox:#"Information" : #"Certificate import succeeded"];
}
where kClientIdentityLabel and kServerCertificateLabel are arbitrary labels.
The kSec functions are too many/complex to explain here in detail. Suffice it to say that everything is cleared, then the extracted client identity is saved, followed by extraction of the root CA which is then saved separately. Why the loop? because I didn't know if it is technically correct to assume the root is at the end of the chain but it will be if I generate the p12 so the code is just there for now.
Note that errors from kSec are encoded so this site is indispensable: https://www.osstatus.com
4. Retrieve the saved credentials from the keychain
Once the credentials are in the keychain you can extract them thusly (the failure modes leave something to be desired):
- (void) reloadCredentials {
self.clientCredential = nil;
self.serverCertificateData = nil;
if (self.useClientCertificateIfPresent) {
NSDictionary* idQuery = [NSDictionary dictionaryWithObjectsAndKeys:
kClientIdentityLabel, kSecAttrLabel,
(id)kSecClassIdentity, kSecClass,
kCFBooleanTrue, kSecReturnRef,
kSecMatchLimitAll, kSecMatchLimit,
nil];
CFArrayRef result = nil;
OSStatus err = SecItemCopyMatching((CFDictionaryRef)idQuery, (CFTypeRef*)&result);
if (err == errSecItemNotFound) {
[self messageBox:#"Warning" : #"Client credentials not found. Server connection may fail"];
}
else if (err == noErr && result != nil ) {
SecIdentityRef clientIdentity = (SecIdentityRef)CFArrayGetValueAtIndex(result, 0);
SecCertificateRef clientCertificate;
SecIdentityCopyCertificate(clientIdentity, &clientCertificate);
const void *certs[] = { clientCertificate };
CFArrayRef certsArray = CFArrayCreate(NULL, certs, 1, NULL);
self.clientCredential = [NSURLCredential credentialWithIdentity:clientIdentity certificates:(NSArray*)certsArray
persistence:NSURLCredentialPersistenceNone];
CFRelease(certsArray);
CFRelease(clientCertificate);
CFRelease(result);
}
else {
[self messageBox:#"Warning" : #"Client or Server credentials not found. Server connection may fail"];
}
NSDictionary* serverCertQuery = [NSDictionary dictionaryWithObjectsAndKeys:
kServerCertificateLabel, kSecAttrLabel,
(id)kSecClassCertificate, kSecClass,
kCFBooleanTrue, kSecReturnRef,
kSecMatchLimitAll, kSecMatchLimit,
nil];
CFArrayRef result1 = nil;
err = SecItemCopyMatching((CFDictionaryRef)serverCertQuery, (CFTypeRef*)&result1);
if (err == errSecItemNotFound) {
[self messageBox:#"Warning" : #"Server certificate not found. Server connection may fail"];
}
else if (err == noErr && result1 != nil ) {
SecCertificateRef certRef = (SecCertificateRef)CFArrayGetValueAtIndex(result1, 0);
CFDataRef certRefData = SecCertificateCopyData(certRef);
self.serverCertificateData = (NSData *)certRefData;
CFRelease(certRefData);
CFRelease(result1);
}
else {
[self messageBox:#"Warning" : #"Client or Server credentials not found. Server connection may fail"];
}
}
}
5. Authenticate server certificate and return client credentials
Hoo boy. This is an edit to explain how to actually use the retrieved certificates (it was supposed to be the easy obvious part...)
First, Apple's already dubious documentation is obsoleted by the new Application Transport Security framework (see for instance: http://useyourloaf.com/blog/app-transport-security/). I'm not going to get into it here but the idea is to force everyone to always use https and trusted certs by default. For my scenario, with certificate pinning and mutual authentication between dedicated clients and a private server you can safely turn this feature off by adding a dictionary to your plist as follows:
Next, in Step 4, you already had the client credential to respond to that challenge immediately when it hits but the server cert is floating around as NSData in DER format as created by SecCertificateCopyData and it is not clear what should happen when that challenge arrives.
Turns out that what you are supposed to do is implement the algorithm in section 6 of the "X.509 standard" (https://www.rfc-editor.org/rfc/rfc5280). Luckily, this is implemented behind the scenes by the iOS SecTrustEvaluate function but there is scaffolding to build and weird stuff to understand.
[Slight problem - ran out of space!! Added a new question, including the end of this step.]
https://stackoverflow.com/questions/35964632/correctly-use-a-pinned-self-signed-certificate-in-ios-9-2
[Continuing from other post]
So that's it. Sorry about the not quite production quality but I wanted to slap this together while it was still fresh in my mind. I will update the post if I find errors.
Hope this helps and here's a final link to a very good book that, amongst other things, will give you the creeps about trusting commercial CAs...
https://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf

Answer 2

[I just(!) realized I can add another answer since the continuation link was down-voted and closed and there are two requests for the additional information that wouldn't fit above. The answer below starts with the question in the deleted post]
...The part that I am still not clear about is why I had to create a new trust and policy to implement an anchor certificate and pinning.
If I simply added the anchor to the trust received from the server I could not successfully return the pointer to the NSURLCredential received from the server, it seemed to get modified and rejected by the sender(?).
The question is, is this really the appropriate processing or can it be condensed? This is getting a bit tiresome but I don't want to accept something just because it "works". My current solution is shown below.
In Step 4, you already had the client credential to respond to that type of challenge without manipulation but the server cert is floating around as NSData in DER format as created by SecCertificateCopyData and it is not clear what should happen when that challenge arrives.
Turns out that what you are supposed to do is implement the algorithm in section 6 of the "X.509 standard" (https://www.rfc-editor.org/rfc/rfc5280). Luckily, this is implemented behind the scenes by the iOS SecTrustEvaluate function but there is scaffolding to build and weird stuff to understand. First the code (following a hat tip to my original source):
SecTrustEvaluate always returns kSecTrustResultRecoverableTrustFailure with SecPolicyCreateSSL
- (void)_handleServerTrustChallenge {
OSStatus status;
BOOL trusted = false;
SecTrustResultType trustResult;
SecTrustRef serverTrust = self.challenge.protectionSpace.serverTrust;
NSURLCredential *credential = [NSURLCredential credentialForTrust:serverTrust]; //candidate credential for return to sender if valid
if (svDelegate.serverCertificateData) {
//locally stored information
SecCertificateRef storedCertificate = SecCertificateCreateWithData(NULL, (CFDataRef)svDelegate.serverCertificateData);
NSMutableArray *anchorCertArray = [NSMutableArray arrayWithCapacity:1];
[anchorCertArray addObject:(id)storedCertificate];
//incoming credentials from server
NSMutableArray *receivedCertChain = [NSMutableArray array];
for(int i = 0; i < SecTrustGetCertificateCount(serverTrust); i++)
[receivedCertChain addObject:(id) SecTrustGetCertificateAtIndex(serverTrust,i))];
//new custom policy object to use in creating new trust
//YES indicates extendedKeyUsage is set to serverAuth; effectively ignore server name check by specifying incoming name
SecPolicyRef newPolicyRef = SecPolicyCreateSSL(YES, (CFStringRef)self.challenge.protectionSpace.host);
//create and evaluate new trust with pinned certificate
SecTrustRef newTrustRef = NULL;
SecTrustCreateWithCertificates((CFArrayRef) receivedCertChain, newPolicyRef, &newTrustRef);
status = SecTrustSetAnchorCertificates(newTrustRef, (CFArrayRef) anchorCertArray);
if (status == noErr) status = SecTrustSetAnchorCertificatesOnly(newTrustRef, TRUE);
if (status == noErr) status = SecTrustEvaluate(newTrustRef, &trustResult);
//----- debug -------
//CFShow(newPolicyRef);
//NSLog(#"%#", receivedCertChain);
CFRelease(newTrustRef);
CFRelease(newPolicyRef);
CFRelease(storedCertificate);
}
else { //Server certificate not stored, rely on standard trusted Root CA authorities
status = SecTrustEvaluate(serverTrust, &trustResult);
}
trusted = (status == noErr) && (trustResult == kSecTrustResultUnspecified);
if (!trusted) credential = nil;
[self stopWithCredential:credential];
[self.delegate challengeHandlerDidFinish:self];
}
So first I check whether the server cert was loaded (else process via conventional trusted CA method).
Next you select the "trust object" to evaluate. I failed to do this without making a working copy of the trust object I received over the wire from the server b/c it somehow messed up the 'NSURLCredential *credential = [NSURLCredential credentialForTrust:serverTrust]' reference if I used it directly. It appears though from the truly horrible Apple docs that this is a kosher approach (I, for one, recommend skimming the x.509 rfc if you want to understand any of it).
https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/NetworkingTopics/Articles/OverridingSSLChainValidationCorrectly.html
[https://developer.apple.com/library/ios/technotes/tn2232/_index.html#//apple_ref/doc/uid/DTS40012884-CH1-SECCUSTOMROOT][2]
The trust requires a 'policy', the incoming certificate chain to evaluate, and one or more 'anchor certificates' which basically defines the origin in an arbitrary coordinate system - everything is validated downstream of the zero point even if it is not a root cert.
So you load the incoming chain and the stored cert into arrays to be provided to the new trust and create a new policy with SecPolicyCreateSSL - this sets a flag to indicate that the certificate should be checked to have been issued for serverAuth and that the incoming server name should be ignored (to allow some infrastructure flexibility).
Next you create the new trust using the new policy and the certificate array to be authenticated. Then you set the anchor and ensure that the chain will only be evaluated against your anchor cert, not just anything in the iOS keychain.
When you evaluate the trust it may seem odd that you accept kSecTrustResultUnspecified and not proceed or something more positive-sounding. In fact, proceed means you are following overrides from the user interface so that is actually bad; unspecified just means there's nothing wrong per the specified policy.
Finally, you return the credential from the incoming trust object (not the new one) and everything should be golden...