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:
- A macOS smart-card token extension exposes hardware-backed keys and certificates to login and Keychain services.
- An app queries token-backed items through Security.framework while the token is present.
- 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.
| Type | Role | Important constraint |
|---|---|---|
TKTokenDriver, TKToken, TKTokenSession |
Driver/token/session primitives | Extension behavior depends on platform and extension point |
TKSmartCardTokenDriver |
Smart-card driver entry point | System login integration is a macOS extension flow |
TKSmartCard, TKSmartCardSlotManager |
Reader discovery and APDU transport | Default manager may be nil |
TKTokenWatcher |
Token insertion/removal | Retain it for the monitoring lifetime |
TKSmartCardSlotNFCSession |
Temporary NFC-backed slot | iOS/iPadOS 26+; always end the session |
TKSmartCardTokenRegistrationManager |
NFC token registration | iOS/iPadOS 26+ |
Core invariants
- A token extension declares
com.apple.ctk-tokensand the exactcom.apple.ctk.driver-class; the host app is only its delivery vehicle. - Populate
TKTokenKeychainContentswith stable, matching object IDs.TKTokenKeychainKeycapabilities must reflect the hardware. TKTokenSessionDelegate.supportsreturnstrueonly for algorithms and operations the token actually implements.- Wrap structured
sendcalls inwithSession; for rawtransmit, pairbeginSessionandendSessionon 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
TKTokenSmartCardPINAuthOperationfrom 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:
| Error | Expected response |
|---|---|
.canceledByUser |
Stop quietly or restore prior UI state |
.authenticationFailed / .authenticationNeeded |
Present bounded retry or authentication UI |
.tokenNotFound / .objectNotFound |
Ask for reinsertion or refresh token contents |
.communicationError |
End the session and offer a fresh attempt |
.corruptedData |
Reject the response; do not parse or trust partial data |
.notImplemented |
Disable the unsupported operation |
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.