Repository files navigation

This is a collection of helper functions for saving text and data in the Keychain.As you probably noticed Apple's keychain API is a bit verbose. This library was designed to provide shorter syntax for accomplishing a simple task: reading/writing text values for specified keys:

letkeychain=KeychainSwift()keychain.set("hello world", forKey:"my key")keychain.get("my key")

The Keychain library includes the following features:

• Get, set and delete string, boolean and Data Keychain items
• Specify item access security level
• Synchronize items through iCloud
• Share Keychain items with other apps

Keychain is a secure storage. You can store all kind of sensitive data in it: user passwords, credit card numbers, secret tokens etc. Once stored in Keychain this information is only available to your app, other apps can't see it. Besides that, operating system makes sure this information is kept and processed securely. For example, text stored in Keychain can not be extracted from iPhone backup or from its file system. Apple recommends storing only small amount of data in the Keychain. If you need to secure something big you can encrypt it manually, save to a file and store the key in the Keychain.

There are four ways you can add KeychainSwift to your project.

Simply addKeychainSwiftDistrib.swift file into your Xcode project.

Alternatively, addgithub "evgenyneu/keychain-swift" ~> 24.0 to your Cartfile and runcarthage update.

If you are using CocoaPods add this text to your Podfile and runpod install.

use_frameworks!target 'Your target name'pod 'KeychainSwift', '~> 24.0'

• In Xcode selectFile > Add Packages.
• Enter this project's URL:https://github.com/evgenyneu/keychain-swift.git

If you're using KeychainSwift in a Swift package, make sure to specify aname. This is because SPM cannot automatically resolve a name for a package that has a different Target name in itsPackage.swift (namelyKeychainSwift) that differs from the repo link (keychain-swift).

.package(name: "KeychainSwift", url: "https://github.com/evgenyneu/keychain-swift.git", from: "24.0.0")

Setup aprevious version of the library if you use an older version of Swift.

Addimport KeychainSwift to your source code unless you used the file setup method.

letkeychain=KeychainSwift()keychain.set("hello world", forKey:"my key")keychain.get("my key")

letkeychain=KeychainSwift()keychain.set(true, forKey:"my key")keychain.getBool("my key")

letkeychain=KeychainSwift()keychain.set(dataObject, forKey:"my key")keychain.getData("my key")

keychain.delete("my key") // Remove single keykeychain.clear() // Delete everything from app's Keychain. Does not work on macOS.

letkeychain=KeychainSwift()keychain.allKeys // Returns the names of all keys

UsewithAccess parameter to specify the security level of the keychain storage.By default the.accessibleWhenUnlocked option is used. It is one of the most restrictive options and provides good data protection.

let keychain = KeychainSwift()keychain.set("Hello world", forKey: "key 1", withAccess: .accessibleWhenUnlocked)

You can use.accessibleAfterFirstUnlock if you need your app to access the keychain item while in the background. Note that it is less secure than the.accessibleWhenUnlocked option.

See the list of all availableaccess options.

Setsynchronizable property totrue to enable keychain items synchronization across user's multiple devices. The synchronization will work for users who have the "Keychain" enabled in the iCloud settings on their devices.

Settingsynchronizable property totrue will add the item to other devices with theset method and obtain synchronizable items with theget command. Deleting a synchronizable item will remove it from all devices.

Note that you do NOT need to enable iCloud or Keychain Sharing capabilities in your app's target for this feature to work.

// First deviceletkeychain=KeychainSwift()keychain.synchronizable=truekeychain.set("hello world", forKey:"my key")// Second deviceletkeychain=KeychainSwift()keychain.synchronizable=truekeychain.get("my key") // Returns "hello world"

We could not get the Keychain synchronization work on macOS.

In order to share keychain items between apps on the same device they need to have commonKeychain Groups registered inCapabilities > Keychain Sharing settings.This tutorial shows how to set it up.

UseaccessGroup property to access shared keychain items. In the following example we specify an access group "CS671JRA62.com.myapp.KeychainGroup" that will be used to set, get and delete an item "my key".

letkeychain=KeychainSwift()keychain.accessGroup="CS671JRA62.com.myapp.KeychainGroup" // Use your own access goupkeychain.set("hello world", forKey:"my key")keychain.get("my key")keychain.delete("my key")keychain.clear()

Note: there is no way of sharing a keychain item between the watchOS 2.0 and its paired device:https://forums.developer.apple.com/thread/5938

One can pass akeyPrefix argument when initializing aKeychainSwift object. The string passed inkeyPrefix argument will be used as a prefix toall the keys used inset,get,getData anddelete methods. Adding a prefix to the keychain keys can be useful in unit tests. This prevents the tests from changing the Keychain keys that are used when the app is launched manually.

Note thatclear method still clears everything from the Keychain regardless of the prefix used.

letkeychain=KeychainSwift(keyPrefix:"myTestKey_")keychain.set("hello world", forKey:"hello")// Value will be stored under "myTestKey_hello" key

One can verify ifset,delete andclear methods finished successfully by checking their return values. Those methods returntrue on success andfalse on error.

if keychain.set("hello world", forKey:"my key"){  // Keychain item is saved successfully}else{  // Report error}

To get a specific failure reason use thelastResultCode property containing result code for the last operation. SeeKeychain Result Codes.

keychain.set("hello world", forKey:"my key")if keychain.lastResultCode!= noErr{ /* Report error */}

Use theasReference: true parameter to return the data as reference, which is needed forNEVPNProtocol.

letkeychain=KeychainSwift()keychain.set(dataObject, forKey:"my key")keychain.getData("my key", asReference:true)

This manual describes how to use KeychainSwift in Objective-C apps.

Ithas been reported that the library sometimes returnsnil instead of the stored Keychain value. It may be connected withthe Keychain issue reported on Apple developer forums. The issue is random and hard to reproduce. If you experienced this problem feel free to create an issue and share your story, so we can find solutions.

Thanks to Alex Nagy fromrebeloper.com for creating this two-partvideo tutorial.

Here are some other Keychain libraries.

• DanielTomlinson/Latch
• jrendel/SwiftKeychainWrapper
• kishikawakatsumi/KeychainAccess
• matthewpalmer/Locksmith
• s-aska/KeyClip
• yankodimitrov/SwiftKeychain

• The code is based on this example:https://gist.github.com/s-aska/e7ad24175fb7b04f78e7
• Thanks todiogoguimaraes for adding Swift Package Manager setup option.
• Thanks toglyuck for taming booleans.
• Thanks topepibumur for adding macOS, watchOS and tvOS support.
• Thanks toezura for iOS 7 support.
• Thanks tomikaoj for adding keychain synchronization.
• Thanks totcirwin for adding Swift 3.0 support.
• Thanks toTulleb for adding Xcode 8 beta 6 support.
• Thanks toCraigSiemens for adding Swift 3.1 support.
• Thanks tomaxkramerbcgdv for fixing Package Manager setup in Xcode 8.2.
• Thanks toelikohen for fixing concurrency issues.
• Thanks tobeny for adding Swift 4.2 support.
• Thanks toxuaninbox for fixing watchOS deployment target for Xcode 10.
• Thanks toschayes04 for adding Swift 5.0 support.
• Thanks tomediym41 for adding ability to return data as reference.
• Thanks toAnthonyOliveri for adding ability to run unit tests from Swift Package Manager.
• Thanks tophilippec for removing deprecated access options.
• Thanks tolucasmpaim for adding ability to return the names of all keys.

If you notice any issue, got stuck or just want to chat feel free to create an issue. We will be happy to help you.

Keychain Swift is released under theMIT License.