DOCSEARCHbyAlgolia
Submit Docs

SimpleKeychain Documentation

repository·master·Indexed 20 days ago

https://github.com/auth0/simplekeychain

A lightweight Swift wrapper for the iOS/macOS Keychain providing a simple API to securely store and retrieve strings and data items. It supports custom service names, access groups, iCloud synchronization, and biometric authentication via Touch ID or Face ID. Compatible with iOS 14.0+, macOS 11.0+, tvOS 14.0+, and watchOS 7.0+ using Swift 6.0+.

Tokens
2.7K
Snippets
14
Records
20
Agent score
73%

What's inside SimpleKeychain

  1. Understand SimpleKeychain v1 behavior changes

    master

    Authentication UI

    kSecUseAuthenticationUI is no longer used. To control whether a user is prompted for authentication, configure the LAContext.interactionNotAllowed property on your provided LAContext instance.

    Item Existence Checks

    The hasItem(forKey:) method has changed its error logic. It no longer returns false for every error; it now only returns false specifically when the error is errSecItemNotFound. For other errors, it will throw a SimpleKeychainError.

  2. Migrate from SimpleKeychain v0 to v1

    master

    SimpleKeychain v1 introduces breaking changes, including a shift from a class to a struct, improved error handling via SimpleKeychainError, and support for iCloud synchronization. Key changes include:

    • Language Support: Minimum Swift version is now 5.5. Objective-C is no longer supported.
    • Platform Targets:
      • iOS 12.0
      • macOS 10.15
      • tvOS 12.0
      • watchOS 6.2
    • Core Type Change: A0SimpleKeychain has been renamed to SimpleKeychain and changed from a class to a struct.

  3. Install SimpleKeychain

    master

    You can install SimpleKeychain using Swift Package Manager, CocoaPods, or Carthage.

    Swift Package Manager

    1. In Xcode, go to File > Add Packages...
    2. Enter the URL: https://github.com/auth0/SimpleKeychain
    3. Select your dependency rule and click Add Package.

    CocoaPods

    Add this line to your Podfile:

    pod 'SimpleKeychain', '~> 1.0'

    Then run pod install.

    Carthage

    Add this line to your Cartfile:

    gitub "auth0/SimpleKeychain" ~> 1.0

    Then run carthage bootstrap --use-xcframeworks.

  4. Store, retrieve, and delete items in SimpleKeychain

    master

    SimpleKeychain provides methods to manage strings, data, and keys within the iOS/macOS keychain.

    Storing items

    Use .set(_:forKey:) to store a string or data object.

    try simpleKeychain.set(accessToken, forKey: "auth0-access-token")

    Retrieving items

    • Check existence: try simpleKeychain.hasItem(forKey:) returns a boolean.
    • Retrieve String: try simpleKeychain.string(forKey:) returns the stored string.
    • Retrieve Data: try simpleKeychain.data(forKey:) returns the stored Data object.
    • List all keys: try simpleKeychain.keys() returns an array of all stored keys.

    Deleting items

    • Delete specific item: try simpleKeychain.deleteItem(forKey:).
    • Delete everything: try simpleKeychain.deleteAll().
    try simpleKeychain.set(accessToken, forKey: "auth0-access-token")
let isStored = try simpleKeychain.hasItem(forKey: "auth0-access-token")
let accessToken = try simpleKeychain.string(forKey: "auth0-access-token")
try simpleKeychain.deleteItem(forKey: "auth0-access-token")

  5. Migrate SimpleKeychain initialization and configuration

    master

    In v1, configuration properties that were previously set on the instance are now passed via the SimpleKeychain initializer.

    Accessibility

    Replace defaultAccessiblity with the accessibility parameter.

    Access Control

    Replace useAccessControl with the accessControlFlags parameter.

    Local Authentication Context

    SimpleKeychain no longer creates its own LAContext. You must provide an LAContext instance via the context parameter. This also replaces the need for setTouchIDAuthenticationAllowableReuseDuration(_:), as you should now configure the LAContext directly.

    // Before
let simpleKeychain = A0SimpleKeychain()
simpleKeychain.defaultAccessiblity = .whenPasscodeSetThisDeviceOnly
simpleKeychain.useAccessControl = true
simpleKeychain.setTouchIDAuthenticationAllowableReuseDuration(10)

// After
let context = LAContext()
context.touchIDAuthenticationAllowableReuseDuration = 10
let simpleKeychain = SimpleKeychain(
  accessibility: .whenPasscodeSetThisDeviceOnly,
  accessControlFlags: .userPresence,
  context: context
)

  7. Initialize SimpleKeychain

    master

    To use the library, instantiate SimpleKeychain. By default, it uses your app's bundle identifier as the service name. You can also specify a custom service name to group your keychain items.

    // Use default bundle identifier as service
let simpleKeychain = SimpleKeychain()

// Use a custom service name
let simpleKeychain = SimpleKeychain(service: "Auth0")
    let simpleKeychain = SimpleKeychain(service: "Auth0")

  8. Enable iCloud synchronization for keychain items

    master

    To allow keychain items to be shared across a user's devices via iCloud, set the sychronizable parameter to true when creating the SimpleKeychain instance.

    let simpleKeychain = SimpleKeychain(sychronizable: true)

  9. Require Touch ID or Face ID to retrieve an item

    master

    To enforce biometric authentication (Touch ID or Face ID) before accessing keychain items, provide accessControlFlags and an optional LAContext instance to the SimpleKeychain initializer. The LAContext allows you to configure settings like touchIDAuthenticationAllowableReuseDuration.

    let context = LAContext()
context.touchIDAuthenticationAllowableReuseDuration = 10
let simpleKeychain = SimpleKeychain(accessControlFlags: .biometryCurrentSet,
                                    context: context)

  10. Use a custom service name in SimpleKeychain

    master

    By default, SimpleKeychain uses your app's bundle identifier as the service name. To use a specific service name for saving items, pass the service parameter during initialization.

    let simpleKeychain = SimpleKeychain(service: "Auth0")

  11. Restrict item accessibility based on device state

    master

    You can control when keychain items are accessible (e.g., only when the device is unlocked) by specifying an accessibility value. The default value is .afterFirstUnlock.

    let simpleKeychain = SimpleKeychain(accessibility: .whenUnlocked)

  12. Include additional attributes in SimpleKeychain queries

    master

    You can specify additional attributes to be included in every keychain query by passing a dictionary to the attributes parameter during initialization. This is useful for setting specific keychain behaviors like kSecUseDataProtectionKeychain.

    let attributes = [kSecUseDataProtectionKeychain as String: true]
let simpleKeychain = SimpleKeychain(attributes: attributes)