Keychain Storage
Keychain is an encrypted container (128 bit AES algorithm) and a centralized SQLite database that holds identities & passwords for multiple applications and network services, with restricted access rights. On the iPhone, keychain SQLite database is used to store the small amounts of sensitive data like usernames, passwords, encryption keys, certificates and private keys.
iOS applications use the keychain service library/API (secItemAdd, secItemDelete, secItemCopyMatching & secItemUpdate methods) to read and write data to and from the keychain. Developers leverage the keychain services API to dictate the operating system to store sensitive data securely on their behalf, instead of storing them in a property list file or a plaintext configuration file. On the iPhone, the keychain SQLite database file is located at – /private/var/Keychains/keychain-2.db.
Keychain contains a number of keychain items and each keychain item will have encrypted data and a set of unencrypted attributes that describes it. Attributes associated with a keychain item depend on the keychain item class (kSecClass). In iOS, keychain items are classified into 5 classes – generic passwords (kSecClassGenericPassword), internet passwords (kSecClassInternetPassword), certificates (kSecClassCertificate), keys (kSecClassKey) and digital identities (kSecClassIdentity, identity=certificate + key). In the iOS keychain, all the keychain items are stored in 4 tables – genp, inet, cert and keys. Genp table contains generic password keychain items, inet table contains Internet password keychain items, and cert & keys tables contain certificates, keys and digital identity keychain items.
Columns in the keychain tables are mapped to the corresponding keychain item class attributes.
genp table columns shown in below image are mapped to Generic password keychain item class attributes as shown in Table 1.
(Figure 1)
| column | Attribute | description |
| cdat | kSecAttrCreationDate | Item creation date in Unix epoch time format |
| mdat | kSecAttrModificationDate | Item modification date in Unix epoch time format |
| desc | kSecAttrDescription | User visible string that describes the item |
| icmt | kSecAttrComment | User editable comment for the item |
| crtr | kSecAttrCreator | Application created (4 char) code |
| type | kSecAttrType | Item type |
| scrp | kSecAttrScriptCode | String script code (such as encoding type) |
| labl | kSecAttrLabel | Label to be displayed to the user (print name) |
| alis | kSecAttrAlias | Item alias |
| invi | kSecAttrIsInvisible | Invisible |
| nega | kSecAttrIsNegative | Invalid item |
| cusi | kSecAttrHasCustomIcon | Existence of application specific icon (Boolean) |
| prot | kSecProtectedDataItemAttr ? | Item’s data is protected (Boolean) |
| acct | kSecAttrAccount | Account key (such as user id) |
| svce | kSecAttrService | Service name (such as Application identifier) |
| gena | kSecAttrGeneric | User defined attribute |
| data | kSecValueData |
Actual data (such as password, crypto key…) |
| agrp | kSecAttrAccessGroup | Keychain access group |
| pdmn | kSecAttrAccessible | Access restrictions (Data protection classes) |
Table 1
Attributes for all the keychain item classes are documented in the Keychain Item class keys and Values section in Apple’s documentation.The keychain database is encrypted with a hardware-specific key which is unique per the device. The hardware key cannot be extracted from the device, so the data stored in the keychain can only be accessible on the device itself and cannot be moved to another device. The keychain database is tied to the device, so even if an attacker obtains access to the keychain through physical access to the file system or in a remote attack, he cannot decrypt and view the file contents. The keychain file format is shown in Table 2.
| Version | Protection class | len_wrapped key | AESWRAP (class key, item key, len_wrapped key) | AES256_GCM(item key, data) | Integrity tag(16 bytes) |
Keychain data is logically zoned and data stored by one application is not accessible to another application. Keychain data of an iOS application is stored outside the application’s sandbox. So the operating system process securityd enforces the access control and regulates access to the keychain data in such a way that the applications with correct permissions can read their data. Keychain access permissions of an iOS application are defined in the code sign entitlements. Keychain Services uses these entitlements to grant permissions for the applications to access its own keychain items.
Entitlements of an application define the properties that provide access to the iOS features such as push notifications, keychain access and iCloud communication, etc… Entitlements grant specific capabilities or security permissions to iOS applications. An entitlement file for a keychain data sharing application contains an application-identifier and may contain a set of keychain-access-groups constants. In iOS, each application ships with a unique application-identifier. The keychain service restricts the keychain data access based on this application identifier. By default, applications can only access data associated with their own application-identifier.
Later, to share the keychain items with multiple applications, keychain-access-groups were introduced. Applications with the same keychain access group entitlement can access/share the keychain items. Entitlements of an application are embedded in the application binary and stored unencrypted. So, on a JailBroken iPhone, entitlements of an application can be extracted from the application binary using grep or sed commands (stream editor – sed can be downloaded from Cydia packages).
To list out the entitlements of an iOS application, connect to the iPhone over SSH, navigate to the application’s home directory (/var/mobile/Applications/[unique-id]/) and run the below command.
[CODE]
sed -n ‘//,/<\/dict>/p’ [AppDirectory]/[ApplicationBinary]
[/CODE]
For example below command will list out the entitlements of Facebook iOS application.
[CODE]
> sed -n ‘//,/<\/dict>/p’ Facebook.app/Facebook application-identifier T84QZS65DQ.com.facebook.Facebook aps-environment production keychain-access-groups T84QZS65DQ.platformFamily
[/CODE]
Facebook iOS application is a fat binary (built for ARM6 & ARM7 architectures), so the above command will print the entitlement details twice.
The above result shows that the Facebook iOS application uses ‘T84QZS65DQ.platformFamily’ keychain-access-group while storing the entries in the keychain.
When an application adds an entry to the keychain, an application identifier or keychain access group of the application also gets added to the keychain item agrp (access group) column. Later, when an application tries to access the keychain item, the keychain service verifies the application identifier or keychain access group against the agrp value of corresponding keychain item to permit the access. A sample keychain-2.db file is shown in Figure 3 and Facebook entitlements are highlighted.
(Figure2)
Note--> Applications that are built for the simulator use the same default keychain access group. So on the simulator, all the applications can access all the keychain items.
With the introduction of data protection mechanisms in iOS, sensitive data stored in the keychain item is protected with another layer of encryption which is tied to the user’s passcode. Data protection encryption keys (protection class keys) are derived from a device’s hardware key and a key generated from the user’s passcode. So encryption offered by data protection API is as good as the strength of a user’s passcode. Data protection is designed to protect the user’s data in case a device is lost or stolen. Data protection for the keychain items can be enabled by supplying an accessibility constant value to the kSecAttrAccessible attribute of SecItemAdd or SecItemUpdate methods.
Data protection accessibility constants determine when a keychain item should be readable by an application. They also determine whether a keychain item is allowed to migrate to other devices or not. During an iTunes backup, all the data stored in the iOS device is backed up to the computer including the keychain database. On the iTunes backups, the keychain SQLite database is stored as a Plist file (Keychain-backup.plist). Keychain items which are backed-up with the iTunes encrypted backup option can be moved/loaded to another device. However the keychain items which are protected with ThisDeviceOnly constants cannot be moved to other iOS devices.
Below is the list of keychain item accessibility constants –
- kSecAttrAccessibleWhenUnlocked
- Keychain item is accessible only after the device is unlocked
- Data protection class keys required to decrypt the keychain items are loaded into memory only when the device is unlocked and the encryption keys are automatically purged in 10 seconds once the device is locked.
- kSecAttrAccessibleAfterFirstUnlock
- Keychain item is accessible only after the first unlock of the device until reboot
- Data protection class keys required to decrypt the keychain items are loaded into memory only when the user unlocks the device after a reboot, and the keys remain in the memory til next reboot of the device.
- kSecAttrAccessibleAlways
- Keychain item is accessible even when the device is locked
- Data protection class keys required to decrypt the keychain items are always loaded into memory.
- kSecAttrAccessibleWhenUnlockedThisDeviceOnly
- Keychain item is accessible only after the device is unlocked, and the item cannot be migrated between devices.
- kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
- Keychain item is accessible after the first unlock of the device and the item cannot be migrated between devices.
- kSecAttrAccessibleAlwaysThisDeviceOnly
- Keychain item is accessible even when the device is locked and the item cannot be migrated between devices.
| pdmn | Keychain accessibility constants |
| ak | kSecAttrAccessibleWhenUnlocked |
| ck | kSecAttrAccessibleAfterFirstUnlock |
| dk | kSecAttrAccessibleAlways |
| aku | kSecAttrAccessibleWhenUnlockedThisDeviceOnly |
| cku | kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly |
| dku | kSecAttrAccessibleAlwaysThisDeviceOnly |
(Table 3)












