iOS/Pods/SwiftKeychainWrapper/README.md

   1 #SwiftKeychainWrapper
   2
   3 A simple wrapper for the iOS Keychain to allow you to use it in a similar fashion to User Defaults. Written in Swift.
   4
   5 Provides singleton instance that is setup to work for most needs. Use KeychainWrapper.standard to access the singleton instance.
   6
   7 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 access.
   8
   9 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 keycain.
  10
  11 Users that want to deviate from this default implementation, now can do so in 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.
  12
  13 ##General Usage
  14
  15 Add a string value to keychain:
  16 ```
  17 let saveSuccessful: Bool = KeychainWrapper.standard.set("Some String", forKey: "myKey")
  18 ```
  19
  20 Retrieve a string value from keychain:
  21 ```
  22 let retrievedString: String? = KeychainWrapper.standard.string(forKey: "myKey")
  23 ```
  24
  25 Remove a string value from keychain:
  26 ```
  27 let removeSuccessful: Bool = KeychainWrapper.standard.remove(key: "myKey")
  28 ```
  29
  30 ##Custom Instance
  31
  32 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 keycahin under different identifiers.
  33
  34 To share keychain items between your applications, you may specify an access group and use that same access group in each application.
  35
  36 To set a custom service name identifier or access group, you may now create your own instance of the keychain wrapper as follows:
  37
  38 ```
  39 let uniqueServiceName = "customServiceName"
  40 let uniqueAccessGroup = "sharedAccessGroupName"
  41 let customKeychainWrapperInstance = KeychainWrapper(serviceName: uniqueServiceName, accessGroup: uniqueAccessGroup)
  42 ```
  43 The custom instance can then be used in place of the shared instance or static accessors:
  44
  45 ```
  46 let saveSuccessful: Bool = customKeychainWrapperInstance.set("Some String", forKey: "myKey")
  47
  48 let retrievedString: String? = customKeychainWrapperInstance.string(forKey: "myKey")
  49
  50 let removeSuccessful: Bool = customKeychainWrapperInstance.removeObject(forKey: "myKey")
  51 ```
  52
  53 ##Accessibility Options
  54
  55 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:
  56
  57 ```
  58 KeychainWrapper.standard.set("Some String", forKey: "myKey", withAccessibility: .AfterFirstUnlock)
  59 ```
  60
  61 ##Installation
  62
  63 #### CocoaPods
  64 You can use [CocoaPods](http://cocoapods.org/) to install SwiftKeychainWrapper by adding it to your `Podfile`:
  65
  66 ``` ruby
  67 use_frameworks!
  68 platform :ios, '8.0'
  69
  70 target 'target_name' do
  71    pod 'SwiftKeychainWrapper'
  72 end
  73 ```
  74
  75 To use the keychain wrapper in your app, import SwiftKeychainWrapper into the file(s) where you want to use it.
  76
  77 ```
  78 import SwiftKeychainWrapper
  79 ```
  80
  81 #### Carthage
  82 You can use [Carthage](https://github.com/Carthage/Carthage) to install SwiftKeychainWrapper by adding it to your `Cartfile`.
  83
  84 Swift 3.0:
  85 ```
  86 github "jrendel/SwiftKeychainWrapper" ~> 3.0
  87 ```
  88
  89 Swift 2.3:
  90 ```
  91 github "jrendel/SwiftKeychainWrapper" == 2.1.1
  92 ```
  93
  94 #### Manually
  95 Download and drop ```KeychainWrapper.swift``` and ```KeychainItemAcessibility.swift``` into your project.
  96
  97
  98 ## Release History
  99
 100 * 3.0.1
 101     * Added a host app for the unit tests to get around the issue with keychain access not working the same on iOS 10 simulators
 102     * Minor update to readme instructions
 103 * 3.0
 104     * Swift 3.0 update. Contains breaking API changes. 2.2.0 and 2.2.1 are now rolled into 3.0
 105 * 2.2.1 (Removed from Cocoapods)
 106     * Syntax updates to be more Swift 3 like
 107 * 2.2 (Removed from Cocoapods)
 108     * Updated to support Swift 3.0
 109     * Remove deprecated functions (static access)
 110 * 2.1
 111     * Updated to support Swift 2.3
 112 * 2.0
 113     * Further changes to more closely align the API with how NSUserDefaults works. Access to the default implementation is now done through a singleton instance. Static accessors have been included that wrap this shared instance to maintain backwards compatibility. These will be removed in the next update
 114     * Ability to change keychain service name identifier and access group on the shared instance has been deprecated. Users now have the ability to create their own instance of the keychain if they want to customize these.
 115     * Addtional options have been provided to alter the keychain accessibility for each key value saved.
 116
 117 * 1.0.11
 118     * Update for Swift 2.0
 119
 120 * 1.0.10
 121     * Update License info. Merged Pull Request with Carthage support.
 122
 123 * 1.0.8
 124     * Update for Swift 1.2
 125
 126 * 1.0.7
 127     * Determined that once provisioned correctly for access groups, using KeychainWrapper on the simulator with access groups works. So I removed the simulator related check and unit tests previously added.
 128
 129 * 1.0.6
 130     * Support for Access Groups
 131     * SwiftKeychainWrapperExample has been updated to show usage with an Access Group: https://github.com/jrendel/SwiftKeychainWrapperExample
 132
 133     * Access Groups do not work on the simulator. Apps that are built for the simulator aren't signed, so there's no keychain access group for the simulator to check. This means that all apps can see all keychain items when run on the simulator. Attempting to set an access group will result in a failure when attempting to Add or Update keychain items. Because of this, the Keychain Wrapper detects if it is being using on a simulator and will not set an access group property if one is set. This allows the Keychain Wrapper to still be used on the simulator for development of your app. To properly test Keychain Access Groups, you will need to test on a device.
 134
 135 * 1.0.5
 136     * This version converts the project to a proper Swift Framework and adds a podspec file to be compatible with the latest CocoaPods pre-release, which now supports Swift.
 137
 138     * To see an example of usage with CocoaPods, I've created the repo SwiftKeychainWrapperExample:  https://github.com/jrendel/SwiftKeychainWrapperExample
 139
 140 * 1.0.2
 141     * Updated for Xcode 6.1
 142
 143 ======
 144
 145 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:
 146
 147 http://www.raywenderlich.com/6475/basic-security-in-ios-5-tutorial-part-1
 148
 149 This is a rewrite of that code in Swift.
 150
 151 [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)