Cryptotokenkit

CryptoTokenKit

Use CryptoTokenKit for token driver extensions, smart-card communication, token sessions, token-backed keychain integration, and certificate-based authentication in Swift 6.3 apps.

Platform availability: CryptoTokenKit classes are available across Apple platforms, but capability depends on extension point, entitlement, hardware, and OS version. The smart-card app extension flow for login/keychain unlock is macOS. TKSmartCardSlotManager.default is optional and returns nil unless smart-card access is enabled. iOS/iPadOS 26+ add NFC smart-card slots and registration.

Contents

• Architecture Overview
• Token Extensions
• Token Sessions
• Smart Card Communication
• Keychain Integration
• Certificate Authentication
• Token Watching
• Error Handling
• Common Mistakes
• Review Checklist
• References

Architecture Overview

CryptoTokenKit bridges hardware security tokens (smart cards, USB tokens) with authentication and keychain services. The framework has three main usage modes:

Smart-card token extensions -- macOS app extensions that make a hardware token's cryptographic items available to system login and keychain unlock. The driver handles token lifecycle, session management, and cryptographic operations.

Client-side token access -- Apps query the keychain for items backed by tokens. CryptoTokenKit exposes token items as standard keychain entries when a token is present.

NFC smart-card access -- iOS/iPadOS 26+ apps create a temporary NFC smart card slot and communicate with the presented contactless card through TKSmartCard.

Boundary routing: Own token/smart-card sessions, token-backed keychain items, and certificate-based smart-card auth. Route passkeys/WebAuthn and account sign-in to authentication; route Secure Enclave, CryptoKit primitives, keychain architecture, certificate pinning, and trust policy to swift-security.

Key Types

Token Extensions

For system login and keychain unlock on macOS, a token driver is an app extension that makes a hardware token's cryptographic capabilities available to the system. The host app exists only as a delivery mechanism for the extension.

A smart card token extension has three core classes:

1. TokenDriver (subclass of TKSmartCardTokenDriver) -- entry point
2. Token (subclass of TKSmartCardToken) -- represents the token
3. TokenSession (subclass of TKSmartCardTokenSession) -- handles operations

Driver Class

import CryptoTokenKit

final class TokenDriver: TKSmartCardTokenDriver, TKSmartCardTokenDriverDelegate {
    func tokenDriver(
        _ driver: TKSmartCardTokenDriver,
        createTokenFor smartCard: TKSmartCard,
        aid: Data?
    ) throws -> TKSmartCardToken {
        return try Token(
            smartCard: smartCard,
            aid: aid,
            instanceID: "com.example.token:\(smartCard.slot.name)",
            tokenDriver: driver
        )
    }
}

Token Class

The token reads certificates and keys from hardware and populates its keychain contents:

final class Token: TKSmartCardToken, TKTokenDelegate {
    init(
        smartCard: TKSmartCard, aid: Data?,
        instanceID: String, tokenDriver: TKSmartCardTokenDriver
    ) throws {
        try super.init(
            smartCard: smartCard, aid: aid,
            instanceID: instanceID, tokenDriver: tokenDriver
        )
        self.delegate = self

        let certData = try readCertificate(from: smartCard)
        guard let cert = SecCertificateCreateWithData(nil, certData as CFData) else {
            throw TKError(.corruptedData)
        }

        let certItem = TKTokenKeychainCertificate(certificate: cert, objectID: "cert-auth")
        let keyItem = TKTokenKeychainKey(certificate: cert, objectID: "key-auth")
        keyItem?.canSign = true
        keyItem?.canDecrypt = false
        keyItem?.isSuitableForLogin = true

        self.keychainContents?.fill(with: [certItem!, keyItem!])
    }

    func createSession(_ token: TKToken) throws -> TKTokenSession {
        TokenSession(token: token)
    }
}

Info.plist and Registration

The extension's Info.plist must name the driver class:

NSExtension
  NSExtensionAttributes
    com.apple.ctk.driver-class = $(PRODUCT_MODULE_NAME).TokenDriver
  NSExtensionPointIdentifier = com.apple.ctk-tokens

Register the extension once by launching the host app as _securityagent:

sudo -u _securityagent /Applications/TokenHost.app/Contents/MacOS/TokenHost

Token Sessions

TKTokenSession manages authentication state and performs cryptographic operations via its delegate.

final class TokenSession: TKSmartCardTokenSession, TKTokenSessionDelegate {
    func tokenSession(
        _ session: TKTokenSession,
        supports operation: TKTokenOperation,
        keyObjectID: TKToken.ObjectID,
        algorithm: TKTokenKeyAlgorithm
    ) -> Bool {
        switch operation {
        case .signData:
            return algorithm.isAlgorithm(.rsaSignatureDigestPKCS1v15SHA256)
                || algorithm.isAlgorithm(.ecdsaSignatureDigestX962SHA256)
        case .decryptData:
            return algorithm.isAlgorithm(.rsaEncryptionOAEPSHA256)
        case .performKeyExchange:
            return algorithm.isAlgorithm(.ecdhKeyExchangeStandard)
        default:
            return false
        }
    }

    func tokenSession(
        _ session: TKTokenSession,
        sign dataToSign: Data,
        keyObjectID: TKToken.ObjectID,
        algorithm: TKTokenKeyAlgorithm
    ) throws -> Data {
        let smartCard = try getSmartCard()
        return try smartCard.withSession {
            try performCardSign(smartCard: smartCard, data: dataToSign, keyID: keyObjectID)
        }
    }

    func tokenSession(
        _ session: TKTokenSession,
        decrypt ciphertext: Data,
        keyObjectID: TKToken.ObjectID,
        algorithm: TKTokenKeyAlgorithm
    ) throws -> Data {
        let smartCard = try getSmartCard()
        return try smartCard.withSession {
            try performCardDecrypt(smartCard: smartCard, data: ciphertext, keyID: keyObjectID)
        }
    }
}

PIN Authentication

Return a TKTokenAuthOperation from beginAuthFor: to prompt the user for PIN entry before cryptographic operations:

func tokenSession(
    _ session: TKTokenSession,
    beginAuthFor operation: TKTokenOperation,
    constraint: Any
) throws -> TKTokenAuthOperation {
    let pinAuth = TKTokenSmartCardPINAuthOperation()
    pinAuth.pinFormat.charset = .numeric
    pinAuth.pinFormat.minPINLength = 4
    pinAuth.pinFormat.maxPINLength = 8
    pinAuth.smartCard = (session as? TKSmartCardTokenSession)?.smartCard
    pinAuth.apduTemplate = buildVerifyAPDU()
    pinAuth.pinByteOffset = 5
    return pinAuth
}

Smart Card Communication

TKSmartCard provides low-level APDU communication with smart cards. TKSmartCardSlotManager.default is optional; treat nil as unavailable