Locksmith

A powerful, protocol-oriented library for working with the keychain in Swift.

• [x] 📱 iOS 8.0+
• [x] 💻 Mac OS X 10.10+
• [x] ⌚️ watchOS 2
• [x] 📺 tvOS

 

🚀 I make Rocket, an app that gives you Slack-style emoji everywhere on your Mac.

 

Details

How is Locksmith different to other keychain wrappers?

• Locksmith’s API is both super-simple and deeply powerful
• Provides access to all of the keychain’s metadata with strongly typed results
• Add functionality to your existing types for free
• Useful enums and Swift-native types

Want to read more about Locksmith’s design? I wrote a blog post on protocol oriented programming in Swift.

Installation

• Locksmith 4.0 and greater is Swift 4 compatible. See the swift-3.1 branch for compatibility with older versions of Swift.

CocoaPods

Locksmith is available through CocoaPods.

pod 'Locksmith'

Carthage

Locksmith is available through Carthage.

github "matthewpalmer/Locksmith"

Quick start

Setup

1. Choose your target project
2. Select Capabilties
3. Enable Keychain Sharing

Xcode then automatically creates a .entitlements file and you are ready to use Locksmith!

Save data

try Locksmith.saveData(["some key": "some value"], forUserAccount: "myUserAccount")

Load data

let dictionary = Locksmith.loadDataForUserAccount("myUserAccount")

Update data

• as well as replacing existing data, this writes data to the keychain if it does not exist already

try Locksmith.updateData(["some key": "another value"], forUserAccount: "myUserAccount")

Delete data

try Locksmith.deleteDataForUserAccount("myUserAccount")

Power to the protocols

Locksmith has been designed with Swift 2, protocols, and protocol extensions in mind.

Why do this? Because you can add existing functionality to your types with only the slightest changes!

Say we have a Twitter account

struct TwitterAccount {
  let username: String
  let password: String
}

and we want to save it to the keychain as a generic password. All we need to do is conform to the right protocols in Locksmith and we get that functionality for free.

struct TwitterAccount: CreateableSecureStorable, GenericPasswordSecureStorable {
  let username: String
  let password: String

  // Required by GenericPasswordSecureStorable
  let service = "Twitter"
  var account: String { return username }

  // Required by CreateableSecureStorable
  var data: [String: AnyObject] {
    return ["password": password]
  }
}

Now we get the ability to save our account in the keychain.

let account = TwitterAccount(username: "_matthewpalmer", password: "my_password")
try account.createInSecureStore()

Creating, reading, and deleting each have their own protocols: CreateableSecureStorable, ReadableSecureStorable, and DeleteableSecureStorable. And the best part?

You can conform to all three protocols on the same type!

struct TwitterAccount: ReadableSecureStorable,
                       CreateableSecureStorable,
                       DeleteableSecureStorable,
                       GenericPasswordSecureStorable {
  let username: String
  let password: String

  let service = "Twitter"
  var account: String { return username }
  var data: [String: AnyObject] {
    return ["password": password]
  }
}

let account = TwitterAccount(username: "_matthewpalmer", password: "my_password")

// CreateableSecureStorable lets us create the account in the keychain
try account.createInSecureStore()

// ReadableSecureStorable lets us read the account from the keychain
let result = account.readFromSecureStore()

// DeleteableSecureStorable lets us delete the account from the keychain
try account.deleteFromSecureStore()

So. cool.

The details

By declaring that your type adopts these protocols—which is what we did above with struct TwitterAccount: CreateableSecureStorable, ...—you get a bunch of functionality for free.

I like to think about protocols with extensions in terms of “what you get,” “what you’ve gotta do,” and “what’s optional.” Most of the stuff under ‘optional’ should only be implemented if you want to change existing functionality.

CreateableSecureStorable

What you get

// Saves a type to the keychain
func createInSecureStore() throws

Required

// The data to save to the keychain
var data: [String: AnyObject] { get }

Optional

// Perform the request in this closure
var performCreateRequestClosure: PerformRequestClosureType { get }

ReadableSecureStorable

What you get

// Read from the keychain
func readFromSecureStore() -> SecureStorableResultType?

Required

Nothing!

Optional

// Perform the request in this closure
var performReadRequestClosure: PerformRequestClosureType { get }

DeleteableSecureStorable

What you get

// Read from the keychain
func deleteFromSecureStore() throws

Required

Nothing!

Optional

// Perform the request in this closure
var performDeleteRequestClosure: PerformRequestClosureType { get }

Powerful support for the Cocoa Keychain

Many wrappers around the keychain have only support certain parts of the API. This is because there are so many options and variations on the way you can query the keychain that it’s almost impossible to abstract effectively.

Locksmith tries to include as much of the keychain as possible, using protocols and protocol extensions to minimize the complexity. You can mix-and-match your generic passwords with your read requests while staying completely type-safe.

Please refer to the Keychain Services Reference for full information on what each of the attributes mean and what they can do.

Certificates, keys, and identities are possible—it’s just a matter of translating the kSec... constants!

GenericPasswordSecureStorable

Generic passwords are probably the most common use-case of the keychain, and are great for storing usernames and passwords.

Properties listed under ‘Required’ have to be implemented by any types that conform; those listed under ‘Optional’ can be implemented to add additional information to what is saved or read if desired.

One thing to note: if you implement an optional property, its type annotation must match the type specified in the protocol exactly. If you implement description: String? it can’t be declared as var description: String.

Required

var account: String { get }
var service: String { get }

Optional

var comment: String? { get }
var creator: UInt? { get }
var description: String? { get }
var generic: NSData? { get }
var isInvisible: Bool? { get }
var isNegative: Bool? { get }
var label: String? { get }
var type: UInt? { get }

InternetPasswordSecureStorable

Types that conform to InternetPasswordSecureStorable typically come from web services and have certain associated metadata.

Required

var account: String { get }
var authenticationType: LocksmithInternetAuthenticationType { get }
var internetProtocol: LocksmithInternetProtocol { get }
var port: String { get }
var server: String { get }

Optional

var comment: String? { get }
var creator: UInt? { get }
var description: String? { get }
var isInvisible: Bool? { get }
var isNegative: Bool? { get }
var path: String? { get }
var securityDomain: String? { get }
var type: UInt? { get }

Result types

By adopting a protocol-oriented design from the ground up, Locksmith can provide access to the result of your keychain queries with type annotations included—store an NSDate, get an NSDate back with no type-casting!

Let’s start with an example: the Twitter account from before, except it’s now an InternetPasswordSecureStorable, which lets us store a bit more metadata.

struct TwitterAccount: InternetPasswordSecureStorable,
                       ReadableSecureStorable,
                       CreateableSecureStorable {
  let username: String
  let password: String

  var account: String { return username }
  var data: [String: AnyObject] {
    return ["password": password]
  }

  let server = "com.twitter"
  let port = 80
  let internetProtocol = .HTTPS
  let authenticationType = .HTTPBasic
  let path: String? = "/api/2.0/"
}

let account = TwitterAccount(username: "_matthewpalmer", password: "my_password")

// Save all this to the keychain
account.createInSecureStore()

// Now let’s get it back
let result: InternetPasswordSecureStorableResultType = account.readFromSecureStore()

result?.port // Gives us an Int directly!
result?.internetProtocol // Gives us a LocksmithInternetProtocol enum case directly!
result?.data // Gives us a [String: AnyObject] of what was saved
// and so on...

This is awesome. No more typecasting.

GenericPasswordSecureStorableResultType

Everything listed here can be set on a type conforming to GenericPasswordSecureStorable, and gotten back from the result returned from readFromSecureStore() on that type.

var account: String { get }
var service: String { get }
var comment: String?