### Implement tokenForConfiguration for TKTokenDriverDelegate

Source: https://context7.com/purebred/ctkprovider/llms.txt

Creates a new Token instance when the system accesses the token extension. The driver must be registered in the Info.plist.

```objective-c
// TokenDriver.m - TKTokenDriverDelegate implementation

@implementation TokenDriver

- (TKToken *)tokenDriver:(TKTokenDriver *)driver
    tokenForConfiguration:(TKTokenConfiguration *)configuration
                    error:(NSError **)error
{
    // Log token creation for debugging
    NSLog(@"Creating token for configuration: %@", configuration.instanceID);

    // Create and return new Token instance
    // instanceID is the SHA256 hash of the certificate
    return [[Token alloc] initWithTokenDriver:self
                                   instanceID:configuration.instanceID];
}

@end
```

--------------------------------

### Create Token Session with Error Handling

Source: https://context7.com/purebred/ctkprovider/llms.txt

Initializes a new TokenSession for cryptographic operations. Includes logging and keychain item enumeration for debugging. Ensure proper error handling when creating the session.

```objective-c
// Token.m - TKTokenDelegate implementation

@implementation Token

- (TKTokenSession *)token:(TKToken *)token
     createSessionWithError:(NSError **)error
{
    // Log session creation with token details
    NSLog(@"Creating session for token: %@", [token configuration]);

    // Enumerate keychain items for debugging
    TKTokenKeychainContents* contents = [token keychainContents];
    NSArray<TKTokenKeychainItem *>* items = [contents items];

    for (TKTokenKeychainItem* item in items) {
        NSLog(@"Keychain item - objectID: %@, label: %@",
              [item objectID], [item label]);
    }

    // Create and return session
    return [[TokenSession alloc] initWithToken:self];
}

@end

// Session lifecycle:
// 1. System/app requests cryptographic operation
// 2. Token driver creates Token via tokenForConfiguration
// 3. Token creates session via createSessionWithError
// 4. Session handles supportsOperation, signData, decryptData calls
// 5. Session may be reused or recreated for subsequent operations

```

--------------------------------

### Add Signing Token Action

Source: https://github.com/purebred/ctkprovider/blob/main/README.md

This code demonstrates how to add a signing token by retrieving an identity from a PKCS12 file and passing it to the AddItem function. Ensure the identity is released after use.

```Objective-C
    SecIdentityRef identity = GetIdentity(@"signature", @"password");
    AddItem(identity);
    CFRelease(identity);

```

--------------------------------

### Token Driver Implementation

Source: https://context7.com/purebred/ctkprovider/llms.txt

Implementation of the TokenDriver which creates token instances for the Crypto Token Kit framework.

```APIDOC
## Token Driver Implementation

### tokenForConfiguration - Create Token Instance

### Description
Creates a new Token instance when the system needs to access the token extension. Called by the Crypto Token Kit framework when a token is accessed.

### Method
Objective-C (TokenDriverDelegate)

### Endpoint
N/A (Method within a delegate)

### Parameters
#### Method Parameters
- **driver** (TKTokenDriver *) - The token driver instance.
- **configuration** (TKTokenConfiguration *) - The configuration for the token.
- **error** (NSError **) - A pointer to an NSError object that will be set if an error occurs.

### Response
#### Success Response
- **TKToken *** - A new instance of the Token.

#### Error Response
- **nil** - If token creation fails, an NSError object will be returned via the error parameter.

### Notes
- The `instanceID` is the SHA256 hash of the certificate.
- The `TokenDriver` is registered in `Info.plist` with specific attributes for the Crypto Token Kit.
```

--------------------------------

### Convert TKTokenKeyAlgorithm to SecKeyAlgorithm (Objective-C)

Source: https://context7.com/purebred/ctkprovider/llms.txt

Converts a TKTokenKeyAlgorithm to its equivalent SecKeyAlgorithm for use with Security framework functions. Logs an unrecognized algorithm and returns nil if no mapping is found. Useful for bridging token key algorithms to system APIs.

```Objective-C
// TokenUtils.m

SecKeyAlgorithm GetAlgorithmFromTKTokenKeyAlgorithm(TKTokenKeyAlgorithm* algorithm)
{
    // Signature algorithms
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureRaw])
        return kSecKeyAlgorithmRSASignatureRaw;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256])
        return kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256])
        return kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPSSSHA256])
        return kSecKeyAlgorithmRSASignatureDigestPSSSHA256;

    // Encryption algorithms
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionPKCS1])
        return kSecKeyAlgorithmRSAEncryptionPKCS1;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionOAEPSHA256])
        return kSecKeyAlgorithmRSAEncryptionOAEPSHA256;

    // ... 76 total algorithm mappings

    NSLog(@"Unrecognized algorithm: %@", algorithm);
    return nil;
}

// Usage in signData/decryptData:
// SecKeyAlgorithm secAlg = GetAlgorithmFromTKTokenKeyAlgorithm(algorithm);
// if (SecKeyIsAlgorithmSupported(key, kSecKeyOperationTypeSign, secAlg)) {
//     CFDataRef sig = SecKeyCreateSignature(key, secAlg, data, &error);
// }
```

--------------------------------

### Create and Add Keychain Items

Source: https://github.com/purebred/ctkprovider/blob/main/README.md

Creates TKTokenKeychainCertificate and TKTokenKeychainKey objects from a certificate reference and adds them to the token configuration's keychain items. This is used to associate a SecIdentityRef with the token.

```objective-c
    NSArray<TKTokenKeychainItem *>* keychainItems = [[NSMutableArray<TKTokenKeychainItem*> alloc]init];
    TKTokenKeychainCertificate* tokenKeychainCertificate = [[TKTokenKeychainCertificate alloc]initWithCertificate:certificateRef objectID:label];
    keychainItems = [keychainItems arrayByAddingObject:tokenKeychainCertificate];

    TKTokenKeychainKey* tokenKeychainKey = [[TKTokenKeychainKey alloc]initWithCertificate:certificateRef objectID:label];
    tokenConfiguration.keychainItems = [keychainItems arrayByAddingObject:tokenKeychainKey];
```

--------------------------------

### Dump Token Configurations Objective-C

Source: https://context7.com/purebred/ctkprovider/llms.txt

Dumps token configurations to the console for debugging purposes. It logs driver class IDs, token instance IDs, and keychain item details.

```objective-c
// ViewController.m

// Dump token configurations to console for debugging
- (IBAction)onDump:(id)sender {
    NSDictionary* driverConfigs = [TKTokenDriverConfiguration driverConfigurations];

    for (id driverKey in driverConfigs) {
        TKTokenDriverConfiguration* driverConfig = driverConfigs[driverKey];
        NSLog(@"Driver classID: %@", [driverConfig classID]);

        NSDictionary* tokenConfigs = [driverConfig tokenConfigurations];
        for (id tokenKey in tokenConfigs) {
            TKTokenConfiguration* tokenConfig = tokenConfigs[tokenKey];
            NSLog(@"Token instanceID: %@", [tokenConfig instanceID]);

            for (TKTokenKeychainItem* item in [tokenConfig keychainItems]) {
                NSLog(@"  Item objectID: %@, label: %@",
                      [item objectID], [item label]);
            }
        }
    }
}
```

--------------------------------

### Obtain Token Driver Configuration

Source: https://github.com/purebred/ctkprovider/blob/main/README.md

Retrieves the driver configurations for a token. The dictionary should contain exactly one TKTokenDriverConfiguration item, keyed by the extension's bundle identifier.

```objective-c
    TKTokenDriverConfiguration* tokenDriverConfiguration = nil;
    NSDictionary<TKTokenDriverClassID, TKTokenDriverConfiguration *>* driverConfigurations = [TKTokenDriverConfiguration driverConfigurations];

    // There should be just one named with the bundle identifier of the extension
    for (id key in driverConfigurations) {
        tokenDriverConfiguration = [driverConfigurations objectForKey:key];
    }
```

--------------------------------

### Implement signData for TKTokenSessionDelegate

Source: https://context7.com/purebred/ctkprovider/llms.txt

Signs data using a private key retrieved from the keychain, supporting various RSA signature algorithms.

```objective-c
// TokenSession.m - TKTokenSessionDelegate implementation

- (NSData *)tokenSession:(TKTokenSession *)session
                signData:(NSData *)dataToSign
                usingKey:(TKTokenObjectID)keyObjectID
               algorithm:(TKTokenKeyAlgorithm *)algorithm
                   error:(NSError **)error
{
    // Retrieve private key from keychain (uses cache for performance)
    SecKeyRef privateKeyRef = getKey(keyObjectID);
    if (privateKeyRef == nil) {
        privateKeyRef = GetPrivateKeyRef(keyObjectID);
        if (!privateKeyRef) {
            *error = [NSError errorWithDomain:TKErrorDomain
                                        code:TKErrorCodeObjectNotFound
                                    userInfo:@{NSLocalizedDescriptionKey:
                                              @"Failed to load private key"}];
            return nil;
        }
        putKey(keyObjectID, privateKeyRef);
    }

    // Convert TKTokenKeyAlgorithm to SecKeyAlgorithm
    SecKeyAlgorithm secAlgorithm = GetAlgorithmFromTKTokenKeyAlgorithm(algorithm);

    // Verify key supports this algorithm for signing
    if (!SecKeyIsAlgorithmSupported(privateKeyRef, kSecKeyOperationTypeSign, secAlgorithm)) {
        *error = [NSError errorWithDomain:TKErrorDomain
                                    code:TKErrorCodeBadParameter
                                userInfo:@{NSLocalizedDescriptionKey:
                                          @"Unsupported algorithm"}];
        return nil;
    }

    // Create signature
    CFErrorRef cfError;
    CFDataRef signature = SecKeyCreateSignature(privateKeyRef,
                                                secAlgorithm,
                                                (CFDataRef)dataToSign,
                                                &cfError);

    if (!signature) {
        *error = (__bridge_transfer NSError*)cfError;
        return nil;
    }

    return (__bridge_transfer NSData*)signature;
}
```

--------------------------------

### Parse PKCS12 and Import Identity to Keychain

Source: https://context7.com/purebred/ctkprovider/llms.txt

Loads a private key and certificate from a bundled PKCS12 file and imports it into the iOS keychain. The key is protected with `kSecAccessControlUserPresence`, requiring user authentication for cryptographic operations.

```Objective-C
#import "CtkProviderUtils.h"

// Load identity from a bundled .p12 file
// The label parameter corresponds to the filename (without .p12 extension)
// The password parameter is used to decrypt the PKCS12 contents
SecIdentityRef identity = GetIdentity(@"signature", @"password");

if (identity != nil) {
    // Identity successfully loaded and key imported to keychain
    // Key is protected with kSecAccessControlUserPresence
    // User must authenticate with passcode or biometric to use the key

    // Process the identity (e.g., add to token configuration)
    AddItem(identity);

    // Clean up
    CFRelease(identity);
} else {
    NSLog(@"Failed to load identity from PKCS12 file");
}

// Internal implementation creates access control with:
// - kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly (device-bound)
// - kSecAccessControlUserPresence (requires authentication)
```

--------------------------------

### Add Token Configuration

Source: https://github.com/purebred/ctkprovider/blob/main/README.md

Adds a token configuration to the token driver using a specified label. The label is typically a SHA256 hash of the certificate.

```objective-c
    TKTokenConfiguration* tokenConfiguration = [tokenDriverConfiguration addTokenConfigurationForTokenInstanceID:label];
```

--------------------------------

### Implement decryptData for TKTokenSessionDelegate

Source: https://context7.com/purebred/ctkprovider/llms.txt

Handles decryption of ciphertext using a private key associated with a token. Requires verification of the algorithm and retrieval of the SecKeyRef.

```objective-c
// TokenSession.m - TKTokenSessionDelegate implementation

- (NSData *)tokenSession:(TKTokenSession *)session
             decryptData:(NSData *)ciphertext
                usingKey:(TKTokenObjectID)keyObjectID
               algorithm:(TKTokenKeyAlgorithm *)algorithm
                   error:(NSError **)error
{
    // Verify algorithm is supported
    if (!IsAlgorithmSupported(algorithm)) {
        *error = [NSError errorWithDomain:TKErrorDomain
                                    code:TKErrorCodeBadParameter
                                userInfo:@{NSLocalizedDescriptionKey:
                                          @"Unsupported algorithm"}];
        return nil;
    }

    // Retrieve private key (with caching for Mail.app performance)
    SecKeyRef privateKeyRef = getKey(keyObjectID);
    if (privateKeyRef == nil) {
        privateKeyRef = GetPrivateKeyRef(keyObjectID);
        if (!privateKeyRef) {
            *error = [NSError errorWithDomain:TKErrorDomain
                                        code:TKErrorCodeObjectNotFound
                                    userInfo:@{NSLocalizedDescriptionKey:
                                              @"Failed to load private key"}];
            return nil;
        }
        putKey(keyObjectID, privateKeyRef);
    }

    // Convert algorithm and verify support
    SecKeyAlgorithm secAlgorithm = GetAlgorithmFromTKTokenKeyAlgorithm(algorithm);
    if (!SecKeyIsAlgorithmSupported(privateKeyRef, kSecKeyOperationTypeDecrypt, secAlgorithm)) {
        *error = [NSError errorWithDomain:TKErrorDomain
                                    code:TKErrorCodeBadParameter
                                userInfo:@{NSLocalizedDescriptionKey:
                                          @"Unsupported algorithm"}];
        return nil;
    }

    // Perform decryption
    CFErrorRef cfError;
    CFDataRef plaintext = SecKeyCreateDecryptedData(privateKeyRef,
                                                    secAlgorithm,
                                                    (CFDataRef)ciphertext,
                                                    &cfError);

    if (!plaintext) {
        CFRelease(cfError);
        return nil;
    }

    return (__bridge_transfer NSData*)plaintext;
}
```

--------------------------------

### Implement supportsOperation for TKTokenSessionDelegate

Source: https://context7.com/purebred/ctkprovider/llms.txt

Validates if the token supports specific RSA signing or decryption operations based on key existence.

```objective-c
// TokenSession.m - TKTokenSessionDelegate implementation

- (BOOL)tokenSession:(TKTokenSession *)session
   supportsOperation:(TKTokenOperation)operation
            usingKey:(TKTokenObjectID)keyObjectID
           algorithm:(TKTokenKeyAlgorithm *)algorithm
{
    // Only sign and decrypt operations are supported
    if (TKTokenOperationSignData != operation &&
        TKTokenOperationDecryptData != operation) {
        return NO;
    }

    // Verify algorithm is a supported RSA algorithm
    if (!IsAlgorithmSupported(algorithm)) {
        return NO;
    }

    // Verify certificate/key exists in keychain
    SecCertificateRef certificateRef = GetCertificateRef(keyObjectID);
    if (!certificateRef) {
        return NO;
    }
    CFRelease(certificateRef);

    return YES;
}
```

--------------------------------

### supportsOperation - Check Algorithm and Operation Support

Source: https://context7.com/purebred/ctkprovider/llms.txt

Determines whether the token supports a specific cryptographic operation with a given algorithm. Returns YES for RSA sign and decrypt operations when a matching certificate exists.

```APIDOC
## supportsOperation

### Description
Determines whether the token supports a specific cryptographic operation with a given algorithm. Returns YES for RSA sign and decrypt operations when a matching certificate exists.

### Parameters
- **session** (TKTokenSession) - The current token session.
- **operation** (TKTokenOperation) - The operation to check (e.g., TKTokenOperationSignData, TKTokenOperationDecryptData).
- **keyObjectID** (TKTokenObjectID) - The identifier for the key.
- **algorithm** (TKTokenKeyAlgorithm) - The algorithm to validate.

### Response
- **Returns** (BOOL) - YES if the operation and algorithm are supported and the certificate exists, otherwise NO.
```

--------------------------------

### Remove All Tokens Objective-C

Source: https://context7.com/purebred/ctkprovider/llms.txt

Removes all token configurations and resets the keychain. This iterates through driver and token configurations to remove them, then clears keychain items.

```objective-c
// ViewController.m

// Remove all token configurations and reset keychain
- (IBAction)onRemoveAllTokens:(id)sender {
    NSDictionary* driverConfigs = [TKTokenDriverConfiguration driverConfigurations];

    for (id key in driverConfigs) {
        TKTokenDriverConfiguration* driverConfig = driverConfigs[key];
        NSDictionary* tokenConfigs = [driverConfig tokenConfigurations];

        for (id tokenKey in tokenConfigs) {
            TKTokenConfiguration* tokenConfig = tokenConfigs[tokenKey];
            [driverConfig removeTokenConfigurationForTokenInstanceID:
                [tokenConfig instanceID]];
        }
    }

    // Clear keychain items
    [self resetKeychain];
}
```

--------------------------------

### signData - Create Digital Signatures

Source: https://context7.com/purebred/ctkprovider/llms.txt

Signs data using the private key associated with the token. Supports multiple RSA signature algorithms including PKCS1v15 and PSS with SHA-1 through SHA-512.

```APIDOC
## signData

### Description
Signs data using the private key associated with the token. Supports multiple RSA signature algorithms.

### Parameters
- **session** (TKTokenSession) - The current token session.
- **dataToSign** (NSData) - The data to be signed.
- **keyObjectID** (TKTokenObjectID) - The identifier for the private key.
- **algorithm** (TKTokenKeyAlgorithm) - The RSA signature algorithm to use.
- **error** (NSError**) - Pointer to an error object if the operation fails.

### Response
- **Returns** (NSData) - The generated digital signature on success, or nil if an error occurs.
```

--------------------------------

### Add Signature Token Objective-C

Source: https://context7.com/purebred/ctkprovider/llms.txt

Adds a signature token from a bundled PKCS12 file. Ensure the identity and password are correct. This action triggers a UI confirmation.

```objective-c
// ViewController.m

// Add a signature token from bundled PKCS12 file
- (IBAction)onAddSignatureToken:(id)sender {
    SecIdentityRef identity = GetIdentity(@"signature", @"password");
    if (identity) {
        AddItem(identity);
        CFRelease(identity);

        // Show confirmation
        UIAlertController* alert = [UIAlertController
            alertControllerWithTitle:@"Added"
            message:@"Added signature token."
            preferredStyle:UIAlertControllerStyleAlert];
        [self presentViewController:alert animated:YES completion:nil];
    }
}
```

--------------------------------

### Register Token with Crypto Token Kit

Source: https://context7.com/purebred/ctkprovider/llms.txt

Adds a token configuration to the Persistent Token Extension using a SecIdentityRef. This makes the key available to system and third-party apps for operations like digital signatures and data decryption. The token is labeled with a SHA256 hash of the certificate.

```Objective-C
#import "CtkProviderUtils.h"
#import <CryptoTokenKit/CryptoTokenKit.h>

// First, obtain an identity from a PKCS12 file
SecIdentityRef identity = GetIdentity(@"authentication", @"password");

if (identity != nil) {
    // Add the identity as a token configuration
    // This makes the key available to system apps (Mail, Safari) and third-party apps
    AddItem(identity);

    // The token is now registered with the system
    // Other apps can discover and use this key for:
    // - Digital signatures
    // - Data decryption
    // - Client authentication

    CFRelease(identity);
}

// AddItem internally:
// 1. Extracts certificate from identity
// 2. Generates SHA256 hash of certificate for labeling
// 3. Gets TKTokenDriverConfiguration for the extension
// 4. Creates TKTokenConfiguration with the label as instanceID
// 5. Creates TKTokenKeychainCertificate and TKTokenKeychainKey
// 6. Assigns keychain items to token configuration
```

--------------------------------

### Validate RSA Algorithm Support (Objective-C)

Source: https://context7.com/purebred/ctkprovider/llms.txt

Checks if a TKTokenKeyAlgorithm is one of the supported RSA algorithms for signature or encryption. Returns false for EC and other unsupported types. Used to ensure compatibility before cryptographic operations.

```Objective-C
// TokenUtils.m

bool IsAlgorithmSupported(TKTokenKeyAlgorithm* algorithm)
{
    // RSA Signature algorithms (PKCS1v15 and PSS)
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureRaw]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15Raw]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA1]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA384]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA512]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureDigestPSSSHA256]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSASignatureMessagePSSSHA256]) return true;

    // RSA Encryption algorithms (PKCS1, OAEP, AESGCM)
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionRaw]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionPKCS1]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionOAEPSHA1]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionOAEPSHA256]) return true;
    if ([algorithm isAlgorithm:kSecKeyAlgorithmRSAEncryptionOAEPSHA256AESGCM]) return true;
    // ... additional algorithms supported

    return false;  // EC and other algorithms not supported
}

// Example usage in supportsOperation:
// if (!IsAlgorithmSupported(algorithm)) {
//     NSLog(@"Unsupported algorithm: %@", algorithm);
//     return NO;
// }
```

--------------------------------

### Generate Hexadecimal String from Byte Buffer

Source: https://context7.com/purebred/ctkprovider/llms.txt

Converts binary data from a byte buffer into its hexadecimal string representation. This utility is commonly used for generating unique token labels from certificate hashes.

```Objective-C
#import "CtkProviderUtils.h"
#include <CommonCrypto/CommonDigest.h>

// Convert arbitrary byte buffer to hex string
const unsigned char buffer[] = {0xDE, 0xAD, 0xBE, 0xEF};
NSString* hexString = GetAsHex(buffer, 4);
// Result: @"DEADBEEF"

// For certificate labeling, the implementation uses SHA256:
// NSData* certificateData = (__bridge_transfer NSData*)SecCertificateCopyData(certificateRef);
// unsigned char result[CC_SHA256_DIGEST_LENGTH];
// CC_SHA256([certificateData bytes], (CC_LONG)[certificateData length], result);
// NSString* label = GetAsHex(result, CC_SHA256_DIGEST_LENGTH);
// Result: 64-character hex string uniquely identifying the certificate
```

--------------------------------

### Retrieve Private Key Reference from Keychain

Source: https://context7.com/purebred/ctkprovider/llms.txt

Searches the iOS keychain for a private key by its label. Returns a SecKeyRef that the caller must release using CFRelease. Ensure the label accurately matches the key in the keychain.

```objective-c
// TokenUtils.m

SecKeyRef GetPrivateKeyRef(NSString* label)
{
    NSMutableDictionary* query = [[NSMutableDictionary alloc] init];

    // Configure keychain query
    [query setObject:(id)kSecClassKey forKey:(id)kSecClass];
    [query setObject:(id)kCFBooleanTrue forKey:(id)kSecReturnRef];
    [query setObject:(id)kCFBooleanTrue forKey:(id)kSecReturnData];
    [query setObject:@"Authenticate to use private key"
              forKey:(id)kSecUseOperationPrompt];
    [query setObject:label forKey:(id)kSecAttrLabel];

    CFTypeRef items = nil;
    OSStatus result = SecItemCopyMatching((CFDictionaryRef)query, &items);

    if (result == errSecSuccess) {
        CFDictionaryRef dict = (CFDictionaryRef)items;
        SecKeyRef key = (SecKeyRef)CFDictionaryGetValue(dict, kSecValueRef);
        CFRetain(key);
        CFRelease(items);
        return key;  // Caller must CFRelease
    }

    return nil;
}

// Usage in token session:
// SecKeyRef key = GetPrivateKeyRef(keyObjectID);
// if (key) {
//     // Use key for signing or decryption
//     CFRelease(key);
// }

```

--------------------------------

### Retrieve Certificate Reference from Keychain

Source: https://context7.com/purebred/ctkprovider/llms.txt

Searches the iOS keychain for a certificate by its label. Returns a SecCertificateRef that the caller must release using CFRelease. This is useful for verifying key existence before cryptographic operations.

```objective-c
// TokenUtils.m

SecCertificateRef GetCertificateRef(NSString* label)
{
    NSMutableDictionary* query = [[NSMutableDictionary alloc] init];

    // Configure keychain query for certificate
    [query setObject:(id)kSecClassCertificate forKey:(id)kSecClass];
    [query setObject:(id)kCFBooleanTrue forKey:(id)kSecReturnRef];
    [query setObject:label forKey:(id)kSecAttrLabel];
    [query setObject:(id)kSecMatchLimitOne forKey:(id)kSecMatchItemList];

    SecCertificateRef certificateRef;
    OSStatus result = SecItemCopyMatching((CFDictionaryRef)query,
                                          (CFTypeRef*)&certificateRef);

    if (result == errSecSuccess) {
        return certificateRef;  // Caller must CFRelease
    }

    return nil;
}

// Used to verify key existence before operations:
// SecCertificateRef cert = GetCertificateRef(keyObjectID);
// if (cert) {
//     // Certificate exists, corresponding key should also exist
//     CFRelease(cert);
//     return YES;  // Operation supported
// }

```

--------------------------------

### Decrypt Data

Source: https://context7.com/purebred/ctkprovider/llms.txt

Decrypts ciphertext using the private key associated with the token. Supports various RSA and AES-GCM encryption algorithms.

```APIDOC
## decryptData - Decrypt Encrypted Content

### Description
Decrypts ciphertext using the private key associated with the token. Supports RSA encryption algorithms including PKCS1, OAEP with various hash functions, and AESGCM variants.

### Method
Objective-C (TKTokenSessionDelegate)

### Endpoint
N/A (Method within a delegate)

### Parameters
#### Method Parameters
- **session** (TKTokenSession *) - The token session object.
- **ciphertext** (NSData *) - The encrypted data to decrypt.
- **keyObjectID** (TKTokenObjectID) - The object ID of the private key to use for decryption.
- **algorithm** (TKTokenKeyAlgorithm *) - The encryption algorithm to use.
- **error** (NSError **) - A pointer to an NSError object that will be set if an error occurs.

### Response
#### Success Response
- **NSData *** - The decrypted plaintext data.

#### Error Response
- **nil** - If decryption fails, an NSError object will be returned via the error parameter.

### Example System Usage (Mail.app S/MIME decryption):
1. Encrypted email received, Mail.app identifies recipient key.
2. Token discovered via keychain search.
3. User authenticates via biometric/passcode.
4. decryptData called with encrypted session key.
5. Decrypted session key used to decrypt email body.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.