search

jrendel / SwiftKeychainWrapper

A simple wrapper for the iOS Keychain to allow you to use it in a similar fashion to User Defaults. Written in Swift.
MIT License
1.59k stars 340 forks source link

readme

:no_entry: [DEPRECATED] This library is not being kept up to date. This was created when Swift was first released as a simple way to work with the Keychain. But the approach was restricted and not suited to more advanced keychain usage.

SwiftKeychainWrapper

A simple wrapper for the iOS / tvOS Keychain to allow you to use it in a similar fashion to User Defaults. Written in Swift.

Provides singleton instance that is setup to work for most needs. Use KeychainWrapper.standard to access the singleton instance.

If you need to customize the keychain access to use a custom identifier or access group, you can create your own instance instead of using the singleton instance.

By default, the Keychain Wrapper saves data as a Generic Password type in the iOS Keychain. It saves items such that they can only be accessed when the app is unlocked and open. If you are not familiar with the iOS Keychain usage, this provides a safe default for using the keychain.

Users that want to deviate from this default implementation, now can do so in version 2.0 and up. Each request to save/read a key value now allows you to specify the keychain accessibility for that key.

General Usage

Add a string value to keychain:

let saveSuccessful: Bool = KeychainWrapper.standard.set("Some String", forKey: "myKey")

Retrieve a string value from keychain:

let retrievedString: String? = KeychainWrapper.standard.string(forKey: "myKey")

Remove a string value from keychain:

let removeSuccessful: Bool = KeychainWrapper.standard.removeObject(forKey: "myKey")

Custom Instance

When the Keychain Wrapper is used, all keys are linked to a common identifier for your app, called the service name. By default this uses your main bundle identifier. However, you may also change it, or store multiple items to the keychain under different identifiers.

To share keychain items between your applications, you may specify an access group and use that same access group in each application.

To set a custom service name identifier or access group, you may now create your own instance of the keychain wrapper as follows:

let uniqueServiceName = "customServiceName"
let uniqueAccessGroup = "sharedAccessGroupName"
let customKeychainWrapperInstance = KeychainWrapper(serviceName: uniqueServiceName, accessGroup: uniqueAccessGroup)

The custom instance can then be used in place of the shared instance or static accessors:

let saveSuccessful: Bool = customKeychainWrapperInstance.set("Some String", forKey: "myKey")

let retrievedString: String? = customKeychainWrapperInstance.string(forKey: "myKey")

let removeSuccessful: Bool = customKeychainWrapperInstance.removeObject(forKey: "myKey")

Subscript usage

Keychain can also be accessed with subscript as it is in dictionary. Keys can be predefined and listed in one place for convenience.

Firstly, let's define the key to use later.

extension KeychainWrapper.Key {
    static let myKey: KeychainWrapper.Key = "myKey"
}

And now we can use this key as follows:

KeychainWrapper.standard[.myKey] = "some string"

let myValue: String? = KeychainWrapper.standard[.myKey]

KeychainWrapper.standard.remove(forKey: .myKey)

Accessibility Options

By default, all items saved to keychain can only be accessed when the device is unlocked. To change this accessibility, an optional withAccessibility param can be set on all requests. The enum KeychainItemAccessibilty provides an easy way to select the accessibility level desired:

KeychainWrapper.standard.set("Some String", forKey: "myKey", withAccessibility: .AfterFirstUnlock)

Synchronizable Option

By default, all items saved to keychain are not synchronizable, so they are not synced with the iCloud. To change this, an isSynchronizable bool param can be set on all requests. You need the item to be synchronized with the iCloud if you want to have it on all of your devices:

KeychainWrapper.standard.set("Some String", forKey: "myKey", isSynchronizable: true)

Important: You can't modify value for key if it was previously set with different accessibility option. Remove the value for key and set it with new accessibility option. (Otherwise the value will not change).
For example:

KeychainWrapper.standard.set("String one", forKey: "myKey", withAccessibility: .AfterFirstUnlock)
KeychainWrapper.standard.removeObject(forKey: "myKey")
KeychainWrapper.standard.set("String two", forKey: "myKey", withAccessibility: .Always)

Installation

CocoaPods

You can use CocoaPods to install SwiftKeychainWrapper by adding it to your Podfile:

use_frameworks!
platform :ios, '8.0'

target 'target_name' do
   pod 'SwiftKeychainWrapper'
end

To use the keychain wrapper in your app, import SwiftKeychainWrapper into the file(s) where you want to use it.

import SwiftKeychainWrapper

Carthage

You can use Carthage to install SwiftKeychainWrapper by adding it to your Cartfile.

Swift 3.0:

github "jrendel/SwiftKeychainWrapper" ~> 3.0

Swift 2.3:

github "jrendel/SwiftKeychainWrapper" == 2.1.1

Swift Package Manager

You can use Swift Package Manager to install SwiftKeychainWrapper using Xcode:

  1. Open your project in Xcode

  2. Click "File" -> "Swift Packages" -> "Add Package Dependency..."

  3. Paste the following URL: https://github.com/jrendel/SwiftKeychainWrapper

  4. Click "Next" -> "Next" -> "Finish"

Manually

Download and drop KeychainWrapper.swift and KeychainItemAcessibility.swift into your project.

Release History

I've been using an Objective-C based wrapper in my own projects for the past couple years. The original library I wrote for myself was based on the following tutorial:

http://www.raywenderlich.com/6475/basic-security-in-ios-5-tutorial-part-1

This is a rewrite of that code in Swift.

Carthage compatible