Chilkat.CertChain Class Overview

Chilkat.CertChain represents an ordered X.509 certificate chain, beginning with the end-entity certificate and continuing through intermediate certificates to the root certificate when available. It is used to inspect, verify, export, and trust-check certificate chains.

What the Class Is Used For

Use Chilkat.CertChain when an application needs to examine or verify a certificate chain. A chain is typically produced by Cert.BuildCertChain, loaded from a JWK x5c array, or used when validating signatures, TLS certificates, X.509 Binary Security Tokens, or XAdES-related certificate paths.

Inspect Chain Contents Access the certificates in order, from the end-entity certificate at index 0 to the root certificate at the final index.
Check Chain Completeness Determine whether the chain reaches a root certificate with ReachesRoot.
Verify Signatures Verify that each certificate in the chain was signed by the next certificate above it.
Export Certificate Path Export the chain as an X509PKIPathv1 value for token and signature formats that require an encoded certificate path.

Typical Workflow

  1. Build or load the certificate chain. For example, call Cert.BuildCertChain to populate a CertChain, or call LoadX5C to load the chain from a JWK x5c parameter.
  2. Check NumCerts to determine how many certificates are in the chain.
  3. Use CertAt to retrieve individual certificates for inspection, display, validation, or export.
  4. Check ReachesRoot to determine whether the chain extends to a root certificate.
  5. Check NumExpiredCerts to determine whether one or more certificates in the chain are expired.
  6. Call VerifyCertSignatures to verify the certificate signatures through the chain.
  7. If needed, call IsRootTrusted with a TrustedRoots object to determine whether the root certificate is trusted by the application.

Certificate Ordering

Certificates in a CertChain are ordered from the certificate being validated up toward the root.

Index Certificate Role Description
0 End-entity / subscriber certificate The certificate most removed from the trusted root. This is usually the server certificate, signing certificate, client certificate, or other certificate being validated.
1 to NumCerts - 2 Intermediate certificates Certificates that link the end-entity certificate to the root certificate. A chain may contain zero, one, or multiple intermediates.
NumCerts - 1 Root or self-signed certificate The certificate at the top of the chain. The root certificate may be a trusted CA root or a self-signed certificate.
Indexing reminder: Chilkat uses zero-based indexing. The first certificate in the chain is retrieved with CertAt(0, cert).

Core Properties

Property Purpose How to Use It
NumCerts Returns the number of certificates in the chain. Use this to loop over the chain with CertAt.
NumExpiredCerts Returns the number of expired certificates in the chain. Use this as a quick validity check before examining individual certificates.
ReachesRoot Indicates whether the chain extends all the way to a root certificate. Use this after building a chain to determine whether the chain is complete.
LastErrorText Provides detailed information about the last method call or property access. Check this after failures or unexpected behavior.
UncommonOptions Provides uncommon or specialized options. Currently supports PkiPathV1.ExcludeRoot to exclude the root certificate from X509PKIPathv1.

Core Methods

Method Purpose Typical Use
CertAt Retrieves the Nth certificate in the chain into a Cert object. Use to inspect subject, issuer, validity, usage, extensions, or thumbprints for each certificate in the chain.
IsRootTrusted Checks whether the chain’s root certificate is present in a supplied TrustedRoots object. Use when trust should be based on an application-defined trusted-root set.
LoadX5C Loads a certificate chain from the x5c parameter of a JWK. Useful for JWT, JWS, JWK, and other JOSE workflows where a certificate chain is provided in JSON.
VerifyCertSignatures Verifies certificate signatures through the chain to the root. Use to confirm that each certificate was signed by the certificate above it.
X509PKIPathv1 Returns a Base64 representation of an X509PKIPathv1 containing the certificates in the chain. Used in X.509 Binary Security Tokens and sometimes in XAdES signatures.

Chain Validation Checks

A complete certificate-chain evaluation usually involves more than one check. The CertChain class exposes several pieces of that validation process.

Question Check Meaning
Does the chain contain certificates? NumCerts A valid chain object should contain at least the end-entity certificate.
Does the chain reach a root? ReachesRoot True when the chain extends to a root certificate, either a trusted CA root or a self-signed certificate.
Is the root trusted by this application? IsRootTrusted True when the root is found in the supplied TrustedRoots object.
Are any certificates expired? NumExpiredCerts Returns the count of expired certificates in the chain.
Are the certificate signatures valid? VerifyCertSignatures True when all certificate signatures validate through the chain to the root.
Important distinction: ReachesRoot means the chain reaches a root certificate. It does not, by itself, prove that the root is trusted by your application. Use IsRootTrusted with a TrustedRoots object for that check.

Working with Individual Certificates

The chain object stores certificates, but individual certificate details are inspected through Chilkat.Cert. Retrieve each certificate with CertAt, then use the Cert object to inspect subject, issuer, dates, thumbprints, extensions, public keys, and usage properties.

Certificate Position What to Inspect Common Cert Properties
End-entity certificate Identity, expiration, intended usage, SAN, public key, and issuer. SubjectCN, SubjectDN, SubjectAlternativeName, ValidTo, ExtendedKeyUsage
Intermediate certificates Issuer/subject linkage, validity, signature chain, and policy-related extensions. IssuerDN, SubjectDN, AuthorityKeyId, SubjectKeyId
Root certificate Whether the root is self-signed and trusted by the application. SelfSigned, IsRoot, Sha1Thumbprint

Loading from JWK x5c

The LoadX5C method loads a certificate chain from the x5c parameter of a JSON Web Key. The x5c value is commonly used in JOSE/JWT/JWS scenarios to provide an X.509 certificate chain alongside a public key.

Input Method Result
JWK containing an x5c array LoadX5C Populates the CertChain with the certificates represented by the JWK’s x5c parameter.

X509PKIPathv1 Export

X509PKIPathv1 returns a Base64 representation of an X509PKIPathv1 containing the certificates in the chain. This format is used by X.509 Binary Security Tokens and may also be used in XAdES signatures.

Need Use Notes
Export the complete chain as a PKIPath X509PKIPathv1 Returns the Base64-encoded PKIPath representation of the chain.
Exclude the root certificate from PKIPath output UncommonOptions = "PkiPathV1.ExcludeRoot" Use when the target format or verifier expects the PKIPath to omit the root certificate.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Method failure or unexpected result LastErrorText Provides detailed diagnostic information about the last called method or property.
Incomplete chain ReachesRoot If false, an intermediate or root certificate may be missing from the available certificate sources.
Expired certificates NumExpiredCerts If greater than zero, retrieve certificates with CertAt and inspect their validity dates.
Untrusted root IsRootTrusted Check whether the chain’s root certificate exists in the supplied TrustedRoots object.
Invalid signatures VerifyCertSignatures If false, a certificate may not have been signed by the next certificate in the chain, or the chain may be malformed.

Best Practices

Recommendation Reason
Always check NumCerts before iterating. It prevents out-of-range access when using CertAt.
Use ReachesRoot to determine chain completeness. A built chain may still be incomplete if intermediate or root certificates are unavailable.
Do not treat “reaches root” as the same as “trusted.” A chain can reach a self-signed root that is not trusted by the application. Use IsRootTrusted for trust evaluation.
Check NumExpiredCerts before relying on the chain. A chain with expired certificates should normally be rejected or flagged.
Call VerifyCertSignatures for signature validation. This confirms that the certificates are cryptographically linked through the chain.
Use CertAt for detailed certificate inspection. Chain-level properties summarize the chain, while individual certificate fields are exposed by Chilkat.Cert.
Set PkiPathV1.ExcludeRoot only when the target format requires it. Some token or signature formats may expect the root certificate to be omitted from the exported PKIPath.
Check LastErrorText after failures. It provides the most useful information for diagnosing load, export, trust, or signature-verification problems.

Summary

Chilkat.CertChain is a compact helper class for representing and working with X.509 certificate chains. It lets applications inspect the chain order, retrieve individual certificates, determine whether the chain reaches a root, check for expired certificates, verify chain signatures, test whether the root is trusted, load chains from JWK x5c, and export the chain as X509PKIPathv1.

For certificate-level details such as subject, issuer, SAN, key usage, validity dates, thumbprints, and extensions, retrieve each certificate with CertAt and inspect it using Chilkat.Cert.