Chilkat.CertStore Class Overview

Chilkat.CertStore represents a certificate store that can be opened, searched, iterated, modified, or populated from certificate files. It can work with Windows certificate stores, Apple Keychain, file-based stores, registry stores, memory stores, PFX/P12 files, PEM files, and certificates available from HSM devices such as smart cards and USB tokens.

What the Class Is Used For

Use Chilkat.CertStore when an application needs to access a collection of certificates, search for a certificate by criteria, iterate through certificates, add or remove certificates where supported, or inspect the contents of a PFX/P12 or PEM certificate source without necessarily importing it into the operating system certificate store.

Open System Stores Access Windows certificate stores, the Windows Current User / Local Machine Personal stores, Outlook’s Other People store, and Apple Keychain.
Load File-Based Sources Load certificates from PEM files, PEM strings, PFX/P12 files, or PFX/P12 bytes.
Find and Iterate Certificates Search with JSON criteria using FindCert or loop from 0 to NumCertificates - 1 with GetCert.
Use Smart Cards and Tokens Load certificates from connected HSM devices such as smart cards and USB tokens with OpenSmartcard.

Typical Workflow

  1. Create a CertStore object.
  2. Open or load a certificate source, such as OpenCurrentUserStore, OpenWindowsStore, OpenSmartcard, LoadPfxFile, or LoadPemFile.
  3. Check NumCertificates to see how many certificates are available.
  4. Retrieve a certificate by index with GetCert, or search with FindCert.
  5. If the store supports updates and was opened writable, add or remove certificates with AddCertificate or RemoveCertificate.
  6. Call CloseCertStore when finished to close open stores and clear the object.
  7. Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept Meaning Important Members
Certificate Store A container holding one or more certificates. It may be backed by the operating system, a file, the registry, memory, a PFX/P12, a PEM source, or an HSM device. Open*, Load*, NumCertificates
Search Result Certificate A certificate found by search criteria and loaded into a supplied Cert object. FindCert
Indexed Certificate Access Certificates can be retrieved one at a time by zero-based index. NumCertificates, GetCert
Read-Only Store Access Some open methods accept a read-only flag to prevent permission errors when only fetching certificates. OpenCurrentUserStore, OpenLocalSystemStore, OpenWindowsStore
Private Key Access Some certificates may have associated private keys. On Windows, access to a private key can trigger OS security prompts depending on how the key was installed. AvoidWindowsPkAccess, SmartCardPin
Smart Card / HSM Store Certificates can be loaded from connected HSM devices such as smart cards and USB tokens. OpenSmartcard

Core Properties

Property Purpose Guidance
NumCertificates Number of certificates currently held in the store object. Use with GetCert to iterate through the loaded certificates.
AvoidWindowsPkAccess Prevents returned certificates from attempting to access associated private keys on Windows. Useful when a certificate was installed with high-security settings and private-key access would trigger a Windows security warning dialog. Default is false.
SmartCardPin PIN value for a certificate/private key stored on a smart card. Use carefully when multiple HSM devices are connected. Avoid setting this property unless all connected devices share the same PIN.
UncommonOptions Catch-all property for uncommon needs. Defaults to the empty string and should typically remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Opening Existing Certificate Stores

Method Platform Store Opened Read-Only Behavior
OpenCurrentUserStore Windows; macOS/iOS starting v10.0.0 Windows: Current-User\Personal. macOS/iOS: Apple Keychain. On Windows, readOnly = true opens read-only. On macOS/iOS, readOnly is ignored.
OpenLocalSystemStore Windows only Registry-based Local-Computer\Personal store. Use readOnly = true when only fetching certificates.
OpenOutlookStore Windows only Registry-based Current-User\Other People store, used by Microsoft Outlook. Use readOnly = true when only fetching certificates.
OpenWindowsStore Windows only Named Windows certificate store in CurrentUser or LocalMachine. Use readOnly = true to avoid write-permission requirements.
OpenRegistryStore Windows only Arbitrary registry-based certificate store. Use readOnly = true to avoid write-permission requirements.
OpenFileStore Windows only File-based certificate store. Opens read-only or writable according to the readOnly argument.
OpenSmartcard Windows, macOS, iOS, Linux; Android not yet supported Certificates from connected HSM devices such as smart cards and USB tokens. The csp argument is ignored; pass an empty string.
Read-only tip: On Windows, set readOnly = true when only searching or fetching certificates. This can prevent permission-denied errors caused by opening the store with write access.

Windows Store Names for OpenWindowsStore

Store Name Meaning
AddressBook Certificate store for other users.
AuthRoot Certificate store for third-party certification authorities.
CertificationAuthority Certificate store for intermediate certification authorities.
Disallowed Certificate store for revoked certificates.
My Certificate store for personal certificates.
Root Certificate store for trusted root certification authorities.
TrustedPeople Certificate store for directly trusted people and resources.
TrustedPublisher Certificate store for directly trusted publishers.
Store location values: For OpenWindowsStore and registry-based methods, the location/root value must be CurrentUser or LocalMachine.

Creating New Stores

Method Platform Store Type Notes
CreateMemoryStore Windows only In-memory certificate store Temporary runtime-only store. It is not backed by a file or persistent storage and is lost when the application ends unless saved elsewhere.
CreateFileStore Windows only File-based certificate store Creates a new empty certificate store backed by a file. Certificates can be saved with AddCertificate.
CreateRegistryStore Windows only Registry-based certificate store Creates a new empty certificate store in the Windows registry. The registry root is CurrentUser or LocalMachine.

Loading PEM and PFX/P12 Sources

Method Input Purpose Important Notes
LoadPemFile PEM file path Loads certificates contained within a PEM formatted file. The certificates become available in the store object for searching or iteration.
LoadPemStr PEM string Loads certificates contained within an in-memory PEM formatted string. Useful when PEM text is already in memory.
LoadPfxFile PFX/P12 file path and password Loads a PFX/P12 file into the CertStore object. This does not import certificates into Windows certificate stores. It loads the PFX/P12 for exploration, searching, or iteration.
LoadPfxBd BinData containing PFX/P12 bytes and password Loads PFX/P12 bytes from memory. Useful when PFX/P12 data is already held in a BinData object.
PFX import distinction: LoadPfxFile and LoadPfxBd load PFX/P12 contents into this object for searching or inspection. They do not import certificates into the Windows certificate stores.

Finding and Retrieving Certificates

Method Purpose Important Details
FindCert Searches for a certificate using criteria supplied in a JsonObject. If multiple criteria are provided, Chilkat searches each one sequentially and returns the first match. Preference is given to non-expired certificates when both expired and non-expired matches exist.
GetCert Loads the Nth certificate into a supplied Cert object. Indexing begins at 0. Use with NumCertificates.
Iteration pattern: To examine all certificates, loop from 0 to NumCertificates - 1 and call GetCert for each index.

Adding and Removing Certificates

Method Platform Behavior Important Notes
AddCertificate Windows; macOS/iOS starting v10.0.0 Windows: updates or adds the certificate to the open Windows certificate store. macOS/iOS: adds the certificate, including any private keys and intermediate CA certificates, to Apple Keychain. On Windows, this imports the certificate without the private key. To import a certificate with a private key on Windows, use Chilkat.Pfx.ImportToWindows.
RemoveCertificate Windows only Removes the passed certificate from the open store. The Cert object passed to this method can no longer be used after it is removed.
CloseCertStore All applicable platforms Closes any open certificate stores, removes all certificates from the object, and resets NumCertificates to 0. Call when finished with the store.

Smart Card and HSM Access

Member Purpose Guidance
OpenSmartcard Identifies connected HSM devices such as smart cards and USB tokens, then loads certificates from each device. Enhanced in Chilkat v10.1.2. Compatible with Windows, macOS, iOS, and Linux. Android is not yet supported. The csp argument is no longer used and is ignored; pass an empty string.
SmartCardPin Supplies a PIN for certificates/private keys stored on a smart card. Avoid setting this when multiple HSM devices are connected unless every device uses the same PIN.
Multiple device caution: If multiple HSM devices are connected and SmartCardPin is set, Chilkat will attempt to use that PIN for each device. This can cause issues when devices use different PINs.

Platform Availability Summary

Feature Area Windows macOS / iOS Linux Android
Current user store / Apple Keychain OpenCurrentUserStore opens Current-User\Personal. Starting v10.0.0, OpenCurrentUserStore opens Apple Keychain. Not documented for this method. Not documented for this method.
Windows certificate stores Supported through OpenWindowsStore, OpenLocalSystemStore, OpenOutlookStore, and registry/file store methods. Not applicable. Not applicable. Not applicable.
PEM and PFX/P12 loading Supported. Supported. Supported. Supported unless otherwise limited by environment.
Smart card / HSM certificate loading Supported. Supported. Supported. Not yet supported.
Create file, memory, registry stores Supported. Not documented as available. Not documented as available. Not documented as available.

Method Summary by Category

Category Methods Purpose
Open stores OpenCurrentUserStore, OpenLocalSystemStore, OpenOutlookStore, OpenWindowsStore, OpenRegistryStore, OpenFileStore, OpenSmartcard Open system, registry, file-based, Outlook, Apple Keychain, or smart card / HSM-backed certificate stores.
Create stores CreateMemoryStore, CreateFileStore, CreateRegistryStore Create new Windows memory, file-based, or registry-backed certificate stores.
Load certificate sources LoadPemFile, LoadPemStr, LoadPfxFile, LoadPfxBd Load certificates from PEM or PFX/P12 sources into the CertStore object.
Find and retrieve FindCert, GetCert Search for a certificate by JSON criteria or retrieve certificates by index.
Modify store AddCertificate, RemoveCertificate Add certificates to an open store, or remove certificates where supported.
Close and clear CloseCertStore Close open stores, remove certificates from the object, and reset the count.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Permission denied opening a Windows store OpenCurrentUserStore, OpenLocalSystemStore, OpenWindowsStore Open the store with readOnly = true when only fetching certificates.
Windows security dialog appears when retrieving certificates AvoidWindowsPkAccess Set to true to avoid trying to access associated private keys when returning certificates.
PFX/P12 was loaded but not visible in Windows certificate store LoadPfxFile, LoadPfxBd These methods load the PFX/P12 into the CertStore object for inspection. They do not import into Windows certificate stores.
Certificate was added on Windows but private key is missing AddCertificate On Windows, AddCertificate imports the certificate without the private key. Use Chilkat.Pfx.ImportToWindows to import a certificate with a private key.
Smart card access behaves unexpectedly with multiple devices OpenSmartcard, SmartCardPin Avoid setting SmartCardPin unless all connected HSM devices share the same PIN.
No certificates are found NumCertificates, FindCert, GetCert Confirm the intended store or file source was opened or loaded successfully, then check the certificate count and search criteria.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected store opening, loading, searching, adding, removing, or smart card operations.

Common Pitfalls

Pitfall Better Approach
Opening a Windows store read-write when only reading certificates. Use readOnly = true to avoid unnecessary permission requirements.
Assuming LoadPfxFile imports into Windows. Treat LoadPfxFile as a way to inspect/search PFX contents. Use Chilkat.Pfx.ImportToWindows for Windows import with a private key.
Using AddCertificate on Windows and expecting the private key to be imported. On Windows, AddCertificate imports only the certificate, not the private key.
Passing a CSP name to OpenSmartcard. The csp argument is ignored. Pass an empty string.
Setting one SmartCardPin when multiple devices have different PINs. Avoid setting SmartCardPin unless all connected devices share the same PIN.
Continuing to use a Cert object after removing it from a Windows store. After RemoveCertificate, the passed certificate object can no longer be used.
Forgetting to close and clear the store object. Call CloseCertStore when finished to close open stores and reset the certificate list.

Best Practices

Recommendation Reason
Open stores read-only unless you need to modify them. This avoids permission problems and reduces the risk of accidental store changes.
Use AvoidWindowsPkAccess when private-key prompts are unwanted. It prevents certificate retrieval from triggering Windows private-key access dialogs.
Use FindCert for targeted lookup and GetCert for full enumeration. Search is convenient for known criteria, while index-based access is best for inspecting every certificate.
Check NumCertificates after opening or loading a store. It confirms that certificates were actually loaded into the object.
Use the correct import path for certificates with private keys. On Windows, use Chilkat.Pfx.ImportToWindows for certificates that need private-key import.
Pass an empty string to OpenSmartcard. The csp argument is no longer used and is ignored.
Check LastErrorText after failures. It provides useful diagnostic detail for store access, file loading, PFX/P12 loading, certificate search, store modification, and smart card operations.

Summary

Chilkat.CertStore is the Chilkat class for working with certificate collections from system stores, Apple Keychain, Windows file or registry stores, memory stores, PEM files, PFX/P12 files, and smart card / USB token devices. It supports opening, creating, loading, searching, iterating, adding, removing, and closing certificate stores, with platform-specific behavior for Windows and Apple Keychain.

The most important practical guidance is to open stores read-only when only fetching certificates, use FindCert or GetCert after verifying NumCertificates, distinguish PFX loading from operating-system import, avoid unwanted Windows private-key access prompts when needed, and use LastErrorText for diagnostics.