cryptotokenkit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CryptoTokenKit

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+.
使用CryptoTokenKit框架访问安全令牌及其存储的加密资产。内容涵盖令牌驱动扩展、智能卡通信、令牌会话、钥匙串集成以及基于证书的身份验证。适配Swift 6.3版本。
平台可用性: CryptoTokenKit主要是一款macOS框架。智能卡读卡器访问(
TKSmartCard
,
TKSmartCardSlotManager
)仅支持macOS。令牌扩展API(
TKTokenDriver
,
TKToken
,
TKTokenSession
)仅适用于macOS。客户端令牌监控(
TKTokenWatcher
)和通过
kSecAttrTokenID
过滤的钥匙串查询支持iOS 14+/macOS 11+。NFC智能卡插槽会话支持iOS 16.4+。

Contents

目录

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.
CryptoTokenKit将硬件安全令牌(智能卡、USB令牌)与macOS身份验证和钥匙串服务相连接。该框架有两种主要使用模式:
令牌驱动扩展(仅macOS)—— 使硬件令牌的加密项对系统可用的应用扩展。宿主应用仅作为扩展的交付载体。
客户端令牌访问(macOS + iOS)—— 应用查询钥匙串中由令牌支持的项。当令牌存在时,CryptoTokenKit会自动将令牌项暴露为标准钥匙串条目。

Key Types

核心类型

TypeRolePlatform
TKTokenDriver
Base class for token driver extensionsmacOS
TKToken
Represents a hardware cryptographic tokenmacOS
TKTokenSession
Manages authentication state for a tokenmacOS
TKSmartCardTokenDriver
Entry point for smart card extensionsmacOS
TKSmartCard
Low-level smart card communicationmacOS
TKSmartCardSlotManager
Discovers and manages card reader slotsmacOS
TKTokenWatcher
Observes token insertion and removalmacOS, iOS 14+
TKTokenKeychainKey
A key stored on a tokenmacOS
TKTokenKeychainCertificate
A certificate stored on a tokenmacOS
类型作用平台
TKTokenDriver
令牌驱动扩展的基类macOS
TKToken
表示硬件加密令牌macOS
TKTokenSession
管理令牌的身份验证状态macOS
TKSmartCardTokenDriver
智能卡扩展的入口点macOS
TKSmartCard
底层智能卡通信macOS
TKSmartCardSlotManager
发现并管理读卡器插槽macOS
TKTokenWatcher
监控令牌的插入和移除macOS, iOS 14+
TKTokenKeychainKey
存储在令牌上的密钥macOS
TKTokenKeychainCertificate
存储在令牌上的证书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:
  1. TokenDriver (subclass of
    TKSmartCardTokenDriver
    ) -- entry point
  2. Token (subclass of
    TKSmartCardToken
    ) -- represents the token
  3. TokenSession (subclass of
    TKSmartCardTokenSession
    ) -- handles operations
令牌驱动是一款macOS应用扩展,用于使硬件令牌的加密功能对系统可用。宿主应用仅作为扩展的交付载体。
智能卡令牌扩展包含三个核心类:
  1. TokenDriver
    TKSmartCardTokenDriver
    的子类)—— 入口点
  2. Token
    TKSmartCardToken
    的子类)—— 表示令牌
  3. TokenSession
    TKSmartCardTokenSession
    的子类)—— 处理操作

Driver Class

驱动类

swift
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
        )
    }
}
swift
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:
swift
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)
    }
}
令牌从硬件读取证书和密钥,并填充其钥匙串内容:
swift
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

Info.plist与注册

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
:
shell
sudo -u _securityagent /Applications/TokenHost.app/Contents/MacOS/TokenHost
扩展的
Info.plist
必须指定驱动类:
NSExtension
  NSExtensionAttributes
    com.apple.ctk.driver-class = $(PRODUCT_MODULE_NAME).TokenDriver
  NSExtensionPointIdentifier = com.apple.ctk-tokens
通过以
_securityagent
身份启动宿主应用,完成一次扩展注册:
shell
sudo -u _securityagent /Applications/TokenHost.app/Contents/MacOS/TokenHost

Token Sessions

令牌会话

TKTokenSession
manages authentication state and performs cryptographic operations via its delegate.
swift
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)
        }
    }
}
TKTokenSession
管理身份验证状态,并通过其委托执行加密操作。
swift
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

PIN身份验证

Return a
TKTokenAuthOperation
from
beginAuthFor:
to prompt the user for PIN entry before cryptographic operations:
swift
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
}
beginAuthFor:
返回
TKTokenAuthOperation
,以便在执行加密操作前提示用户输入PIN:
swift
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).
TKSmartCard
提供与读卡器连接的智能卡的底层APDU通信(仅macOS)。

Discovering Card Readers

发现读卡器

swift
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)
            }
        }
    }
}
swift
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

发送APDU命令

Use
send(ins:p1:p2:data:le:)
for structured APDU communication. Always wrap calls in
withSession
:
swift
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.
使用
send(ins:p1:p2:data:le:)
进行结构化APDU通信。始终将调用包裹在
withSession
中:
swift
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)
        }
    }
}
对于原始APDU字节或非标准格式,使用
transmit(_:reply:)
并手动管理
beginSession
/
endSession
生命周期。

NFC Smart Card Sessions (iOS 16.4+)

NFC智能卡会话(iOS 16.4+)

On supported iOS devices, create NFC smart card sessions to communicate with contactless smart cards:
swift
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(...)
    }
}
在支持的iOS设备上,创建NFC智能卡会话以与非接触式智能卡通信:
swift
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:
swift
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
.
当令牌存在时,CryptoTokenKit会将其项暴露为标准钥匙串条目。使用
kSecAttrTokenID
属性查询这些条目:
swift
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
}
使用
kSecReturnPersistentRef
替代
kSecReturnRef
以获取跨应用启动仍有效的持久引用。当令牌被移除时,该引用将失效——需处理
errSecItemNotFound
错误,提示用户重新插入令牌。
使用
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
对于用户登录,令牌必须包含至少一个能够使用以下算法签名的密钥:EC签名摘要X962、RSA签名摘要PSS或RSA签名摘要PKCS1v15。
对于钥匙串解锁,令牌需要:
  • 256位EC密钥(
    kSecAttrKeyTypeECSECPrimeRandom
    ),支持
    ecdhKeyExchangeStandard
    ,或
  • 2048/3072/4096位RSA密钥(
    kSecAttrKeyTypeRSA
    ),支持
    rsaEncryptionOAEPSHA256
    解密

Smart Card Authentication Preferences (macOS)

智能卡身份验证偏好设置(macOS)

Configure in the
com.apple.security.smartcard
domain (MDM or systemwide):
KeyDefaultDescription
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.
com.apple.security.smartcard
域中配置(通过MDM或系统级设置):
默认值描述
allowSmartCard
true
启用智能卡身份验证
checkCertificateTrust
0
证书信任级别(0-3)
oneCardPerUser
false
将单个智能卡与账户绑定
enforceSmartCard
false
强制要求使用智能卡登录
信任级别:
0
= 信任所有证书,
1
= 验证有效性与颁发者,
2
= 额外验证软吊销,
3
= 额外验证硬吊销。

Token Watching

令牌监控

TKTokenWatcher
monitors token insertion and removal. Available on both macOS and iOS 14+.
swift
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)
        }
    }
}
TKTokenWatcher
监控令牌的插入和移除。支持macOS和iOS 14+。
swift
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:
CodeMeaning
.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
CryptoTokenKit操作会抛出
TKError
。主要错误代码:
代码含义
.notImplemented
令牌不支持该操作
.communicationError
与令牌通信失败
.corruptedData
令牌返回的数据已损坏
.canceledByUser
用户取消了操作
.authenticationFailed
PIN或密码错误
.objectNotFound
未找到请求的密钥或证书
.tokenNotFound
令牌已不存在
.authenticationNeeded
执行操作前需要身份验证

Common Mistakes

常见误区

DON'T: Query token keychain items without checking token presence

错误做法:未检查令牌存在性就查询令牌钥匙串项

swift
// 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)
swift
// 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

错误做法:假设智能卡API在iOS上可用

swift
// 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
}
swift
// 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

错误做法:跳过卡通信的会话管理

swift
// 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
    )
}
swift
// 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

错误做法:忽略APDU响应中的状态字

swift
// 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)
}
swift
// 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.
supports
委托方法必须反映硬件实际支持的算法。无条件返回
true
会导致系统尝试不支持的操作时出现运行时失败。

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
  • 已验证平台可用性(
    TKSmartCard
    仅支持macOS,
    TKTokenWatcher
    支持iOS 14+)
  • 令牌扩展目标的
    NSExtensionPointIdentifier
    设置为
    com.apple.ctk-tokens
  • Info.plist中
    com.apple.ctk.driver-class
    已设置为正确的驱动类
  • 安装期间通过
    _securityagent
    启动完成扩展注册
  • TKTokenSessionDelegate
    检查具体算法,而非无条件返回
    true
  • 智能卡会话已正确打开和关闭(使用
    withSession
    beginSession
    /
    endSession
  • 每次
    send
    调用后都检查了APDU状态字
  • 查询钥匙串前通过
    TKTokenWatcher
    验证令牌存在性
  • 已处理
    TKError
    情况并提供适当的用户反馈
  • 钥匙串内容已使用正确的
    objectID
    值填充
  • TKTokenKeychainKey
    的功能(
    canSign
    ,
    canDecrypt
    )与硬件匹配
  • 已根据部署环境配置适当的证书信任级别
  • 令牌移除时,已处理持久引用的
    errSecItemNotFound
    错误

References

参考资料