iOS Components and Frameworks: Understanding the Advanced Features of the iOS SDK (2014)

---

Setting Up and Using Keychain

Keychain is part of the Security.framework and has been available for iOS starting with the initial SDK release. Keychain has its roots in Mac OS X development, where it was first introduced with OS X 10.2. However, Keychain’s history predates even OS X with roots back into OS 8.6. Keychain was initially developed for Apple’s email system called PowerTalk.

Keychain can be used to secure small amounts of data such as passwords, keys, certificates, and notes. However, if an app is securing large amounts of information such as encoded images or videos, implementing a third-party encryption library is usually a better fit than Keychain. Core data also provides encryption capabilities, and is worth exploring if the app will be Core Data–based.

Before working with Keychain, the Security.framework must be added to the project and <Security/Security.h> needs to be imported to any classes directly accessing Keychain methods and functions.

Setting Up a New KeychainItemWrapper

On iOS Keychains are unlocked based on the code signing of the app that is requesting it. Since there is no systemwide password as seen on OS X, there needs to be an additional step to secure data. Since the app controls which Keychain data can be accessed to truly secure information, the app itself should be password protected. This is done through the sample app using a PIN entry system.

When the app is launched for the first time, it will prompt the user to enter a new PIN and repeat it. To securely store the PIN, a new KeychainItemWrapper is created.

pinWrapper = [[KeychainItemWrapper alloc]initWithIdentifier:@"com.ICF.Keychain.pin" accessGroup:nil];

Creating a new KeychainItemWrapper is done using two attributes. The first attribute is an identifier for that Keychain item. It is recommended that a reverse DNS approach be used here such as com.company.app.id. accessGroup is set to nil in this example, and theaccessGroup parameter is used for sharing Keychains across multiple apps. Refer to the section “Sharing a Keychain Between Apps” for more information on accessGroups.

The next attribute that should be set on a new KeychainItemWrapper is the kSecAttrAccessible. This controls when the data will be unlocked. In the sample app the data becomes available when the device is unlocked, securing the data for a locked device. There are several possible options for this parameter, as detailed in Table 18.1.

[pinWrapper setObject:kSecAttrAccessibleWhenUnlocked forKey: (id)kSecAttrAccessible];

Table 18.1 All Possible Constants and Associated Descriptions to Be Supplied to kSecAttrAccessible

The app now knows the identifier for the Keychain as well the security level that is required of it. However, an additional parameter needs to be set before data can begin to be stored. The kSecAttrService is used to store a username for the password pair that will be used for the PIN. A PIN does not have an associated password; for the purposes of the sample app, pinIdentifer is used here. Although Keychains will often work while the kSecAttrService is omitted, having a value set here corrects many hard-to-reproduce failures.

[pinWrapper setObject:@"pinIdentifer" forKey: (id)kSecAttrAccount];

Storing and Retrieving the PIN

After a new KeychainItemWrapper has been configured in the manner described in the preceding section, data can be stored into it. Storing information in a Keychain is very similar to storing data in a dictionary. The sample app first checks to make sure that both of the PIN text fields match; then it calls setObject: on the pinWrapper that was created in the preceding section. For the key identifier kSecValueData is used. This item is covered more in depth in the section “Keychain Attribute Keys”; for now, however, it is important to use this constant.

if([pinField.text isEqualToString: pinFieldRepeat.text])
{
[pinWrapper setObject:[pinField text] forKey:kSecValueData];
}

After a new value has been stored into the Keychain, it can be retrieved in the same fashion. To test whether the user has entered the correct PIN in the sample app, the following code is used:

if([pinField.text isEqualToString: [pinWrapper objectForKey:kSecValueData]])

After the PIN number being entered has been confirmed as the PIN number stored in the Keychain, the user is allowed to access the next section of the app, described in the section “Securing a Dictionary.”

Keychain Attribute Keys

Keychains are stored much like NSDictionaries; however, they have very specific keys that can be associated with them. Unlike an NSDictionary, a Keychain cannot use any random string for a key value. Each Keychain is associated with a Keychain Class; if using Apple’sKeychainItemWrapper, it defaults to using CFTypeRef kSecClassGenericPassword. However, other options exist for kSecClassInternetPassword, kSecClassCertificate, kSecClassKey, and kSecClassIdentity. Each class has different associated values attached to it. For the purposes of this chapter as well as for the KeychainItemWrapper, the focus will be on kSecClassGenericPassword.

kSecClassGenericPassword contains 14 possible keys for storing and accessing data, as described in Table 18.2. It is important to keep in mind that these keys are optional and are not required to be populated in order to function correctly.

Table 18.2 Keychain Attribute Keys Available When Working with kSecClassGenericPassword

Securing a Dictionary

Securing a more complex data type such as a dictionary follows the same approach taken to secure the PIN in earlier sections. The Keychain wrapper only allows for the storage of strings; to secure a dictionary, it is first turned into a string. The approach chosen for the sample code is to first save the dictionary to a JSON string using the NSJSONSerialization class. (See Chapter 7, “Working with and Parsing JSON,” for more info.)

NSMutableDictionary *secureDataDict = [[[NSMutableDictionary alloc] init] autorelease];

NSError *error = nil;

if(numberTextField.text)
[secureDataDict setObject:numberTextField.text forKey:@"numberTextField"];

if(expDateTextField.text)
[secureDataDict setObject:expDateTextField.text forKey:@"expDateTextField"];

if(CV2CodeTextField.text)
[secureDataDict setObject:CV2CodeTextField.text forKey:@"CV2CodeTextField"];

if(nameTextField.text)
[secureDataDict setObject:nameTextField.text forKey:@"nameTextField"];

NSData *rawData = [NSJSONSerialization dataWithJSONObject:secureDataDict
options:0
error:&error];

if(error != nil)
{
NSLog(@"An error occurred: %@", [error localizedDescription]);
}

NSString *dataString = [[[NSString alloc] initWithData:rawData encoding:NSUTF8StringEncoding] autorelease];

After the value of the dictionary has been converted into a string representation of the dictionary data, it can be added to the Keychain in the same fashion as previously discussed.

KeychainItemWrapper *secureDataKeychain = [[KeychainItemWrapper alloc] initWithIdentifier:@"com.ICF.keychain.securedData" accessGroup:nil];

[secureDataKeychain setObject:@"secureDataIdentifer" forKey: (id)kSecAttrAccount];

[secureDataKeychain setObject:kSecAttrAccessibleWhenUnlocked forKey: (id)kSecAttrAccessible];

[secureDataKeychain setObject:dataString forKey:kSecValueData];

[secureDataKeychain release];

To retrieve the data in the form of a dictionary, the steps must be followed in reverse. Starting with an NSString from the Keychain, it is turned into a NSData value. The NSData is used with NSJSONSerialization to retrieve the original dictionary value. After the dictionary is re-created, the text fields that display the user’s credit card information are populated.

KeychainItemWrapper *secureDataKeychain = [[KeychainItemWrapper alloc] initWithIdentifier:@"com.ICF.keychain.securedData" accessGroup:nil];

NSString *secureDataString = [secureDataKeychain objectForKey:kSecValueData];

if([secureDataString length] != 0)
{
NSData* data = [secureDataString dataUsingEncoding:NSUTF8StringEncoding];

NSError *error = nil;

NSDictionary *secureDataDictionary = [NSJSONSerialization JSONObjectWithData:data
options:NSJSONReadingMutableContainers
error:&error];

if(error != nil)
{
NSLog(@"An error occurred: %@", [error localizedDescription]);
}

numberTextField.text = [secureDataDictionary objectForKey:@"numberTextField"];

expDateTextField.text = [secureDataDictionary objectForKey:@"expDateTextField"];

CV2CodeTextField.text = [secureDataDictionary objectForKey:@"CV2CodeTextField"];

nameTextField.text = [secureDataDictionary objectForKey:@"nameTextField"];
}

else
{
NSLog(@"No Keychain data stored yet");
}

Resetting a Keychain Item

At times it might be necessary to wipe out the data in a Keychain while not replacing it with another set of user data. This can be done using Apple’s library by invoking the resetKeyChainItem method on the Keychain wrapper that needs to be reset.

[pinWrapper resetKeychainItem];

Sharing a Keychain Between Apps

A Keychain can be shared across multiple iOS apps if they are published by the same developer and under certain conditions. The most important requirement for sharing Keychain data between two apps is that both apps must have the same bundle seed. For example, consider two apps with the bundle identifiers 659823F3DC53.com.ICF.firstapp and 659823F3DC53.com.ICF.secondapp. These apps would be able to access and modify each other’s Keychain data. Keychain sharing with a wildcard ID does not seem to work, although the official documentation remains quiet on this situation. Bundle seeds can be configured from the developer portal when new apps are created.

When you have two apps that share the same bundle seed, each app will need to have its entitlements configured to allow for a Keychain access group. Starting with Xcode 4.5, Keychain Groups are configured from the summary tab of the target, as shown in Figure 18.1. Before Xcode 4.5, the bundle ID with seed needed to be added to the entitlements file under the array for the key keychain-access-groups. When using the newer Keychain Group entries, you should omit the bundle seed.

Figure 18.1 Setting up a new Keychain Group using Xcode 4.5 or newer.

For the shared Keychain to be accessed, the Keychain group first needs to be set. With a modification of the PIN example from earlier in the chapter, it would look like the following code snippet:

[pinWrapper setObject:@"659823F3DC53.com.ICF.appgroup" forKey:(id)kSecAttrAccessGroup];