Apple’s Security framework contains the class KeychainItem, technically just a dictionary that is being used for transmitting data between the accessible part of iOS and the encrypted sensitive data that is stored unaccessible to the programmer and anyone else, and a lot of methods and special pointers for certificates and key pairs.

Currently, only the most frequently needed methods are implemented, namely writing and reading passwords and additional data. iOSLib is prepared for the other Security features too, but I personally have no use for them currently. Please contact me if you need more advanced features.

Being more or less a framework in itself, I included AppleLAContext and its convenience wrapper iOSLibTouchID here too. With them you can unlock a TouchID enabled device via the user’s fingerprint.

General information

The key to a keychainItem are a Service and an Account Text identifier. These unlock access to the respective keychainitem much like a username/password combination.

It is common practice to use a Service identifier in the form of a bundle identifier, i.e. com.satzservice.iOSLibUnified. You are not limited to this form.

The KeychainItem is in itself just an AppleDictionary. I have provided iOSLib’s implementation AppleKeychainItem with all the constants that are allowed as keys in a keychainitem and built computed properties around them. You should therefore not confuse Integer properties that show a 0 in debugger with those that really exist. Clarity brings you a closer examination of either the DebugDescription or the StringsFileFormat property that AppleKeychainItem inherits from its super classes.

In most of the cases, you will restrict yourself two a few properties, mostly the password itself and a few additions. Pardon me if the current documentation lists only these. Other methods have not been tested yet and as written before I wouldn’t even know what to look for. Again: If you need more features or encounter problems, please tell me. Security/KeychainItem is not that easy to handle. I tried to make the entry point easy but there will be tons of features missing for more advanced uses.

Let‘s examine the KeychainItem‘s main features:

AppleKeychainItem

Constructor

Constructor(): Creates a new, empty Keychainitem.

Main Properties

See above. There’s a lot of more virtual properties to easily read and write the contents. You find a full description of the possible values under Apple’s Keychain Reference.
The following are tha main properties that are read and written in the Secuirty/Keychain Demo view in the Control extensions demo project.

Account As Text: The account name for Security access. That’s one of the two main properties describes above.

ServiceName As Text: The service name to register under, the second of the main properties.

Comment As Text: An optional comment.

Description As Text: An optional descriptive text.

Label As Text: An optional label.

Password As Text: The password. Instead of the other text properties, it is handled internally in form of UTF8-encoded AppleData.

Methods

AddItem() As Int32: Tries to add the item to the keychain and returns a result. 0 if successful.

SetMatchLimit (SearchAll as Boolean, Limit As Integer = 0): Modifies the MatchLimit Key of a keychainitem used for queries to return an array (all matching keychainitems; SearchAll = true), 1 item (SearchAll = false, Limit = 1) or a certain number. Not useful currently as there is no convenience method handling an array of keychainitems yet.

UpdateItem (QueryDictionary As AppleKeychainItem) As Int32: Tries to modify the keychainitem it gets after querying with the content of the current KeychainItem. This item must only contain "real" keychaindata, no metadata like ServiceName or Account. Returns a Result, 0 if successful.

Saving a KeychainItem

For saving a password and a description, do the following:

• Create a new KeychainItem: Dim myitem As new AppleKeychainItem
• Set its identifier properties: myItem.ServiceName = "com.satzservice.iOSLibUnified"
myItem.Account = "myAccountName"
• Set a password: myItem.Password = "mySecretPassword"
• Set a Description: myItem.Description = "This is the password I need to access the hidden Server"
• Add it to the Keychain: Dim Result as Int32 = myItem.Additem

If Result is 0, everything went well. If it is not, use

Dim ErrorText As Text = SecurityFramework.OSStatusErrorText (Result)
to get a clue on what went wrong.

Reading a KeychainItem

Dim ResultItem As AppleKeychainitem = SecurityFramework.ReadKeychainItem (_ServiceName as Text, Account as Text_, _optional_ result as int 32)

is all to get the resulting keychainitem registerd for service and account. Again you can examine the optional result integer if it should not be 0 with SecurityFramework.OSStatusErrorText.

Updating a KeychainItem

• Create a new KeychainItem: Dim myitem As new AppleKeychainItem
• Do not set ServiceName and Account! Do only set the Item properties you want to modify!: myItem.Description = "New description"**
• Create another QueryKeychainitem: Dim Query as AppleKeychainitem = SecurityFramework.MakeQueryKeychainItem (_ServiceName as Text_, _Account As Text_)
  Call the update method: Dim Result As Int32 = myItem.UpdateItem (Query)

Again, Result can be interpreted by SecurityFramework.OSStatusErrorText.

Deleting a KeychainItem

Dim Result As Int32 = SecurityFramework.DeleteKeychainItem (ServiceName As Text, Account As Text)