Howto use the Keychain in iPhone SDK to store and retrieve secure Data

When you need to store data securely from within your iPhone application, sooner or later you will step over the iPhone keychain. This is the super-duper built-in iPhone safe, kindly provided to you by the fruit company.

Now - take your time to praise Apple for being so wise and foresighted to supply you with the cooked equipment for secure data storage...

..did you do well? Did you rag on some dump Windows users? Fine, then here is one more thing: The stuff ain't that simple to use. Of course, as a blessed Apple user you would expect a simple interface in the fashion of "[keychain getMySecretData] [keychain storeMySecretData]". But when you take a closer look at it you will find that it is rather half-baked - and implementing keychain access might take a little more than a one-buttoned mouse.

First of all, there ain't an easy-to-use keychain API in any of the frameworks delivered with the iPhone SDK. You would have to deal with weird C function calls. For instance, to retrieve data from the keychain you have to invoke something called SecItemCopyMatching, passing in a dictionary as parameter. Completely self explanatory, isn't it? If you're getting curious, you can dive into the secrets of keychain services here. Though in this programming guide the Apple guys are not getting bored emphasizing the straightforwardness and ease of use of the keychain API - there seems to be a little doubt, though.  Cause in the code examples accompanying the guidelines, they build an object-oriented wrapper class around all this cute C-function magic. And this is where we join the game..

The complete example application provided by Apple can be found here. But the only thing of interest to us is the KeyChainItemWrapper. You can think of a keychain item as a record stored in the keychain database. Each keychain item consists of unencrypted attributes, and the actual data, which is encrypted. For instance, a password keychain item could have the account name set as one of its attributes, and the password itself be stored as keychain item data. Apple defines these types (aka classes) of keychain items:

• Generic Password
• Internet Password
• Certificate
• Cryptographic Key
• Digital Identity

Keychain item classes differ in the attributes and structure of item data.

The KeyChainItemWrapper is a kind of object-oriented wrapper around a Generic Password keychain item, providing methods for item creation and modification:

- (id)initWithIdentifier: (NSString *)identifier accessGroup:(NSString *) accessGroup

Creates a Generic Password keychain item. If an item with provided identifier is already stored in the keychain data base, it will load its data. If not, it will create a new one and initialize it with empty strings. The identifier should be a string identifying the account the password stored in the keychain item belongs to.

The access group can be used to share the keychain item among different applications. So in most cases, you will not need it, and it can be set to nil.

- (void)setObject:(id)inObject forKey:(id)key

Depending on the value you provide for key, it stores the inObject as keychain item attribute, or encrypted keychain item data. To gain reasonable results, you MUST use the constants defined in the keychain services API for the key. For example, to store an ecrypted password, kSecValueData must be the key, and the actual password must be the inObject. To store a login name as keychain item attribute, use kSecAttrAccount for key, and the login name for inObject.

No later than here you recognize, that even the "object-oriented" KeyChainItemWrapper is not object-oriented, but at most "objective". In a serious object-oriented language, they would have given us methods like [keyChainItem setPassword] and [keyChainItem setAccount]. In reality, we have to tell what we want by passing cryptic constants to generic methods. Well, you will have to get used to it: It's the Apple guys - they don't care about user requirements, they define them themselves.

- (id)objectForKey:(id)key

Get an attribute or data out of the keychain. Just as mentioned in the previous section, you will have to use the pre-defined keychain services API constants for key.

- (void)resetKeychainItem

Delete all attributes and data of the keychain item, and initialize them with empty strings. Note: This does not delete the keychain item itself! Deleting a keychain item is not implemented in the Apple example.
 
Here is a small code example of how to write to and read from the keychain:

- (void) savePassword: (NSString*) password {     [self.keychainItemWrapper setObject:password forKey:            (id)kSecValueData]; } - (void) retrievePassword {     return (NSString*) [self.keychainItemWrapper objectForKey:            (id)kSecValueData]; }

Well, now you should be equipped with the basic knowledge to integrate a secure, keychain-based password storage into your iPhone application. 

Don't forget to add the Security.framework to your Xcode project if you want to use the KeyChainItemWrapper!

One important thing to mention is, that with the latest version 1.2, the KeyChainItemWrapper also works on the iPhone simulator. In prior versions it did not. The programmers just forgot to mention this in the revision history. The only thing you cannot use on the simulator is the ability to share keychain items among different applications using an accessGroup. 

I think, you'll get over it.. 

You can find a very good, more detailed overview of the keychain API in this blog post.