CryptoTokenKit

Use CryptoTokenKit for token-driver extensions, smart-card sessions, token-backed Keychain items, certificate authentication, and iOS/iPadOS 26+ NFC smart-card access.

API presence is not an access guarantee: extension points, entitlements, hardware, and runtime support all matter. The login/keychain-unlock token extension flow is macOS-specific, TKSmartCardSlotManager.default is optional, and NFC smart-card slot creation requires iOS/iPadOS 26+.

Contents

• Choose the workflow
• Architecture and boundaries
• Core invariants
• Platform and capability checks
• Error handling
• Common mistakes
• Review checklist
• References

Choose the workflow

• For the macOS driver/token/session classes, extension Info.plist, PIN auth, low-level APDU sessions, token-backed Keychain queries, NFC slot lifecycle, and certificate requirements, read Token and smart-card workflows.
• For PIV selection and signing, BER/compact TLV parsing, generic token drivers, command chaining, large responses, secure PIN operations, configuration, slot monitoring, and registration, read CryptoTokenKit extended patterns.

Architecture and boundaries

CryptoTokenKit has three distinct modes:

1. A macOS smart-card token extension exposes hardware-backed keys and certificates to login and Keychain services.
2. An app queries token-backed items through Security.framework while the token is present.
3. An iOS/iPadOS 26+ app creates a temporary NFC smart-card slot and communicates through TKSmartCard.

Own token/smart-card sessions, token-backed items, APDUs, PIN operations, and smart-card certificate authentication here. Route passkeys/WebAuthn and account sign-in to authentication; route CryptoKit primitives, Secure Enclave, ordinary Keychain architecture, pinning, and trust policy to swift-security.

Core invariants

• A token extension declares com.apple.ctk-tokens and the exact com.apple.ctk.driver-class; the host app is only its delivery vehicle.
• Populate TKTokenKeychainContents with stable, matching object IDs. TKTokenKeychainKey capabilities must reflect the hardware.
• TKTokenSessionDelegate.supports returns true only for algorithms and operations the token actually implements.
• Wrap structured send calls in withSession; for raw transmit, pair beginSession and endSession on every path.
• Check every APDU status word. Transport success does not mean command success.
• Verify token presence before queries. Persistent references become invalid after removal and must handle errSecItemNotFound.
• Configure TKTokenSmartCardPINAuthOperation from the real card format and APDU layout; never log or retain PIN bytes.
• End every TKSmartCardSlotNFCSession, including error and cancellation paths.

Platform and capability checks

import CryptoTokenKit

guard let manager = TKSmartCardSlotManager.default else {
    // Missing entitlement/access, unsupported runtime, or no smart-card service.
    return
}

On iOS/iPadOS 26+, also require manager.isNFCSupported() before creating an NFC slot. Keep macOS configuration and system-authentication guidance outside iOS-only branches. Do not force unwrap a manager, slot, card, certificate, or keychain item obtained from hardware.

Error handling

Handle TKError according to recovery semantics:

Preserve smart-card-specific status information in app errors without exposing secrets. Avoid blind retries of PIN or destructive card commands.

Common Mistakes

• Treating framework availability as proof that the manager, reader, or NFC capability exists.
• Sending APDUs outside a managed session or ignoring status words.
• Returning blanket algorithm support from the token-session delegate.
• Querying stale token references without observing insertion/removal.
• Declaring signing/decryption/login capabilities not supported by hardware.
• Reusing macOS extension setup in an iOS app target.

Review Checklist

• Exact platform, extension point, entitlement, and hardware requirements are documented.
• Optional manager/slot/card objects are guarded.
• Extension point and driver class are correct for macOS token extensions.
• Object IDs and key capabilities match real token contents.
• Delegate support is algorithm-specific.
• Every APDU runs in a session and validates its status word.
• PIN flow uses the card's real format and has bounded retry behavior.
• Token watcher lifetime covers every query that depends on presence.
• Persistent-reference invalidation is handled.
• NFC support is checked and every NFC session ends.

References

• Token and smart-card workflows
• CryptoTokenKit extended patterns
• CryptoTokenKit documentation
• Smart-card entitlement