Chilkat.ScMinidriver Class Overview

Chilkat.ScMinidriver provides access to smart cards through the card minidriver model. It can acquire a card context, authenticate PINs, inspect card properties, list and retrieve certificates, generate or import keys into card key containers, sign data on the card, manage card files, and link certificates for signing in other Chilkat classes.

What the Class Is Used For

Use Chilkat.ScMinidriver when an application needs to work with a smart card through the Base CSP/KSP and the card minidriver interface. The class focuses on card context management, key containers, certificate access, PIN authentication, signing, and card file operations.

Acquire Smart Card Context Connect to a card in a named reader and obtain basic card information such as the ATR and card name.
PIN Authentication Authenticate, deauthenticate, change PINs, and authenticate using either normal text PINs or hex-encoded PIN values.
Certificates and Keys Find, list, import, retrieve, or delete certificates and manage signature or key-exchange keys in card containers.
On-Card Signing Sign data using RSA or ECC keys stored on the smart card, while private keys remain on the card.
Reader discovery: Reader names used with AcquireContext can be discovered with SCard.ListReaders or SCard.FindSmartcards.

Typical Workflow

  1. Use SCard to discover smart card readers and choose the reader containing the target card.
  2. Call AcquireContext(readerName) to initialize communication with the card.
  3. Inspect Atr, CardName, MaxContainers, or call GetCardProperties for detailed card information.
  4. Authenticate with PinAuthenticate or PinAuthenticateHex when a PIN is required.
  5. Retrieve or find certificates using GetCert, FindCert, or ListCerts.
  6. Generate, import, inspect, or delete keys and containers with GenerateKey, ImportKey, ImportCert, GetContainerKeys, or DeleteKeyContainer.
  7. Sign data with SignData, or use a linked Cert in another Chilkat class for higher-level signing operations.
  8. Call PinDeauthenticate when needed, and DeleteContext when finished with the card.

Core Concepts

Concept Meaning Important Members
Card Context A context represents active communication with the card in a reader. Most operations require that a context has first been acquired. AcquireContext, DeleteContext, Atr, CardName
Key Container A card has a limited number of key containers. Each container can potentially hold one signature key and one key exchange key. MaxContainers, GetContainerKeys, GenerateKey, DeleteKeyContainer
Key Spec A key spec selects which key location inside a container is being used: signature or key exchange. sig, kex, any
Linked Certificate Certificates retrieved from the card can be internally linked to the ScMinidriver session so other Chilkat classes can sign on the card. FindCert, GetCert, Cert
PIN Identity PIN operations target a PIN ID, usually user, but also possibly admin or numeric IDs 3 through 7. PinAuthenticate, PinChange, PinDeauthenticate
Card File System Some card files can be enumerated, read, written, or deleted through directory and filename operations. EnumFiles, ReadFile, WriteFile, CardDeleteFile

Core Properties

Property Purpose Guidance
Atr Contains the ATR of the card in the reader. Set by AcquireContext. Cleared by DeleteContext.
CardName Contains the name of the card in the reader. Set by AcquireContext. Cleared by DeleteContext.
MaxContainers Maximum number of key containers available on the card. Containers are indexed from 0 to MaxContainers - 1.
RsaPaddingScheme RSA padding scheme used for RSA signing. Values are PKCS or PSS. Default is PSS.
RsaPaddingHash Hash algorithm used with the RSA padding scheme. Values are SHA1, SHA256, SHA384, or SHA512. Default is SHA256.
LastErrorText Detailed information about the last method call or property access. Check after failures or unexpected behavior.
UncommonOptions Catch-all property for uncommon or specialized options. Defaults to the empty string and should usually remain empty.

Context and Card Information

Task Method Notes
Start communication with a card AcquireContext Initializes communication with the card inserted in the specified reader. On success, Atr and CardName are set.
End communication with a card DeleteContext Reverses AcquireContext, severs communication between the Base CSP/KSP and the card minidriver, and clears Atr and CardName.
Get all card properties GetCardProperties Returns card properties in a JsonObject.
View CSP container map GetCspContainerMap Returns the contents of the CSP container map file, giving an overview of key containers and certificates from the CSP’s point of view.
Context required: Most methods require a successfully acquired card context. If a method returns an unexpected failure, first verify that AcquireContext succeeded and check LastErrorText.

PIN Authentication

Task Method Return Value / Behavior
Authenticate with a PIN PinAuthenticate Returns 0 for success. On failure, a positive value indicates attempts remaining before lockout. -1 means the PIN is already blocked, and -2 means another failure occurred, such as no context acquired.
Authenticate with a hex-encoded PIN PinAuthenticateHex Same as PinAuthenticate, but the PIN is supplied as hex. For example, 01020304 represents bytes 0x01 0x02 0x03 0x04.
Change a PIN PinChange Returns 0 for success. On failure, a positive value indicates attempts remaining, -1 means already blocked, and -2 indicates another failure.
End PIN authentication PinDeauthenticate Reverses a previous PIN authentication without resetting the card.
PIN lockout caution: Failed PIN attempts can reduce the number of attempts remaining before the PIN is blocked. Always handle nonzero return values carefully.

Certificates on the Smart Card

Task Method Guidance
Get a certificate by container and key spec GetCert Retrieves the certificate at a specified container index and key location. Use sig, kex, or any. A container index of -1 chooses the first container with a certificate.
Find a certificate by identity data FindCert Finds by subjectDN, subjectDN_withTags, subjectCN, serial, or serial:issuerCN.
List certificates ListCerts Returns selected certificate information in a StringTable. The requested part can be subjectDN, subjectDN_withTags, subjectCN, serial, or serial:issuerCN.
Import a certificate and private key ImportCert Imports a certificate whose private key is accessible, such as a certificate loaded from PFX/P12 or from a Windows certificate store where the private key exists and can be exported.
Delete a certificate DeleteCert Deletes a certificate from the smart card and optionally deletes its associated private key when delPrivKey is true.
Signing integration: A certificate returned by GetCert or FindCert is internally linked to the ScMinidriver session so it can be used for signing on the smart card by Chilkat classes such as XmlDSigGen, Pdf, Crypt2, Mime, and MailMan.

Key Containers and Key Management

A smart card has up to MaxContainers key containers. Each container can hold a signature key and a key exchange key. The keySpec argument identifies which key location to use.

Task Method Important Details
Inspect keys in a container GetContainerKeys Returns the signature public key in sigKey if present, and the key exchange public key in kexKey if present.
Generate a key on the card GenerateKey Creates the key container if needed, otherwise replaces the selected key. Key spec is sig or kex. Key type is rsa or ecc.
Import a private key ImportKey Imports a private key into the selected signature or key exchange location. Creates the container if it does not exist, otherwise replaces the selected key.
Import a certificate with private key ImportCert Imports a certificate and its private key into the selected container and key location.
Delete a key container DeleteKeyContainer Deletes both the signature and key exchange keys that may exist in the specified container.
Key Setting Allowed Values Meaning
keySpec sig, kex, any Selects the signature key, key exchange key, or either available key when retrieving certificates.
keyType rsa, ecc Selects RSA or ECC when generating a key.
RSA key size 1024, 2048, 4096, etc. RSA key size in bits. 2048 is a typical value.
ECC key size 256, 384, 521 ECC curve size for generated ECC keys.
pinId user, 3 through 7 Identifies the PIN to associate with generated or imported keys. It is typically user.
Replacement behavior: GenerateKey and ImportKey can replace an existing key in the selected key container and key location. Confirm the container index and key spec before using them.

Signing Data on the Smart Card

SignData signs data using a key stored in a selected key container. The key type determines whether the signature is RSA or ECC. For RSA keys, RsaPaddingScheme and RsaPaddingHash control RSA padding behavior.

Setting Values Purpose
containerIndex 0 to MaxContainers - 1 Selects the key container containing the signing key.
keySpec sig or kex Selects the signature key or key exchange key inside the container.
hashDataAlg sha1, sha256, sha384, sha512, or none If not none, Chilkat hashes the supplied data before signing.
RsaPaddingScheme PKCS or PSS Applies when the signing key is RSA. Default is PSS.
RsaPaddingHash SHA1, SHA256, SHA384, or SHA512 Hash algorithm used with RSA padding. Default is SHA256.
Hashing note: Use hashDataAlg = "none" when the input data is already in the exact form expected for the card’s signing operation. Otherwise, specify a hash algorithm such as sha256.

Card File Operations

Task Method Notes
List files in a directory EnumFiles Returns filenames in a StringTable. Pass the empty string for the root directory.
Read a card file ReadFile Reads the specified file into a BinData object. The directory name can be empty for root.
Write a card file WriteFile Writes the entire contents of a BinData object to the specified file.
Delete a card file CardDeleteFile Deletes a file from the specified directory, or from root when the directory name is empty.
File-system caution: WriteFile and CardDeleteFile modify data stored on the smart card. Use them only when the card file layout and permissions are understood.

Certificate Search Values

certPart Value Used By Meaning
subjectDN FindCert, ListCerts Match or return the subject distinguished name.
subjectDN_withTags FindCert, ListCerts Match or return the subject distinguished name with tags.
subjectCN FindCert, ListCerts Match or return the subject common name.
serial FindCert, ListCerts Match or return the certificate serial number.
serial:issuerCN FindCert, ListCerts Match or return the certificate serial number combined with the issuer common name.

Destructive Operations

Operation Method Risk
Delete card file CardDeleteFile Removes the specified file from the smart card.
Delete certificate DeleteCert Removes a certificate and can optionally delete its associated private key.
Delete key container DeleteKeyContainer Deletes both signature and key exchange keys in the specified container.
Replace generated key GenerateKey Creates the container if needed, otherwise replaces the selected key.
Replace imported key ImportKey Creates the container if needed, otherwise replaces the selected key.
Before deleting or replacing keys: Use GetCspContainerMap, GetContainerKeys, ListCerts, and GetCert to verify what is currently stored on the card.

Diagnostics and Troubleshooting

Problem Area Member What to Check
General method failure LastErrorText Provides detailed information about the last method call or property access.
Card context not available AcquireContext, Atr, CardName Confirm that the reader name is correct and that a card is present.
PIN authentication fails PinAuthenticate, PinAuthenticateHex Interpret the return value carefully: success, attempts remaining, blocked, or another failure.
Certificate not found ListCerts, FindCert, GetCert List available certificate fields first, then search by the most reliable identifier such as serial number or serial plus issuer CN.
Unexpected signing format SignData, RsaPaddingScheme, RsaPaddingHash, hashDataAlg Verify whether the input should be hashed by Chilkat and whether RSA padding should be PKCS or PSS.
Container confusion MaxContainers, GetCspContainerMap, GetContainerKeys Inspect the container map and public keys before importing, generating, or deleting container contents.

Best Practices

Recommendation Reason
Always call AcquireContext first. It initializes communication with the card and populates Atr and CardName.
Use GetCardProperties and GetCspContainerMap before modifying the card. These methods help you understand what the card contains before importing, generating, replacing, or deleting anything.
Use ListCerts before FindCert when search criteria are uncertain. Listing available certificate fields helps choose the correct match value.
Prefer stable certificate identifiers for lookup. Serial number or serial plus issuer CN is usually less ambiguous than subject common name.
Confirm container index and keySpec before key operations. Key generation and import can replace existing keys in the selected container and location.
Handle PIN return values explicitly. A failed PIN operation may indicate attempts remaining, a blocked PIN, or another failure condition.
Use PinDeauthenticate and DeleteContext when finished. This cleanly ends PIN authentication and severs communication with the card.
Check LastErrorText after failures. It provides the most useful diagnostic detail for reader, context, PIN, certificate, key, signing, and file-operation problems.

Summary

Chilkat.ScMinidriver is a smart-card integration class for applications that need card minidriver access to certificates, key containers, PIN authentication, card files, and on-card signing. It can retrieve and link smart-card certificates for use in other Chilkat signing classes, generate or import RSA/ECC keys, sign data directly, inspect card/container state, and manage selected card files and certificates.

Treat card-modifying operations with care. Before deleting, generating, importing, or replacing keys, inspect the card with GetCardProperties, GetCspContainerMap, ListCerts, and GetContainerKeys.