Access security tokens and smart cards using CryptoTokenKit. Use when building token driver extensions with TKTokenDriver and TKToken, communicating with smart…
CryptoTokenKit
Access security tokens and the cryptographic assets they store using the
CryptoTokenKit framework. Covers token driver extensions, smart card
communication, token sessions, keychain integration, and certificate-based
authentication. Targets Swift 6.3.
Platform availability: CryptoTokenKit is primarily a macOS framework.
Smart card reader access (TKSmartCard, TKSmartCardSlotManager) requires
macOS. Token extension APIs (TKTokenDriver, TKToken, TKTokenSession)
are macOS-only. Client-side token watching (TKTokenWatcher) and keychain
queries filtered by kSecAttrTokenID are available on iOS 14+/macOS 11+.
NFC smart card slot sessions are available on iOS 16.4+.
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 macOS authentication and keychain services. The framework has two main
usage modes:
Token driver extensions (macOS only) -- App extensions that make a
hardware token's cryptographic items available to the system. The driver
handles token lifecycle, session management, and cryptographic operations.
Client-side token access (macOS + iOS) -- Apps query the keychain for
items backed by tokens. CryptoTokenKit automatically exposes token items as
standard keychain entries when a token is present.
Key Types
Type
Role
Platform
TKTokenDriver
Base class for token driver extensions
macOS
TKToken
Represents a hardware cryptographic token
macOS
TKTokenSession
Manages authentication state for a token
macOS
TKSmartCardTokenDriver
Entry point for smart card extensions
macOS
TKSmartCard
Low-level smart card communication
macOS
TKSmartCardSlotManager
Discovers and manages card reader slots
macOS
TKTokenWatcher
Observes token insertion and removal
macOS, iOS 14+
TKTokenKeychainKey
A key stored on a token
macOS
TKTokenKeychainCertificate
A certificate stored on a token
macOS
Token Extensions
A token driver is a macOS 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:
TokenDriver (subclass of TKSmartCardTokenDriver) -- entry point
Token (subclass of TKSmartCardToken) -- represents the token
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
connected via readers (macOS-only).
Discovering Card Readers
import CryptoTokenKit
func discoverSmartCards() {
guard let slotManager = TKSmartCardSlotManager.default else {
print("Smart card services unavailable")
return
}
for slotName in slotManager.slotNames {
slotManager.getSlot(withName: slotName) { slot in
guard let slot else { return }
if slot.state == .validCard, let card = slot.makeSmartCard() {
communicateWith(card: card)
}
}
}
}
Sending APDU Commands
Use send(ins:p1:p2:data:le:) for structured APDU communication.
Always wrap calls in withSession:
func selectApplication(card: TKSmartCard, aid: Data) throws {
try card.withSession {
let (sw, response) = try card.send(
ins: 0xA4, p1: 0x04, p2: 0x00, data: aid, le: nil
)
guard sw == 0x9000 else {
throw TKError(.communicationError)
}
}
}
For raw APDU bytes or non-standard formats, use transmit(_:reply:) with
manual beginSession/endSession lifecycle management.
NFC Smart Card Sessions (iOS 16.4+)
On supported iOS devices, create NFC smart card sessions to communicate
with contactless smart cards:
func readNFCSmartCard() {
guard let slotManager = TKSmartCardSlotManager.default,
slotManager.isNFCSupported() else { return }
slotManager.createNFCSlot(message: "Hold card near iPhone") { session, error in
guard let session else { return }
defer { session.end() }
guard let slotName = session.slotName,
let slot = slotManager.slotNamed(slotName),
let card = slot.makeSmartCard() else { return }
// Communicate with the NFC card using card.send(...)
}
}
Keychain Integration
When a token is present, CryptoTokenKit exposes its items as standard
keychain entries. Query them using the kSecAttrTokenID attribute:
import Security
func findTokenKey(tokenID: String) throws -> SecKey {
let query: [String: Any] = [
kSecClass as String: kSecClassKey,
kSecAttrTokenID as String: tokenID,
kSecReturnRef as String: true
]
var result: CFTypeRef?
let status = SecItemCopyMatching(query as CFDictionary, &result)
guard status == errSecSuccess, let key = result else {
throw TKError(.objectNotFound)
}
return key as! SecKey
}
Use kSecReturnPersistentRef instead of kSecReturnRef to obtain a
persistent reference that survives across app launches. The reference
becomes invalid when the token is removed -- handle errSecItemNotFound
by prompting the user to reinsert the token.
Query certificates the same way with kSecClass: kSecClassCertificate.
Certificate Authentication
Token Key Requirements
For user login, the token must contain at least one key capable of signing
with: EC signature digest X962, RSA signature digest PSS, or RSA signature
digest PKCS1v15.
For keychain unlock, the token needs:
256-bit EC key (kSecAttrKeyTypeECSECPrimeRandom) supporting
ecdhKeyExchangeStandard, or
2048/3072/4096-bit RSA key (kSecAttrKeyTypeRSA) supporting
rsaEncryptionOAEPSHA256 decryption
Smart Card Authentication Preferences (macOS)
Configure in the com.apple.security.smartcard domain (MDM or systemwide):
Key
Default
Description
allowSmartCard
true
Enable smart card authentication
checkCertificateTrust
0
Certificate trust level (0-3)
oneCardPerUser
false
Pair a single smart card to an account
enforceSmartCard
false
Require smart card for login
Trust levels: 0 = trust all, 1 = validity + issuer, 2 = + soft
revocation, 3 = + hard revocation.
Token Watching
TKTokenWatcher monitors token insertion and removal. Available on both
macOS and iOS 14+.
import CryptoTokenKit
final class TokenMonitor {
private let watcher = TKTokenWatcher()
func startMonitoring() {
for tokenID in watcher.tokenIDs {
print("Token present: \(tokenID)")
if let info = watcher.tokenInfo(forTokenID: tokenID) {
print(" Driver: \(info.driverName ?? "unknown")")
print(" Slot: \(info.slotName ?? "unknown")")
}
}
watcher.setInsertionHandler { [weak self] tokenID in
print("Token inserted: \(tokenID)")
self?.watcher.addRemovalHandler({ removedTokenID in
print("Token removed: \(removedTokenID)")
}, forTokenID: tokenID)
}
}
}
Error Handling
CryptoTokenKit operations throw TKError. Key error codes:
Code
Meaning
.notImplemented
Operation not supported by this token
.communicationError
Communication with token failed
.corruptedData
Data from token is corrupted
.canceledByUser
User canceled the operation
.authenticationFailed
PIN or password incorrect
.objectNotFound
Requested key or certificate not found
.tokenNotFound
Token is no longer present
.authenticationNeeded
Authentication required before operation
Common Mistakes
DON'T: Query token keychain items without checking token presence
// WRONG -- query may fail if token was removed
let key = try findTokenKey(tokenID: savedTokenID)
// CORRECT -- verify the token is still present first
let watcher = TKTokenWatcher()
guard watcher.tokenIDs.contains(savedTokenID) else {
promptUserToInsertToken()
return
}
let key = try findTokenKey(tokenID: savedTokenID)
DON'T: Assume smart card APIs work on iOS
// WRONG -- TKSmartCardSlotManager.default is nil on iOS
let manager = TKSmartCardSlotManager.default! // Crashes on iOS
// CORRECT -- guard availability
guard let manager = TKSmartCardSlotManager.default else {
print("Smart card services unavailable on this platform")
return
}
DON'T: Skip session management for card communication
// WRONG -- sending commands without a session
card.transmit(apdu) { response, error in /* may fail */ }
// CORRECT -- use withSession or beginSession/endSession
try card.withSession {
let (sw, response) = try card.send(
ins: 0xCA, p1: 0x00, p2: 0x6E, data: nil, le: 0
)
}
DON'T: Ignore status words in APDU responses
// WRONG -- assuming success
let (_, response) = try card.send(ins: 0xA4, p1: 0x04, p2: 0x00, data: aid, le: nil)
// CORRECT -- check status word
let (sw, response) = try card.send(ins: 0xA4, p1: 0x04, p2: 0x00, data: aid, le: nil)
guard sw == 0x9000 else {
throw SmartCardError.commandFailed(statusWord: sw)
}
DON'T: Hard-code blanket algorithm support
The supports delegate method must reflect what the hardware actually
implements. Returning true unconditionally causes runtime failures when
the system attempts unsupported operations.
Review Checklist
Platform availability verified (TKSmartCard macOS-only, TKTokenWatcher iOS 14+)
Token extension target uses NSExtensionPointIdentifier = com.apple.ctk-tokens
com.apple.ctk.driver-class set to the correct driver class in Info.plist
Extension registered via _securityagent launch during installation
TKTokenSessionDelegate checks specific algorithms, not blanket true
Smart card sessions opened and closed (withSession or beginSession/endSession)
APDU status words checked after every send call
Token presence verified via TKTokenWatcher before keychain queries
TKError cases handled with appropriate user feedback
Keychain contents populated with correct objectID values
TKTokenKeychainKey capabilities (canSign, canDecrypt) match hardware
Certificate trust level configured appropriately for deployment environment
errSecItemNotFound handled for persistent references when token is removed
References
Extended patterns (PIV commands, TLV parsing, generic token drivers, APDU helpers, secure PIN): references/cryptotokenkit-patterns.md
CryptoTokenKit framework
TKTokenDriver
TKToken
TKTokenSession
TKSmartCard
TKSmartCardSlotManager
TKTokenWatcher
Authenticating Users with a Cryptographic Token
Using Cryptographic Assets Stored on a Smart Card
Configuring Smart Card Authenticationdon't have the plugin yet? install it then click "run inline in claude" again.