A Lightweight Swift Library for Keychain Access – SimpleKiiManager

Johannes Kinzig
My Libs Open Source Projects Software Engineering
A smartphone, tablet and desktop computer – the computer is showing a lock on its screen.

When you’re dealing with sensitive data in your iOS or macOS app, the Keychain is the place to store things like tokens, passwords, and other secrets securely. But the native API can be a bit tricky to work with and takes some time to get used to.

That’s why I built SimpleKiiManager – a lightweight Swift library that wraps Apple’s verbose Keychain API with a clean and easy-to-use interface.

🔗 Documentation
📦 Git Repository (Bitbucket)

Why SimpleKiiManager?

SimpleKiiManager abstracts away the boilerplate and lets you:

  • Store, retrieve, update, and delete secrets
  • Use enums instead of Core Foundation keys
  • Write clean Swift code with proper error handling
  • Specify Keychain item types and access control easily

I made this library because I wanted a simple way to add secrets or user logins to my Swift apps. It’s a common problem, and I thought it would be helpful to have a solution that’s easy to use.

Core Features

  • Add, get, update, and delete secrets using simple Swift methods
  • Enum-based typing for secret kinds (e.g. .genericPassword)
  • Optional parameters like labelName, serviceName, or comment
  • Supports setting the item’s access policy
  • Swift-native error handling (throws)
  • Minimal setup and clean method signatures

Documentation

  • Release Notes: What’s New and What Got Fixed?
  • Installation: How to add this framework to your Xcode project?
  • Usage: How to use this library, its methods and property wrappers?
  • Tests: What is covered by the tests?
  • To-Dos: To-Dos and Known Issues

Basic Usage

This library consists of two classes simplifying keychain interactions.

SimpleKiiManager Usage Example – add entry to keychain

import SimpleKiiManager


// parameter *secretKind* and *accessPolicyMode* not explicitely stated as the default values are used
try SimpleKiiManagerSt.shared.addSecret(accountName: "user@example.com", labelName: "ExampleLogin", serviceName: "ExampleMailService", secretValue: "mySuperSecretPassword", comment: "E-Mail login for example user")

// parameter *secretKind* and *accessPolicyMode* explicitely stated
try SimpleKiiManagerSt.shared.addSecret(accountName: default1SecretAccountName, labelName: defaultSecretLabelName, serviceName: defaultSecretServiceName, secretValue: default1SecretValue, comment: default1comment, secretKind: .genericPassword, accessPolicyMode: .afterFirstUnlock)

Complete tutorial: SimpleKiiManager Documentation

ComfortKiiManager Usage Example

import SimpleKiiManager

// 1. Init and provide account name for item
@ComfortKiiManager(accountName: "mySimpleSecret")
var mySecret: String?

// 2. add (or updated) secret value for item
mySecret = "thisIsMySuperSecretSecret"

// 3. updated secret value for item 
mySecret = "updatedSuperSecretSecret"

// 4. read secret value
print(mySecret)

// 5. remove item from keychain
mySecret = nil

Complete tutorial: ComfortKiiManager Documentation

Also, look at the Tests for further information.

AccessPolicy Enum and accessPolicyMode parameter

The AccessPolicy enum defines the access policy for your keychain entries. It restricts access to keychain items based on the current security state of the device (e.g. item accessible when unlocked, when password is set, etc.). The desired access policy can be specified when adding an entry to keychaining using addSecret or addOrUpdateSecretValue

The access policies are defined by Apple as an kSecAttribute. For details, refer to Apple’s Developer Documentation for keychain management.

SimpleKiiManager supports the following access policies:

.whenUnlocked

Item can be accessed while device is unlocked, therefore mainly suited for applications accessing the keychain when running in foreground. Items marked with this attribute will be backed up when encrypted backups are enabled. Reflects kSecAttrAccessibleWhenUnlocked.

.afterFirstUnlock

Item can be accessed when device was initially unlocked after a restart, therefore suitable for applications requiring keychain access when running in background. Items marked with this attribute will be backed up when encrypted backups are enabled. Reflects kSecAttrAccessibleAfterFirstUnlock.

.whenPasswordSetAndUnlockedLocalDeviceOnly

Item can be accessed while device is unlocked, therefore mainly suited for applications accessing the keychain when running in foreground. Device is required to have a passcode set up. Items marked with this attribute will never get backed up or migrated to another device. When a backup is restored, this item will be missing. Disabling the passcode protection on device deletes all items marked with this attribute. Reflects kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly.

.whenUnlockedLocalDeviceOnly

Item can be accessed while device is unlocked, therefore mainly suited for applications accessing the keychain when running in foreground. Items marked with this attribute will never get backed up or migrated to another device. When a backup is restored, this item will be missing. Reflects kSecAttrAccessibleWhenUnlockedThisDeviceOnly.

.afterFirstUnlockLocalDeviceOnly

Item can be accessed when device was initially unlocked after a restart, therefore suitable for applications requiring keychain access when running in background. Items marked with this attribute will never get backed up or migrated to another device. When a backup is restored, this item will be missing. Reflects kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly.

Contribution

Contribution is always welcome, please contact me.

Other keychain libraries

My library is not the only wrapper for the native keychain API, several more exist: