Chilkat.Cert Class Overview
Chilkat.Cert represents an X.509 digital certificate and provides methods for loading, inspecting, exporting, validating, chaining, and using certificates with private keys, smart cards, HSMs, cloud signing services, TLS, PKCS7/CMS signing, decryption, and certificate-based authentication.
What the Class Is Used For
Use Chilkat.Cert whenever an application needs to work with an X.509 certificate. The object can hold a public certificate alone, or a certificate associated with a private key from a PFX file, OS certificate store, smart card, USB token, HSM, PKCS#11 session, or cloud signing provider.
Load Certificates
Load from PEM, DER, Base64, files, PFX/P12, OS certificate stores, Apple
Keychain, smart cards, USB tokens, or HSM-backed sources.
Inspect Certificate Fields
Read subject, issuer, serial number, validity dates, thumbprints, SAN, key
usage, extended key usage, OCSP URL, and certificate extensions.
Work with Keys
Retrieve public keys, access private keys when available, associate a private
key, link to PKCS#11, or use remote cloud signing.
Validate and Export
Build certificate chains, verify signatures, check revocation, export to DER,
PEM, XML, PFX, or save as a certificate file.
Typical Workflow
- Load a certificate using a method such as LoadFromFile, LoadPem, LoadPfxFile, LoadByThumbprint, or LoadFromSmartcard.
- Inspect identity fields such as SubjectCN, SubjectDN, IssuerCN, IssuerDN, SerialNumber, and Sha1Thumbprint.
- Check validity and intended use with properties such as ValidFrom, ValidTo, Expired, ExtendedKeyUsage, and the For* usage properties.
- If trust validation is needed, call BuildCertChain or VerifySignature, and configure TrustedRoots or UseCertVault when additional trust anchors or intermediate certificates are needed.
- If a private key is required, check HasPrivateKey, retrieve it with GetPrivateKey, associate one with SetPrivateKey, or link to a smart card, HSM, or cloud signer.
- Export the certificate or certificate/private-key bundle using ExportCertPem, ExportCertDerFile, ExportCertXml, or ExportToPfxFile.
- If an operation fails or behaves unexpectedly, inspect LastErrorText for detailed diagnostic information.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Certificate Object | Holds an X.509 certificate and exposes its subject, issuer, validity, extensions, public key, and trust-related information. | SubjectDN, IssuerDN, CertVersion, SerialNumber |
| Certificate + Private Key | Some certificates have an associated private key, which is needed for signing, decryption, TLS client authentication, and other private-key operations. | HasPrivateKey, GetPrivateKey, SetPrivateKey, LoadPfxFile |
| Certificate Chain | A chain links the end-entity certificate to its issuer, intermediate CAs, and possibly a trusted root. | BuildCertChain, FindIssuer, GetIssuer, TrustedRoot |
| Trust Roots | Trust is determined by configured trusted roots, system CA roots, and certificates made available through TrustedRoots or certificate vaults. | TrustedRoot, UseCertVault, VerifySignature |
| Smart Card / HSM Certificate | A certificate can be loaded from a smart card, USB token, or HSM, while the private key remains on the secure device. | LoadFromSmartcard, SmartCardPin, SmartCardFailReason, LinkPkcs11 |
| Cloud Signing | A certificate can be configured so signing occurs remotely through a cloud signing provider instead of exporting or locally using the private key. | SetCloudSigner, UploadToCloud |
Loading Certificates
| Source | Methods | Notes |
|---|---|---|
| Certificate file | LoadFromFile | Loads from .cer, .crt, .p7b, or .pem. Format is detected from content, not only from the file extension. Does not load .pfx or .p12. |
| PEM text | LoadPem | Loads a certificate from a PEM string. |
| Base64 DER | LoadFromBase64, SetFromEncoded | Loads from Base64-encoded certificate data. |
| Bytes / BinData | LoadFromBinary, LoadFromBd | Accepts certificate data in formats such as binary DER, PEM, or Base64; Chilkat automatically detects the format. |
| PFX / P12 | LoadPfxFile, LoadPfxData, LoadPfxBd | Loads a certificate from a password-protected PFX/P12. If the PFX contains multiple certificates, the first certificate is loaded. |
| OS certificate stores / keychains | LoadByCommonName, LoadByEmailAddress, LoadByThumbprint, LoadByIssuerAndSerialNumber, LoadBySubjectOid | Searches Windows certificate stores or Apple Default/System Keychains, depending on platform. |
| Smart card, USB token, or HSM | LoadFromSmartcard | Searches connected secure devices and loads a matching certificate and associated private key if available. Set SmartCardPin first when required. |
| Completed async task | LoadTaskResult | Loads the certificate result from a completed asynchronous task. |
Format reminder:
LoadFromFile is for certificate files such as
CER/CRT/P7B/PEM. Use LoadPfxFile for PFX/P12 files
that may contain a private key.
Subject, Issuer, Identity, and Validity
| Information | Members | Purpose |
|---|---|---|
| Subject distinguished name | SubjectDN, SubjectCN, SubjectO, SubjectOU, SubjectE, SubjectC, SubjectS, SubjectL | Identifies the certificate subject, such as the person, organization, server, or entity named by the certificate. |
| Issuer distinguished name | IssuerDN, IssuerCN, IssuerO, IssuerOU, IssuerE, IssuerC, IssuerS, IssuerL | Identifies the certificate authority or issuer that signed the certificate. |
| Serial number | SerialNumber, SerialDecimal | Provides the certificate serial number in hexadecimal or decimal form. |
| Thumbprint | Sha1Thumbprint | SHA-1 hash of the certificate’s binary DER representation. |
| Subject alternative names | SubjectAlternativeName, Rfc822Name | Returns SAN data as XML, or RFC822/email names as a string. |
| Validity period | ValidFrom, ValidFromStr, ValidTo, ValidToStr, Expired | Shows when the certificate becomes valid, when it expires, and whether it or any certificate in its authority chain has expired. |
| Certificate type indicators | SelfSigned, IsRoot, CertVersion | Indicates whether the certificate is self-signed, root/self-issued, and whether it is X.509 version 1, 2, or 3. |
Usage, Key Usage, and Extended Key Usage
| Usage Information | Members | Meaning |
|---|---|---|
| Extended key usage string | ExtendedKeyUsage | Returns comma-separated keywords such as serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, and OCSPSigning. |
| Server authentication | ForServerAuthentication | Indicates whether the certificate can be used for TLS server authentication. |
| Client authentication | ForClientAuthentication | Indicates whether the certificate can be used for TLS client authentication. |
| Secure email | ForSecureEmail | Indicates whether the certificate can be used for secure email. |
| Code signing | ForCodeSigning | Indicates whether the certificate can be used for code signing. |
| Time stamping | ForTimeStamping | Indicates whether the certificate can be used for timestamping. |
| Intended key usage bitflags | IntendedKeyUsage | Contains X.509 key usage flags such as digital signature, non-repudiation, key encipherment, data encipherment, key agreement, certificate signing, CRL signing, and encipher-only. |
Practical check:
For TLS server use, check ForServerAuthentication.
For TLS client-certificate authentication, check
ForClientAuthentication. For S/MIME, check
ForSecureEmail.
Private Keys, Public Keys, and Signing Sources
| Need | Members | Guidance |
|---|---|---|
| Check whether a private key is available | HasPrivateKey | Returns true if the certificate has an associated private key available. |
| Access the private key | GetPrivateKey, GetPrivateKeyPem | Retrieves the private key if it is available and exportable or accessible. |
| Associate a private key | SetPrivateKey, SetPrivateKeyPem | Associates a private key with the certificate for signing or decryption. |
| Retrieve the public key | GetPublicKey, GetPubKeyDer | Extracts the public key as a PublicKey object or DER-encoded key data. |
| Determine key type | IsRsa, IsEcdsa | Indicates whether the certificate is RSA-based or ECDSA-based. |
| Avoid private-key access prompts on Windows | AvoidWindowsPkAccess | Prevents methods that return certificates from attempting private-key access, avoiding high-security Windows prompt dialogs. |
| Check whether Windows private key is exportable | PrivateKeyExportable | Indicates whether the private key was installed with settings that allow it to be re-exported. |
| Link to a PKCS#11 private key | LinkPkcs11 | Links the certificate to a private key on an HSM, smart card, token, or cloud HSM so signing occurs on the HSM. |
| Use a remote cloud signer | SetCloudSigner | Configures signing via supported cloud signing services such as AWS KMS, Azure Key Vault, or Aruba Remote Signing Service. |
Smart Cards, USB Tokens, and HSMs
LoadFromSmartcard can load a certificate and its associated private key from a connected USB token, smart card, or HSM. Chilkat searches connected devices and automatically chooses the appropriate communication method where possible.
| Feature | Members | Notes |
|---|---|---|
| PIN value | SmartCardPin | Set before calling LoadFromSmartcard when the device requires a PIN. |
| Suppress PIN dialog | SmartCardNoDialog | If true, no dialog is shown when the PIN is incorrect; the method fails instead. |
| Load from device | LoadFromSmartcard | Loads by criteria such as empty string, CN, subject DN, issuer/serial, serial number, thumbprint, policy OID, organization, country, locality, OU, state, or email. |
| Check PIN | CheckSmartCardPin | Returns 1 if correct, 0 if incorrect, and -1 if unable to check. |
| Failure reason | SmartCardFailReason | Distinguishes no token detected, PIN login failure, certificate not found, and other failures after LoadFromSmartcard. |
| Unload certificate / close session | Unload | Unloads the certificate and may close a PKCS#11 session when the certificate was loaded from a smart card. |
Common case:
Pass an empty string to LoadFromSmartcard when only
one smart card or token is connected and it contains one certificate with an
associated private key.
Certificate Chain, Trust, and Revocation
| Task | Members | Notes |
|---|---|---|
| Build the certificate chain | BuildCertChain | Builds a CertChain containing the certificate and available issuers up to the trusted root if possible. The method can return true even if the chain does not reach a root; inspect the chain’s ReachesRoot property. |
| Find issuer certificate | FindIssuer, GetIssuer | Returns the issuer certificate. For root or self-issued certificates, the returned certificate is a copy of the caller certificate. |
| Use additional certificate sources | UseCertVault | Adds an XML certificate vault to the internal list of sources for chain building and signature verification. |
| Verify certificate signatures | VerifySignature, SignatureVerified | Verifies the certificate signature and signatures in the chain of authentication to the trusted root. |
| Check trust root status | TrustedRoot | Indicates whether the certificate is anchored by a trusted root according to activated trusted roots and system CA roots. |
| Check revocation status | CheckRevoked, Revoked, OcspUrl | CheckRevoked returns 1 if revoked, 0 if not revoked, and -1 if unable to check. |
| Cache-only revocation check on Windows | UncommonOptions = "CheckRevokedCacheOnly" | Prevents network access and checks only cached revocation information on the local computer. |
Revocation caution:
A false value from Revoked may mean the status could
not be checked. Use CheckRevoked when the application
needs to distinguish “not revoked” from “unable to check.”
Extensions, Fingerprints, and Certificate Parts
| Need | Members | Purpose |
|---|---|---|
| Subject Key Identifier | SubjectKeyId | Returns the Subject Key Identifier extension in Base64 when present. |
| Authority Key Identifier | AuthorityKeyId | Returns the Authority Key Identifier extension in Base64 when present. |
| Get extension as XML | GetExtensionAsXml | Decodes ASN.1 extension data into XML. Often the preferred method for certificate extensions. |
| Get extension as text | GetExtensionAsText | Use only for extensions whose values are text and not ASN.1-encoded binary. |
| Get raw extension bytes | GetExtensionBd | Loads extension data for an OID into a BinData object. |
| Get a subject component | GetSubjectPart | Retrieves subject parts by name such as CN, O, OU, E, S, L, C, or by OID. |
| SPKI fingerprint for pinning | GetSpkiFingerprint | Returns a hash of the DER-encoded Subject Public Key Info, suitable for TLS public-key pinning. |
| Hash selected certificate parts | HashOf | Hashes parts such as IssuerDN, IssuerPublicKey, SubjectDN, or SubjectPublicKey. |
| Get certificate signature | GetSignature | Loads the certificate’s signature bytes into a BinData object. |
Exporting and Saving Certificates
| Output Format | Methods | Use When |
|---|---|---|
| DER certificate | ExportCertDer, ExportCertDerBd, ExportCertDerFile | Export the public certificate as binary ASN.1 DER. |
| PEM certificate | ExportCertPem, ExportCertPemFile | Export the public certificate in unencrypted PEM format. |
| XML certificate structure | ExportCertXml | Exports certificate ASN.1 structure as XML with binary values encoded as hex or Base64. |
| PFX / P12 bundle | ExportToPfxFile, ExportToPfxData, ExportToPfxBd | Exports the certificate and private key if available. Can optionally include the certificate chain. |
| Save as certificate file | SaveToFile | Saves the certificate object to a .cer file. |
| Convert PEM to DER file | PemFileToDerFile | Converts a PEM certificate file to a DER certificate file. |
| Base64 DER representation | GetEncoded, SetFromEncoded | Useful for storing or transporting the certificate as Base64 text. |
| X509PKIPathv1 | X509PKIPathv1 | Returns a Base64 representation of an X509PKIPathv1 containing the calling certificate, commonly used in X.509 Binary Security Tokens and some XAdES signatures. |
Private-key export reminder:
Certificate-only exports such as PEM or DER do not include the private key.
Use PFX export methods when a certificate/private-key bundle is required and the
private key is available for export.
Cloud Signing and Cloud Key Upload
| Capability | Method | Purpose |
|---|---|---|
| Configure a cloud signer | SetCloudSigner | Provides information for a remote signing service so the private-key operation happens on a remote signing server. Supported services include AWS KMS, Azure Key Vault, and Aruba Remote Signing Service. |
| Upload private key to a cloud service | UploadToCloud | Open-ended method for uploading a private key to a cloud service such as AWS KMS or Azure Key Vault. |
Compliance-friendly pattern:
For systems where the private key should not leave a secure service, configure
the certificate for remote signing with SetCloudSigner
instead of exporting or locally loading the private key.
Diagnostics and Troubleshooting
| Problem Area | Member | What to Check |
|---|---|---|
| General method failure | LastErrorText | Provides detailed information about the last method call or property access. |
| Smart card load failure | SmartCardFailReason | Indicates whether no device was detected, PIN login failed, certificate matching criteria was not found, or another failure occurred. |
| PIN validation | CheckSmartCardPin | Checks whether the configured SmartCardPin is correct. |
| Private key availability | HasPrivateKey, GetPrivateKey | Determines whether the certificate has a private key and whether it can be accessed. |
| Private key prompts on Windows | AvoidWindowsPkAccess | Set to true when high-security private-key access would trigger unwanted Windows security dialogs. |
| Chain does not reach root | BuildCertChain, UseCertVault, TrustedRoot | Provide missing intermediate certificates through a certificate vault or configure trusted roots. |
| Revocation status uncertainty | CheckRevoked | Use this instead of relying only on Revoked when the application needs to distinguish “not revoked” from “unable to check.” |
Best Practices
| Recommendation | Reason |
|---|---|
| Use LoadPfxFile for certificate/private-key bundles. | PFX/P12 is the standard format when the private key should be loaded with the certificate. |
| Use LoadFromFile for public certificate files. | It auto-detects common certificate formats such as DER, Base64, PKCS7/P7B, and PEM. |
| Call HasPrivateKey before assuming signing or decryption is possible. | A certificate may contain only a public key. Private-key operations require a linked or associated private key. |
| Use smart cards, HSMs, PKCS#11, or cloud signing when the private key should remain protected. | These approaches allow signing without exporting the private key. |
| Inspect key usage before using a certificate for TLS, S/MIME, code signing, or timestamping. | The For* properties and ExtendedKeyUsage help verify intended purpose. |
| Use BuildCertChain and inspect the resulting chain. | The method can succeed even when the chain does not reach a trusted root. |
| Use CheckRevoked for clear revocation status. | It returns three states: revoked, not revoked, or unable to check. |
| Use GetExtensionAsXml for most certificate extensions. | Most extensions contain ASN.1 data, and XML output is easier to inspect than raw binary. |
| Check LastErrorText after failures. | It provides the most useful details for diagnosing loading, store search, private-key, smart-card, chain, or export problems. |
Summary
Chilkat.Cert is the central certificate object used throughout Chilkat for TLS, S/MIME, PKCS7/CMS, signing, decryption, certificate stores, smart cards, HSMs, and cloud signing. It provides a complete set of loading, inspection, validation, key-access, export, chain-building, revocation, and diagnostic features for X.509 certificates.
Use certificate-only formats such as PEM or DER for public certificates, and use PFX/P12, smart-card loading, PKCS#11 linking, or cloud-signing configuration when private-key operations are required.