Latest 0.1.0
Homepage https://github.com/okta/okta-storage-swift
License APACHE2
Platforms ios 9.0
Authors

OktaStorage

Okta Secure Storage Library

This library is a Swift wrapper around the iOS LocalAuthentication and Security frameworks. The library provides convenient APIs to utilize keychain services by giving your app a mechanism to store small bits of user data in an encrypted database. The keychain is not limited to passwords and tokens. You can store other secrets that the user explicitly cares about, such as credit card information or even short notes.

The storage library includes the following features:

  1. Get, set and delete keychain items
  2. Store to the keychain behind a biometric factor such as fingerprint or face ID

Table of Contents

Usage

Add import OktaSecureStorage to your source code

Create instance of OktaSecureStorage class

let oktaStorage = OktaSecureStorage()
or
let oktaStorage = OktaSecureStorage(applicationPassword: "user_password")

Save data to keychain

do {
    try oktaStorage.set(string: "password", forKey: "jdoe")
} catch let error {
    // Handle error
}

Save data to keychain behind a biometric factor

do {
    try oktaStorage.set(string: "password", forKey: "jdoe" behindBiometrics: true)
} catch let error {
    // Handle error
}

Load data from keychain

do {
    let password = try oktaStorage.get("jdoe")
} catch let error {
    // Handle error
}

Delete data from keychain

do {
    try oktaStorage.delete("jdoe")
} catch let error {
    // Handle error
}

API Reference

init(applicationPassword password: String? = nil)

Initializes OktaSecureStorage instance. The optional parameter applicationPassword allows items in the keychain to be secured using an additional password. This way, if the user does not have a passcode or Touch ID set up, the items will still be secure, and it adds an extra layer of security if they do have a passcode set

set(string: String, forKey key: String) -> Bool throws

Stores an item securely in the keychain. Method returns true on success and false on error.

do {
    try oktaStorage.set("password", forKey: "jdoe")
} catch let error {
    // Handle error
}

set(string: String, forKey key: String, behindBiometrics: Bool) throws

Stores an item securely and additionally accepts behindBiometrics parameter. Set this parameter to true if you want to store keychain item behind a biometric factor such as touch ID or face ID.

do {
    try oktaStorage.set("password", forKey: "jdoe" behindBiometrics: true)
} catch let error {
    // Handle error
}

set(string: String, forKey key: String, behindBiometrics: Bool, accessGroup: String) throws

Stores an item securely and additionally accepts accessGroup identifier. Use accessGroup to share keychain items between apps. Two or more apps that are in the same group can share keychain items because they share a common keychain access group entitlement. For more details, see Sharing Access to Keychain Items Among a Collection of Apps

do {
    try oktaStorage.set("password",
                        forKey: "jdoe",
                        accessGroup: "TEAMSEEDID.com.mycompany.sharedkeychain")
} catch let error {
    // Handle error
}

set(string: String, forKey key: String, behindBiometrics: Bool, accessibility: CFString) throws

Stores an item securely and additionally accepts accessibility parameter. Use accessibility parameter to indicate when a keychain item is accessible. Choose the most restrictive option that meets your app’s needs so that the system can protect that item to the greatest extent possible. Possible values are listed here. Please note that default value for accessibility parameter is kSecAttrAccessibleWhenUnlockedThisDeviceOnly – items with this attribute do not migrate to a new device.

do {
    try oktaStorage.set("password",
                        forKey: "jdoe",
                        accessibility: kSecAttrAccessibleWhenUnlockedThisDeviceOnly)
} catch let error {
    // Handle error
}

Additional helper functions

set(string: String,
    forKey key: String,
    accessGroup: String? = nil,
    accessibility: CFString?) throws

set(data: Data,
    forKey key: String) trows

set(data: Data,
    forKey key: String,
    behindBiometrics: Bool) trows

set(data: Data,
    forKey key: String,
    behindBiometrics: Bool,
    accessGroup: String) throws

set(data: Data,
    forKey key: String,
    behindBiometrics: Bool,
    accessibility: CFString) throws

set(data: Data,
    forKey key: String,
    accessGroup: String?,
    accessibility: CFString?) throws

get(key: String, biometricPrompt prompt: String? = nil) -> String throws

Retrieves the stored keychain item from the keychain. Additionally method expects optional prompt message for the keychain item stored behind a biometric factor.

  • Note: iOS will show native Touch ID or Face ID message view in case of biometrics enabled storage. It means that function may be blocked and wait for the user’s action. It is advised to call get function in a background thread
DispatchQueue.global().async {
    do {
        let password = try oktaStorage.get("jdoe", prompt: “Please use Touch ID or Face ID to sign in”)
    } catch let error {
        // Handle error
    }
}

getData(key: String, biometricPrompt prompt: String? = nil) -> Data throws

Retrieves the stored keychain item from the keychain. Additionally method expects optional prompt message for the keychain item stored behind a biometric factor.

  • Note: iOS will show native Touch ID or Face ID message view in case of biometrics enabled storage. It means that function may be blocked and wait for the user’s action. It is advised to call getData function in a background thread
DispatchQueue.global().async {
    do {
        let passwordData = try oktaStorage.getData("jdoe", prompt: “Please use Touch ID or Face ID to sign in”)
    } catch let error {
        // Handle error
    }
}

delete(key: String) throws

Removes the stored keychain item from the keychain

do {
    try oktaStorage.delete("jdoe")
} catch let error {
    // Handle error
}

clear() throws

Removes all keychain items from the keychain

do {
    try oktaStorage.clear()
} catch let error {
    // Handle error
}

isTouchIDSupported -> Bool

Checks whether device enrolled with Touch ID. If the biometry is not available, not enrolled or locked out, then the function call will return false.

let isTouchIDSupported = storageManager.isTouchIDSupported()

isFaceIDSupported -> Bool

Checks whether device enrolled with Face ID. If the biometry is not available, not enrolled or locked out, then the function call will return false.

let isFaceIDSupported = storageManager.isFaceIDSupported()

How to use this libary in Objective-C project

  1. Include auto generated swift header file into your .m file. Swift header file contains objective-c representation of Okta swift classes. Please note that the name of header file consists of your project name and “-Swift” suffix. For example if your project name is AuthApp, then auto generated header file name will be “AuthApp-Swift.h”
  2. Start using programming components available in swift header file

Example:

OktaSecureStorage *storage = [OktaSecureStorage new];
NSError *error;
BOOL success = [storage setWithString:"password" forKey:"jdoe" error:&error];
if (success) {
    NSString *password = [storage getWithKey:@"jdoe" error:&error];
    if (password != nil) {
        success = [storage deleteWithKey:@"jdoe" error:&error];
    }
}

Latest podspec

{
    "name": "OktaStorage",
    "version": "0.1.0",
    "summary": "This library provides convenient APIs to utilize keychain services",
    "description": "Store passwords, tokens and other secrets in an encrypted database using OktaStorage library",
    "homepage": "https://github.com/okta/okta-storage-swift",
    "license": {
        "type": "APACHE2",
        "file": "LICENSE"
    },
    "authors": {
        "Okta Developers": "[email protected]"
    },
    "source": {
        "git": "https://github.com/okta/okta-storage-swift.git",
        "tag": "0.1.0"
    },
    "platforms": {
        "ios": "9.0"
    },
    "source_files": "Sources/*"
}

Pin It on Pinterest

Share This