Session Storage

This guide covers securely storing and restoring Privacy Boost sessions using iOS Keychain, expanding on the persistence options in Key Management.

Why Keychain?

Session data includes sensitive cryptographic keys. Keychain provides:

Hardware-backed encryption
Access control (biometrics, passcode)
Secure enclave support
Data protection across app updates

There are two ways to use it. The SDK can own the vault in the Keychain itself through a KeychainDelegate, which is the path described next, or the app can export the session and store it with its own Keychain code, which the rest of this guide covers.

SDK-Managed Persistence

Select persistenceStorage: .osKeychain and an unlock method, and register a KeychainDelegate before constructing the SDK. PrivacyBoost.withPlatformDefaults(config:) from the PrivacyBoostDefaults product registers DefaultKeychainDelegate() for you unless the app already registered its own, then constructs the SDK:

import PrivacyBoost
import PrivacyBoostDefaults

let config = PrivacyBoostConfig(
    serverUrl: "https://indexer.example.com",
    chainId: nil,
    shieldContractAddress: nil,
    wethContractAddress: nil,
    teePublicKey: nil,
    appId: "my-app",
    persistenceStorage: .osKeychain,
    persistenceUnlock: .pin
)

let sdk = try PrivacyBoost.withPlatformDefaults(config: config)

DefaultKeychainDelegate stores items as generic passwords under one service name (com.privacyboost.sdk unless you pass another to its initializer) with kSecAttrAccessibleWhenUnlockedThisDeviceOnly. To use your own Keychain code instead, conform to KeychainDelegate and register it yourself:

registerKeychainDelegate(delegate: MyKeychainDelegate())
let sdk = try PrivacyBoost(config: config)

registerKeychainDelegate takes an optional service: that namespaces the vault items. Omit it and the SDK uses its own name, which is what a single-SDK app wants; pass your own (a bundle id, say) when two SDK instances or an app extension share the process or a Keychain group, so their items cannot collide. The registration is process-wide: do it once, before the first PrivacyBoost whose config selects .osKeychain, and note that a later call replaces the delegate for every instance. Construction throws SDKError.configError naming register_keychain_delegate when no delegate is registered; hasKeychainDelegate() tells you whether one is. .localStorage and .indexedDb are browser backends and are rejected on iOS, as is .passkey unlock.

Unlock methods

`persistenceUnlock`	On the next launch
`.pin`, `.password`	`authenticate` returns `.credentialRequired`; collect the credential and call `submitCredential`.
`.biometric`	The vault item is written with an access control of `.biometryCurrentSet`, so reading it shows the Face ID or Touch ID prompt. There is no credential challenge: `authenticate` asks the wallet for one signature to derive the vault key and returns `.authenticated`.
`.none`	As `.biometric` without the prompt: one wallet signature, then `.authenticated`.

Unlocking on the next launch

With .pin or .password, the first launch returns .credentialRequired with challenge.action == .setup, where the user chooses the credential, and every later launch returns it with challenge.action == .unlock. submitCredential completes the login either way and can be retried after a wrong credential without calling authenticate again:

func signIn() async throws -> LoginResult {
    let result = try await sdk.authenticate(
        wallet: walletDelegate,
        keySource: .walletDerived,   // ignored once a vault exists
        tokenProvider: nil
    )

    switch result {
    case .authenticated(let login):
        return login
    case .credentialRequired(let challenge):
        let pin = try await promptForPin(isNew: challenge.action == .setup)
        return try await sdk.submitCredential(pin)
    default:
        // .mnemonicGenerated, .recoveryRequired, .accountCreationRequired:
        // see Getting Started.
        throw SDKError.stateError(message: "unhandled auth result")
    }
}

The vault survives logout() and lock(); call deleteVault() to erase it, for example when the user removes the account from the device. Auto-lock below wipes the decrypted keys on a timer and sends the user through this same unlock on the next key access.

Basic Keychain Wrapper

Create a Keychain helper:

import Foundation
import Security

enum KeychainError: Error {
    case duplicateItem
    case itemNotFound
    case unexpectedStatus(OSStatus)
    case invalidData
}

class KeychainManager {
    static let shared = KeychainManager()

    private let service = "com.yourapp.privacyboost"

    private init() {}

    // MARK: - Save

    func save(_ data: Data, for key: String) throws {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
            kSecValueData as String: data,
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
        ]

        let status = SecItemAdd(query as CFDictionary, nil)

        if status == errSecDuplicateItem {
            // Update existing item
            let updateQuery: [String: Any] = [
                kSecClass as String: kSecClassGenericPassword,
                kSecAttrService as String: service,
                kSecAttrAccount as String: key
            ]

            let attributes: [String: Any] = [
                kSecValueData as String: data
            ]

            let updateStatus = SecItemUpdate(updateQuery as CFDictionary, attributes as CFDictionary)
            guard updateStatus == errSecSuccess else {
                throw KeychainError.unexpectedStatus(updateStatus)
            }
        } else if status != errSecSuccess {
            throw KeychainError.unexpectedStatus(status)
        }
    }

    // MARK: - Load

    func load(for key: String) throws -> Data {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
            kSecReturnData as String: true,
            kSecMatchLimit as String: kSecMatchLimitOne
        ]

        var result: AnyObject?
        let status = SecItemCopyMatching(query as CFDictionary, &result)

        guard status == errSecSuccess else {
            if status == errSecItemNotFound {
                throw KeychainError.itemNotFound
            }
            throw KeychainError.unexpectedStatus(status)
        }

        guard let data = result as? Data else {
            throw KeychainError.invalidData
        }

        return data
    }

    // MARK: - Delete

    func delete(for key: String) throws {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key
        ]

        let status = SecItemDelete(query as CFDictionary)
        guard status == errSecSuccess || status == errSecItemNotFound else {
            throw KeychainError.unexpectedStatus(status)
        }
    }

    // MARK: - Exists

    func exists(for key: String) -> Bool {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
            kSecReturnData as String: false
        ]

        let status = SecItemCopyMatching(query as CFDictionary, nil)
        return status == errSecSuccess
    }
}

Session Storage

Store and retrieve Privacy Boost sessions:

import PrivacyBoost

class SessionStorage {
    static let shared = SessionStorage()

    private let keychain = KeychainManager.shared
    private let sessionKey = "privacyboost.session"

    private init() {}

    // MARK: - Save Session

    func saveSession(_ session: ExportedSession) throws {
        let data = try encodeSession(session)
        try keychain.save(data, for: sessionKey)
    }

    // MARK: - Load Session

    func loadSession() throws -> ExportedSession {
        let data = try keychain.load(for: sessionKey)
        return try decodeSession(data)
    }

    // MARK: - Delete Session

    func deleteSession() throws {
        try keychain.delete(for: sessionKey)
    }

    // MARK: - Has Session

    func hasSession() -> Bool {
        return keychain.exists(for: sessionKey)
    }

    // MARK: - Encoding

    private func encodeSession(_ session: ExportedSession) throws -> Data {
        let dict: [String: Any] = [
            "version": session.version,
            "data": session.data
        ]

        return try JSONSerialization.data(withJSONObject: dict)
    }

    private func decodeSession(_ data: Data) throws -> ExportedSession {
        guard let dict = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw KeychainError.invalidData
        }

        return ExportedSession(
            version: dict["version"] as? UInt32 ?? 1,
            data: dict["data"] as? String ?? ""
        )
    }
}

Biometric Protection

Add Face ID/Touch ID protection:

import LocalAuthentication

class BiometricSessionStorage {
    static let shared = BiometricSessionStorage()

    private let keychain = KeychainManager.shared
    private let sessionKey = "privacyboost.session.biometric"

    private init() {}

    // MARK: - Save with Biometrics

    func saveSession(_ session: ExportedSession) throws {
        let data = try encodeSession(session)

        // Create access control with biometrics
        var error: Unmanaged<CFError>?
        guard let accessControl = SecAccessControlCreateWithFlags(
            kCFAllocatorDefault,
            kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
            .biometryCurrentSet,
            &error
        ) else {
            throw error!.takeRetainedValue() as Error
        }

        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: "com.yourapp.privacyboost.biometric",
            kSecAttrAccount as String: sessionKey,
            kSecValueData as String: data,
            kSecAttrAccessControl as String: accessControl
        ]

        // Delete existing and add new
        SecItemDelete(query as CFDictionary)
        let status = SecItemAdd(query as CFDictionary, nil)

        guard status == errSecSuccess else {
            throw KeychainError.unexpectedStatus(status)
        }
    }

    // MARK: - Load with Biometrics

    func loadSession() async throws -> ExportedSession {
        return try await withCheckedThrowingContinuation { continuation in
            let context = LAContext()
            context.localizedReason = "Access your Privacy Boost session"

            let query: [String: Any] = [
                kSecClass as String: kSecClassGenericPassword,
                kSecAttrService as String: "com.yourapp.privacyboost.biometric",
                kSecAttrAccount as String: sessionKey,
                kSecReturnData as String: true,
                kSecUseAuthenticationContext as String: context
            ]

            DispatchQueue.global().async {
                var result: AnyObject?
                let status = SecItemCopyMatching(query as CFDictionary, &result)

                if status == errSecSuccess, let data = result as? Data {
                    do {
                        let session = try self.decodeSession(data)
                        continuation.resume(returning: session)
                    } catch {
                        continuation.resume(throwing: error)
                    }
                } else {
                    continuation.resume(throwing: KeychainError.unexpectedStatus(status))
                }
            }
        }
    }

    // MARK: - Check Biometrics Available

    static var biometricsAvailable: Bool {
        let context = LAContext()
        var error: NSError?
        return context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error)
    }

    static var biometricType: String {
        let context = LAContext()
        _ = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)

        switch context.biometryType {
        case .faceID:
            return "Face ID"
        case .touchID:
            return "Touch ID"
        case .opticID:
            return "Optic ID"
        default:
            return "Biometrics"
        }
    }

    // MARK: - Encoding (same as SessionStorage)

    private func encodeSession(_ session: ExportedSession) throws -> Data {
        let dict: [String: Any] = [
            "version": session.version,
            "data": session.data
        ]
        return try JSONSerialization.data(withJSONObject: dict)
    }

    private func decodeSession(_ data: Data) throws -> ExportedSession {
        guard let dict = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw KeychainError.invalidData
        }

        return ExportedSession(
            version: dict["version"] as? UInt32 ?? 1,
            data: dict["data"] as? String ?? ""
        )
    }
}

Usage in App

Integrate with your SDK manager:

actor SDKManager {
    // ... existing code ...

    func restoreSession() async throws -> Bool {
        // Try biometric first
        if BiometricSessionStorage.biometricsAvailable {
            do {
                let session = try await BiometricSessionStorage.shared.loadSession()
                return try sdk.importSession(session)
            } catch {
                // Fall through to regular storage
            }
        }

        // Try regular storage
        if SessionStorage.shared.hasSession() {
            let session = try SessionStorage.shared.loadSession()
            return try sdk.importSession(session)
        }

        return false
    }

    func saveCurrentSession(withBiometrics: Bool = false) throws {
        guard let session = sdk.exportSession() else {
            return
        }

        if withBiometrics && BiometricSessionStorage.biometricsAvailable {
            try BiometricSessionStorage.shared.saveSession(session)
        } else {
            try SessionStorage.shared.saveSession(session)
        }
    }

    func clearSession() throws {
        try SessionStorage.shared.deleteSession()
    }
}

Auto-lock

Persisting a session keeps the encrypted vault on disk; auto-lock bounds how long the decrypted keys stay in memory. Two optional PrivacyBoostConfig fields drive it, both in seconds:

idleTtlSecs: how long the keys may go unused before the SDK wipes them.
absoluteTtlSecs: how long after an unlock the SDK wipes them, regardless of activity.

nil or 0 disables the respective timer, and both default to nil. The timers are checked lazily, on the next key access: once one has elapsed, that access zeroizes the resident keys and throws SDKError.notAuthenticated. They bound key use rather than key residency, so a screen that needs the keys gone at a fixed time should call lock() from its own timer.

let config = PrivacyBoostConfig(
    serverUrl: "https://indexer.example.com",
    chainId: nil,
    shieldContractAddress: nil,
    wethContractAddress: nil,
    teePublicKey: nil,
    appId: "my-app",
    persistenceStorage: .osKeychain,
    persistenceUnlock: .biometric,
    idleTtlSecs: 300,          // wipe keys after 5 minutes without use
    absoluteTtlSecs: 43_200    // and 12 hours after unlock, no matter what
)

lock() does the same on demand. It zeroizes the key material and drops the session JWT but keeps the persisted vault, which makes it the right call when the app moves to the background:

func sceneDidEnterBackground(_ scene: UIScene) {
    sdk.lock()
}

To unlock, call authenticate again. With a persisted vault the SDK reopens it instead of re-deriving keys: PIN and password vaults return .credentialRequired, and the other unlock methods complete inside authenticate. Compare clearSession(), which drops the JWT but leaves the keys in memory for a quick re-auth, and logout(), which ends the session entirely. Chain-context handles created with createChainContext share the resident keys, so auto-lock and lock() apply to them too, but each keeps its own JWT; call clearSession() on the handle to drop it.

Security Best Practices

Use kSecAttrAccessibleWhenUnlockedThisDeviceOnly - Data only accessible when device is unlocked
Enable biometrics - Add Face ID/Touch ID for sensitive operations
Don’t store in UserDefaults - UserDefaults is not encrypted
Clear on logout - Delete Keychain items when user logs out
Handle errors gracefully - Don’t expose Keychain errors to users

Info.plist

Add Face ID usage description:

<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to secure your Privacy Boost session</string>

Next Steps

API Reference - Complete API documentation
iOS Getting Started - Integrate with SwiftUI

Quickstart

Setup

SDKs

Session storage

Session Storage

Why Keychain?

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

Basic Keychain Wrapper

Session Storage

Biometric Protection

Usage in App

Auto-lock

Security Best Practices

Info.plist

Next Steps

​Session Storage

​Why Keychain?

​SDK-Managed Persistence

​Unlock methods

​Unlocking on the next launch

​Basic Keychain Wrapper

​Session Storage

​Biometric Protection

​Usage in App

​Auto-lock

​Security Best Practices

​Info.plist

​Next Steps

Session Storage

Why Keychain?

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

Basic Keychain Wrapper

Session Storage

Biometric Protection

Usage in App

Auto-lock

Security Best Practices

Info.plist

Next Steps