KeychainAccess

KeychainAccess is a simple Swift wrapper for Keychain that works on iOS and OS X. Makes using Keychain APIs extremely easy and much more palatable to use in Swift.

💡 Features

Simple interface
Support access group
Support accessibility
Support iCloud sharing
Support TouchID and Keychain integration (iOS 8+)
Support Shared Web Credentials (iOS 8+)
Works on both iOS & OS X
watchOS and tvOS are supported
Swift 3 & Swift 2.3 compatible

📖 Usage

👀 See also:

🔑 Basics

Saving Application Password

letkeychain=Keychain(service:"com.example.github-token")keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

Saving Internet Password

letkeychain=Keychain(server:"https://github.com", protocolType:.https)keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

🔑 Instantiation

Create Keychain for Application Password

letkeychain=Keychain(service:"com.example.github-token")

letkeychain=Keychain(service:"com.example.github-token", accessGroup:"12ABCD3E4F.shared")

Create Keychain for Internet Password

letkeychain=Keychain(server:"https://github.com", protocolType:.https)

letkeychain=Keychain(server:"https://github.com", protocolType:.https, authenticationType:.htmlForm)

🔑 Adding an item

subscripting

for String

keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

keychain[string:"kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

for NSData

keychain[data:"secret"]=NSData(contentsOfFile:"secret.bin")

set method

keychain.set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")

error handling

do{try keychain.set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{print(error)}

🔑 Obtaining an item

subscripting

for String (If the value is NSData, attempt to convert to String)

lettoken=keychain["kishikawakatsumi"]

lettoken=keychain[string:"kishikawakatsumi"]

for NSData

letsecretData=keychain[data:"secret"]

get methods

as String

lettoken=try? keychain.get("kishikawakatsumi")

lettoken=try? keychain.getString("kishikawakatsumi")

as NSData

letdata=try? keychain.getData("kishikawakatsumi")

🔑 Removing an item

subscripting

keychain["kishikawakatsumi"]=nil

remove method

do{try keychain.remove("kishikawakatsumi")}catchlet error{print("error: \(error)")}

🔑 Set Label and Comment

letkeychain=Keychain(server:"https://github.com", protocolType:.https)do{try keychain
.label("github.com (kishikawakatsumi)").comment("github access token").set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{print("error: \(error)")}

🔑 Obtaining Other Attributes

PersistentRef

letkeychain=Keychain()letpersistentRef=keychain[attributes:"kishikawakatsumi"].persistentRef
...

Creation Date

letkeychain=Keychain()letcreationDate=keychain[attributes:"kishikawakatsumi"].creationDate
...

All Attributes

letkeychain=Keychain()do{letattributes=try keychain.get("kishikawakatsumi"){ $0 }print(attributes.comment)print(attributes.label)print(attributes.creator)...}catchlet error{print("error: \(error)")}

subscripting

letkeychain=Keychain()letattributes=keychain[attributes:"kishikawakatsumi"]print(attributes.comment)print(attributes.label)print(attributes.creator)

🔑 Configuration (Accessibility, Sharing, iCloud Sync)

Provides fluent interfaces

letkeychain=Keychain(service:"com.example.github-token").label("github.com (kishikawakatsumi)").synchronizable(true).accessibility(.afterFirstUnlock)

Accessibility

Default accessibility matches background application (=kSecAttrAccessibleAfterFirstUnlock)

letkeychain=Keychain(service:"com.example.github-token")

For background application

Creating instance

letkeychain=Keychain(service:"com.example.github-token").accessibility(.afterFirstUnlock)keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

One-shot

letkeychain=Keychain(service:"com.example.github-token")do{try keychain
.accessibility(.afterFirstUnlock).set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{print("error: \(error)")}

For foreground application

Creating instance

letkeychain=Keychain(service:"com.example.github-token").accessibility(.whenUnlocked)keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

One-shot

letkeychain=Keychain(service:"com.example.github-token")do{try keychain
.accessibility(.whenUnlocked).set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{print("error: \(error)")}

👫 Sharing Keychain items

letkeychain=Keychain(service:"com.example.github-token", accessGroup:"12ABCD3E4F.shared")

🔄 Synchronizing Keychain items with iCloud

Creating instance

letkeychain=Keychain(service:"com.example.github-token").synchronizable(true)keychain["kishikawakatsumi"]="01234567-89ab-cdef-0123-456789abcdef"

One-shot

letkeychain=Keychain(service:"com.example.github-token")do{try keychain
.synchronizable(true).set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{print("error: \(error)")}

🖕 Touch ID integration

Any Operation that require authentication must be run in the background thread.
If you run in the main thread, UI thread will lock for the system to try to display the authentication dialog.

🔐 Adding a Touch ID protected item

If you want to store the Touch ID protected Keychain item, specify accessibility and authenticationPolicy attributes.

letkeychain=Keychain(service:"com.example.github-token")DispatchQueue.global().async{do{
// Should be the secret invalidated when passcode is removed? If not then use `.WhenUnlocked`
try keychain
.accessibility(.whenPasscodeSetThisDeviceOnly, authenticationPolicy:.userPresence).set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{
// Error handling if needed...
}}

🔐 Updating a Touch ID protected item

The same way as when adding.

Do not run in the main thread if there is a possibility that the item you are trying to add already exists, and protected.Because updating protected items requires authentication.

Additionally, you want to show custom authentication prompt message when updating, specify an authenticationPrompt attribute. If the item not protected, the authenticationPrompt parameter just be ignored.

letkeychain=Keychain(service:"com.example.github-token")DispatchQueue.global().async{do{
// Should be the secret invalidated when passcode is removed? If not then use `.WhenUnlocked`
try keychain
.accessibility(.whenPasscodeSetThisDeviceOnly, authenticationPolicy:.userPresence).authenticationPrompt("Authenticate to update your access token").set("01234567-89ab-cdef-0123-456789abcdef", key:"kishikawakatsumi")}catchlet error{
// Error handling if needed...
}}

🔐 Obtaining a Touch ID protected item

The same way as when you get a normal item. It will be displayed automatically Touch ID or passcode authentication If the item you try to get is protected.
If you want to show custom authentication prompt message, specify an authenticationPrompt attribute. If the item not protected, the authenticationPrompt parameter just be ignored.

letkeychain=Keychain(service:"com.example.github-token")DispatchQueue.global().async{do{letpassword=try keychain
.authenticationPrompt("Authenticate to login to server").get("kishikawakatsumi")print("password: \(password)")}catchlet error{
// Error handling if needed...
}}

🔐 Removing a Touch ID protected item

The same way as when you remove a normal item. There is no way to show Touch ID or passcode authentication when removing Keychain items.

letkeychain=Keychain(service:"com.example.github-token")do{try keychain.remove("kishikawakatsumi")}catchlet error{
// Error handling if needed...
}

🔑 Shared Web Credentials

Shared web credentials is a programming interface that enables native iOS apps to share credentials with their website counterparts. For example, a user may log in to a website in Safari, entering a user name and password, and save those credentials using the iCloud Keychain. Later, the user may run a native app from the same developer, and instead of the app requiring the user to reenter a user name and password, shared web credentials gives it access to the credentials that were entered earlier in Safari. The user can also create new accounts, update passwords, or delete her account from within the app. These changes are then saved and used by Safari.
https://developer.apple.com/library/ios/documentation/Security/Reference/SharedWebCredentialsRef/

letkeychain=Keychain(server:"https://www.kishikawakatsumi.com", protocolType:.HTTPS)letusername="kishikawakatsumi@mac.com"
// First, check the credential in the app's Keychain
iflet password =try? keychain.get(username){
// If found password in the Keychain,
// then log into the server
}else{
// If not found password in the Keychain,
// try to read from Shared Web Credentials
keychain.getSharedPassword(username){(password, error)->()inif password !=nil{
// If found password in the Shared Web Credentials,
// then log into the server
// and save the password to the Keychain
keychain[username]= password
}else{
// If not found password either in the Keychain also Shared Web Credentials,
// prompt for username and password
// Log into server
// If the login is successful,
// save the credentials to both the Keychain and the Shared Web Credentials.
keychain[username]= inputPassword
keychain.setSharedPassword(inputPassword, account: username)}}}

Request all associated domain's credentials

Keychain.requestSharedWebCredential{(credentials, error)->()in}

Generate strong random password

Generate strong random password that is in the same format used by Safari autofill (xxx-xxx-xxx-xxx).

letpassword=Keychain.generatePassword() // => Nhu-GKm-s3n-pMx

How to set up Shared Web Credentials

Add a com.apple.developer.associated-domains entitlement to your app. This entitlement must include all the domains with which you want to share credentials.

Add an apple-app-site-association file to your website. This file must include application identifiers for all the apps with which the site wants to share credentials, and it must be properly signed.

When the app is installed, the system downloads and verifies the site association file for each of its associated domains. If the verification is successful, the app is associated with the domain.

More details:
https://developer.apple.com/library/ios/documentation/Security/Reference/SharedWebCredentialsRef/

🔑 Debugging

Display all stored items if print keychain object

letkeychain=Keychain(server:"https://github.com", protocolType:.https)print("\(keychain)")

=>
[
[authenticationType: default, key: kishikawakatsumi, server: github.com, class: internetPassword, protocol: https]
[authenticationType: default, key: hirohamada, server: github.com, class: internetPassword, protocol: https]
[authenticationType: default, key: honeylemon, server: github.com, class: internetPassword, protocol: https]
]

Obtaining all stored keys

letkeychain=Keychain(server:"https://github.com", protocolType:.https)letkeys= keychain.allKeys()forkeyin keys {print("key: \(key)")}

=>
key: kishikawakatsumi
key: hirohamada
key: honeylemon

Obtaining all stored items

letkeychain=Keychain(server:"https://github.com", protocolType:.https)letitems= keychain.allItems()foritemin items {print("item: \(item)")}

=>
item: [authenticationType: Default, key: kishikawakatsumi, server: github.com, class: InternetPassword, protocol: https]
item: [authenticationType: Default, key: hirohamada, server: github.com, class: InternetPassword, protocol: https]
item: [authenticationType: Default, key: honeylemon, server: github.com, class: InternetPassword, protocol: https]

Requirements

	OS	Swift
v1.1.x	iOS 7+, OSX 10.9+	1.1
v1.2.x	iOS 7+, OSX 10.9+	1.2
v2.0.x	iOS 7+, OSX 10.9+, watchOS 2+	2.0
v2.1.x	iOS 7+, OSX 10.9+, watchOS 2+	2.0
v2.2.x	iOS 8+, OSX 10.9+, watchOS 2+, tvOS 9+	2.0, 2.1
v2.3.x	iOS 8+, OSX 10.9+, watchOS 2+, tvOS 9+	2.0, 2.1, 2.2
v2.4.x	iOS 8+, OSX 10.9+, watchOS 2+, tvOS 9+	2.2, 2.3
v3.x	iOS 8+, OSX 10.9+, watchOS 2+, tvOS 9+	3.0

Installation

CocoaPods

KeychainAccess is available through CocoaPods. To install it, simply add the following lines to your Podfile:

use_frameworks!pod'KeychainAccess'

Carthage

KeychainAccess is available through Carthage. To install it, simply add the following line to your Cartfile:

github "kishikawakatsumi/KeychainAccess"

Swift Package Manager

KeychainAccess is also available through Swift Package Manager. First, create Package.swift that its package declaration includes:

import PackageDescription
letpackage=Package(
dependencies:[.Package(url:"https://github.com/kishikawakatsumi/KeychainAccess.git", majorVersion:2)])

Then, type

$ swift build

To manually add to your project

Add Lib/KeychainAccess.xcodeproj to your project
Link KeychainAccess.framework with your target
Add Copy Files Build Phase to include the framework to your application bundle

See iOS Example Project as reference.

Author

kishikawa katsumi, kishikawakatsumi@mac.com

License

KeychainAccess is available under the MIT license. See the LICENSE file for more info.

Name		Name	Last commit message	Last commit date
Examples		Examples
KeychainAccess.xcworkspace		KeychainAccess.xcworkspace
Lib		Lib
Screenshots		Screenshots
Sources		Sources
.gitignore		.gitignore
.travis.yml		.travis.yml
KeychainAccess.podspec		KeychainAccess.podspec
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

KeychainAccess

💡 Features

📖 Usage

👀 See also:

🔑 Basics

Saving Application Password

Saving Internet Password

🔑 Instantiation

Create Keychain for Application Password

Create Keychain for Internet Password

🔑 Adding an item

subscripting

for String

for NSData

set method

error handling

🔑 Obtaining an item

subscripting

for String (If the value is NSData, attempt to convert to String)

for NSData

get methods

as String

as NSData

🔑 Removing an item

subscripting

remove method

🔑 Set Label and Comment

🔑 Obtaining Other Attributes

PersistentRef

Creation Date

All Attributes

subscripting

🔑 Configuration (Accessibility, Sharing, iCloud Sync)

Accessibility

Default accessibility matches background application (=kSecAttrAccessibleAfterFirstUnlock)

For background application

Creating instance

One-shot

For foreground application

Creating instance

One-shot

👫 Sharing Keychain items

🔄 Synchronizing Keychain items with iCloud

Creating instance

One-shot

🖕 Touch ID integration

🔐 Adding a Touch ID protected item

🔐 Updating a Touch ID protected item

🔐 Obtaining a Touch ID protected item

🔐 Removing a Touch ID protected item

🔑 Shared Web Credentials

Request all associated domain's credentials

Generate strong random password

How to set up Shared Web Credentials

🔑 Debugging

Display all stored items if print keychain object

Obtaining all stored keys

Obtaining all stored items

Requirements

Installation

CocoaPods

Carthage

Swift Package Manager

To manually add to your project

Author

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages