Reading and Saving Passwords Using Keychain in Swift

Keychain Services is a secure storage interface for macOS and iOS best used for small pieces of private data like passwords, cookies, and authentication tokens. This post presents an example implementation using Keychain Services for a storing and getting passwords:

  1. Saving Data To Keychain
  2. Updating Data In Keychain
  3. Reading Data From Keychain
  4. Deleting Data In Keychain
  5. Syncing Keychain With iCloud

Throughout this post documented code samples will be provided from an example implementation using Keychain Services, the KeychainInterface class. KeychainInterface will handle various Keychain errors that are important to understand:

class KeychainInterface {
    enum KeychainError: Error {
        // Attempted read for an item that does not exist.
        case itemNotFound
        
        // Attempted save to override an existing item.
        // Use update instead of save to update existing items
        case duplicateItem
        
        // A read of an item in any format other than Data
        case invalidItemFormat
        
        // Any operation result status than errSecSuccess
        case unexpectedStatus(OSStatus)
    }
}

Saving Data To Keychain

SecItemAdd in Swift

SecItemAdd is used to save new items to Keychain. An item is uniquely identified by query, a CFDictionary that specifies the item's:
a. Service, kSecAttrService, a string to identify a set of Keychain Items like “com.my-app.bundle-id”
b. Account, kSetAttrAccount, a string to identify a Keychain Item within a specific service, like “username@email.com”
c. Class, kSecClass, a type of secure data to store in a Keychain Item, like kSecClassGenericPassword

The second argument result is an UnsafeMutablePointer to any return value specified by query. Often no return data is expected and nil can be passed for result.

func SecItemAdd(
    _ attributes: CFDictionary, 
    _ result: UnsafeMutablePointer<CFTypeRef?>?
) -> OSStatus

Saving Data To Keychain Example

static func save(password: Data, service: String, account: String) throws {

    let query: [String: AnyObject] = [
        // kSecAttrService,  kSecAttrAccount, and kSecClass
        // uniquely identify the item to save in Keychain
        kSecAttrService as String: service as AnyObject,
        kSecAttrAccount as String: account as AnyObject,
        kSecClass as String: kSecClassGenericPassword,
        
        // kSecValueData is the item value to save
        kSecValueData as String: password as AnyObject
    ]
    
    // SecItemAdd attempts to add the item identified by
    // the query to keychain
    let status = SecItemAdd(
        query as CFDictionary,
        nil
    )

    // errSecDuplicateItem is a special case where the
    // item identified by the query already exists. Throw
    // duplicateItem so the client can determine whether
    // or not to handle this as an error
    if status == errSecDuplicateItem {
        throw KeychainError.duplicateItem
    }

    // Any status other than errSecSuccess indicates the
    // save operation failed.
    guard status == errSecSuccess else {
        throw KeychainError.unexpectedStatus(status)
    }
}

Updating Data In Keychain

SecItemUpdate in Swift

SecItemUpdate is used to override existing data in Keychain. Like SecItemAdd, the Keychain item to override is identified by query. Unlike SecItemAdd, SecItemUpdate expects the new value of the Keychain item to be passed inside a different argument attributesToUpdate using the same key, kSecValueData.

func SecItemUpdate(
    _ query: CFDictionary, 
    _ attributesToUpdate: CFDictionary
) -> OSStatus

Updating Data In Keychain Example

static func update(password: Data, service: String, account: String) throws {
    let query: [String: AnyObject] = [
        // kSecAttrService,  kSecAttrAccount, and kSecClass
        // uniquely identify the item to update in Keychain
        kSecAttrService as String: service as AnyObject,
        kSecAttrAccount as String: account as AnyObject,
        kSecClass as String: kSecClassGenericPassword
    ]
    
    // attributes is passed to SecItemUpdate with
    // kSecValueData as the updated item value
    let attributes: [String: AnyObject] = [
        kSecValueData as String: password as AnyObject
    ]
    
    // SecItemUpdate attempts to update the item identified
    // by query, overriding the previous value
    let status = SecItemUpdate(
        query as CFDictionary,
        attributes as CFDictionary
    )

    // errSecItemNotFound is a special status indicating the
    // item to update does not exist. Throw itemNotFound so
    // the client can determine whether or not to handle 
    // this as an error
    guard status != errSecItemNotFound else {
        throw KeychainError.itemNotFound
    }

    // Any status other than errSecSuccess indicates the
    // update operation failed.
    guard status == errSecSuccess else {
        throw KeychainError.unexpectedStatus(status)
    }
}

Reading Data From Keychain

SecItemCopyMatching in Swift

Like SecItemAdd, SecItemCopyMatching method has an UnsafeMutablePointer argument as well as a query argument. Data read by SecItemCopyMatching will be copied into the UnsafeMutablePointer result for access by your macOS and iOS app.

In this implementation, SecItemCopyMatching is expected to copy the data of the stored item in Keychain. This is implemented by setting kSecReturnData to kCFBooleanTrue in the query.

func SecItemCopyMatching(
    _ query: CFDictionary, 
    _ result: UnsafeMutablePointer<CFTypeRef?>?
) -> OSStatus

Getting Data From Keychain Example

static func readPassword(service: String, account: String) throws -> Data {
    let query: [String: AnyObject] = [
        // kSecAttrService,  kSecAttrAccount, and kSecClass
        // uniquely identify the item to read in Keychain
        kSecAttrService as String: service as AnyObject,
        kSecAttrAccount as String: account as AnyObject,
        kSecClass as String: kSecClassGenericPassword,
        
        // kSecMatchLimitOne indicates keychain should read
        // only the most recent item matching this query
        kSecMatchLimit as String: kSecMatchLimitOne,

        // kSecReturnData is set to kCFBooleanTrue in order
        // to retrieve the data for the item
        kSecReturnData as String: kCFBooleanTrue
    ]

    // SecItemCopyMatching will attempt to copy the item
    // identified by query to the reference itemCopy
    var itemCopy: AnyObject?
    let status = SecItemCopyMatching(
        query as CFDictionary,
        &itemCopy
    )

    // errSecItemNotFound is a special status indicating the
    // read item does not exist. Throw itemNotFound so the
    // client can determine whether or not to handle 
    // this case
    guard status != errSecItemNotFound else {
        throw KeychainError.itemNotFound
    }
    
    // Any status other than errSecSuccess indicates the
    // read operation failed.
    guard status == errSecSuccess else {
        throw KeychainError.unexpectedStatus(status)
    }

    // This implementation of KeychainInterface requires all
    // items to be saved and read as Data. Otherwise, 
    // invalidItemFormat is thrown
    guard let password = itemCopy as? Data else {
        throw KeychainError.invalidItemFormat
    }

    return password
}

Deleting Data In Keychain

SecItemDelete in Swift

Like the other Keychain methods, SecItemDelete takes in a query and returns an OSStatus. Keychain will delete permanently associate data with the items matching the query.

func SecItemDelete(
    _ query: CFDictionary
) -> OSStatus

Keychain Delete Example

static func deletePassword(service: String, account: String) throws {
    let query: [String: AnyObject] = [
        // kSecAttrService,  kSecAttrAccount, and kSecClass
        // uniquely identify the item to delete in Keychain
        kSecAttrService as String: service as AnyObject,
        kSecAttrAccount as String: account as AnyObject,
        kSecClass as String: kSecClassGenericPassword
    ]

    // SecItemDelete attempts to perform a delete operation
    // for the item identified by query. The status indicates
    // if the operation succeeded or failed.
    let status = SecItemDelete(query as CFDictionary)

    // Any status other than errSecSuccess indicates the
    // delete operation failed.
    guard status == errSecSuccess else {
        throw KeychainError.unexpectedStatus(status)
    }
}

Syncing Keychain With iCloud

It is possible to automatically sync a user’s Keychain data with that user’s iCloud, if iCloud Keychain Synchronization is enabled. To do so, set kSecAttrSynchronizable to kCFBooleanTrue when constructing a Keychain Services query for all Keychain operations:

query[kSecAttrSynchronizable as String] = kCFBooleanTrue

Why not use KeychainAccess, KeychainSwift, or other Cocoapods to access Keychain?

Many apps do not require complex Keychain Services behavior beyond what Apple-provided methods like SecItemAdd, SecItemUpdate, SecItemCopyMatching, and SecItemDelete. By using Apple-provided methods to work with Keychain Services and storing secure data, a developer can:

  • simplify the codebase by removing third-party dependencies like KeychainAccess and KeychainSwift
  • reduce the binary size of the application
  • reduce risk associated with relying on third-party dependencies

Getting And Saving Secure Data From Keychain Services in Swift on iOS and macOS

That’s it! By understanding SecItemAdd, SecItemUpdate, SecItemCopyMatching, and SecItemDelete you can implement Keychain Services to save sensitive and private data in your macOS and iOS application.