Chilkat.TrustedRoots Class Overview

Chilkat.TrustedRoots manages a collection of trusted CA and self-signed root certificates used Chilkat-wide for PKCS7 signature validation and SSL/TLS server certificate validation. It can add individual certificates, import trusted certificates from a Java keystore, load PEM CA bundles, activate the trusted-root set, and control whether system CA roots and self-signed server certificates are trusted.

What the Class Is Used For

Use Chilkat.TrustedRoots when an application needs to customize which root certificates Chilkat trusts during certificate-chain validation. This is useful when using private certificate authorities, bundled CA files, Java keystores, or when application policy requires controlling whether operating-system CA roots are trusted.

Trust Custom Root Certificates Add trusted CA or self-signed root certificates with AddCert.
Load CA Bundles Import a PEM CA bundle with LoadCaCertsPem.
Use Java Keystores Add trusted certificates from a JavaKeyStore.
Activate Chilkat-Wide Trust Call Activate to apply the trusted roots to Chilkat validation operations.

Typical Workflow

  1. Create a TrustedRoots object.
  2. Add trusted roots using AddCert, AddJavaKeyStore, or LoadCaCertsPem.
  3. Optionally set TrustSystemCaRoots to control whether operating-system root certificates are also trusted.
  4. Optionally set RejectSelfSignedCerts to reject one-certificate server chains where the TLS server certificate is self-signed.
  5. Call Activate to make this collection the active Chilkat-wide trusted root set.
  6. Use other Chilkat classes that perform SSL/TLS server certificate validation or PKCS7 signature validation.
  7. If needed, call Deactivate to remove the previously activated trusted-root set.
  8. Check LastErrorText if an operation fails or behaves unexpectedly.
Activation matters: Certificates added to a TrustedRoots object do not become Chilkat-wide trusted roots until Activate is called.

Core Concepts

Concept Meaning Important Members
Trusted Root Collection A set of CA or self-signed root certificates explicitly added to the object. AddCert, AddJavaKeyStore, LoadCaCertsPem, NumCerts
Chilkat-Wide Activation Makes this trusted-root collection the active set used by Chilkat validation operations. Activate, Deactivate
System CA Roots Root certificates provided by the operating system, such as Windows registry-based CA stores or a Linux CA certificate bundle. TrustSystemCaRoots
Self-Signed TLS Server Certificates A special case where the server certificate chain is one certificate long and the server certificate is self-signed. RejectSelfSignedCerts
PEM CA Bundle A file containing CA root certificates to be trusted. LoadCaCertsPem

Properties

Property Purpose Default / Guidance
NumCerts Number of certificates explicitly contained in this object. Counts certificates added by AddCert, AddJavaKeyStore, and LoadCaCertsPem. It does not represent the number of system CA roots.
TrustSystemCaRoots Controls whether operating-system CA root certificates are automatically trusted. Default is true. Set false to prevent Chilkat from automatically trusting system-provided root CA certificates.
RejectSelfSignedCerts Controls whether self-signed TLS server certificates are rejected. Default is false. Applies when the server certificate chain is one certificate long and that certificate is self-signed.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Adding Trusted Certificates

Method Input Purpose
AddCert Cert Adds one certificate to the trusted-root collection.
AddJavaKeyStore JavaKeyStore Adds trusted certificates from a Java keystore to the collection.
LoadCaCertsPem Path to a PEM CA bundle file. Loads a PEM file containing CA root certificates. This can also be used to load /etc/ssl/certs/ca-certificates.crt on Linux systems.
PEM bundle example: A CA bundle may contain many trusted root certificates, such as a cacert.pem file generated from Mozilla CA certificates or a Linux system CA bundle.

Activating and Deactivating Trust Settings

Method Effect Use When
Activate Activates this collection as the Chilkat-wide set of trusted CA and self-signed root certificates. Use after adding certificates and configuring trust behavior.
Deactivate Deactivates a previously activated trusted-root set so that all roots and self-signed certificates are implicitly trusted. Use when the application should no longer use the previously activated trusted-root restrictions.
Security note: Deactivate removes the active trusted-root set and returns to behavior where roots and self-signed certificates are implicitly trusted. Use deliberately and only when appropriate for the application.

System CA Roots and Self-Signed Certificates

Setting Behavior Typical Use
TrustSystemCaRoots = true Chilkat automatically trusts operating-system CA roots. Default behavior. Use when standard OS-provided public CAs should be trusted.
TrustSystemCaRoots = false Chilkat does not automatically trust system-provided root CA certificates. Use when the application should trust only explicitly added roots.
RejectSelfSignedCerts = false Self-signed TLS server certificates are not rejected solely because they are self-signed. Default behavior.
RejectSelfSignedCerts = true Rejects TLS server certificate chains consisting of one self-signed certificate. Use when policy requires rejecting self-signed server certificates.
Platform note: On Windows, system CA roots refer to registry-based CA certificate stores. On Linux, Chilkat may use /etc/ssl/certs/ca-certificates.crt if it exists.

Inspecting the Trusted-Root Collection

Member Purpose Important Details
NumCerts Returns the number of explicitly added certificates. Useful for iterating the certificates contained in this object.
CertAt Retrieves the Nth certificate in the collection. Indexing begins at 0. The retrieved certificate is returned in a Cert object.

Async Support

Method Purpose Use When
LoadTaskCaller Loads the caller of the task’s async method. Use in asynchronous task workflows when working with a completed Task.

Method Summary by Category

Category Methods / Properties Purpose
Add trust anchors AddCert, AddJavaKeyStore, LoadCaCertsPem Add individual certificates, Java keystore certificates, or PEM CA bundle certificates to the trusted-root collection.
Activate trust settings Activate, Deactivate Apply or remove the Chilkat-wide trusted-root configuration.
Inspect certificates NumCerts, CertAt Count and retrieve explicitly added certificates.
Trust policy TrustSystemCaRoots, RejectSelfSignedCerts Control use of system CA roots and self-signed TLS server certificates.
Async workflow LoadTaskCaller Load the caller associated with a completed async task.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Custom roots appear to have no effect AddCert, LoadCaCertsPem, Activate Confirm certificates were added successfully and that Activate was called.
System CA roots are still trusted TrustSystemCaRoots Set this property to false if the application should trust only explicitly added roots.
Self-signed server certificates are accepted RejectSelfSignedCerts Set this property to true to reject TLS server chains that contain only one self-signed certificate.
PEM CA bundle does not load LoadCaCertsPem Verify the file path, file permissions, and that the file is a PEM CA bundle.
Unexpected certificate count NumCerts Remember that this count includes only certificates explicitly added by AddCert, AddJavaKeyStore, and LoadCaCertsPem.
Need to inspect an added certificate CertAt Iterate from index 0 to NumCerts - 1.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected add, load, activate, deactivate, inspect, or async operations.

Common Pitfalls

Pitfall Better Approach
Adding certificates but forgetting to call Activate. Call Activate after building the trusted-root collection.
Assuming NumCerts includes operating-system CA roots. Treat NumCerts as the count of certificates explicitly added to this object.
Expecting system CA roots to be disabled by default. TrustSystemCaRoots defaults to true. Set it to false when only explicitly added roots should be trusted.
Assuming RejectSelfSignedCerts rejects every certificate chain containing a self-signed root. This property is for the case where the TLS server certificate chain is one certificate long and the server certificate itself is self-signed.
Calling Deactivate without considering the resulting trust behavior. Use Deactivate deliberately because it removes the activated trusted-root set.
Ignoring diagnostics after a failed load or activation operation. Check LastErrorText for details.

Best Practices

Recommendation Reason
Add all required root certificates before activating. This keeps the active trust policy clear and avoids partial configurations.
Set TrustSystemCaRoots explicitly when trust policy matters. It makes the application’s validation behavior clear and predictable.
Use LoadCaCertsPem for bundled or platform CA files. It can load a PEM CA bundle containing multiple trusted root certificates.
Use AddJavaKeyStore when trust anchors are already maintained in a Java keystore. This avoids manually extracting each trusted certificate.
Use CertAt to inspect explicitly loaded certificates. It can help verify which certificates were added to the trusted-root collection.
Be cautious with Deactivate. It removes the previously activated trusted-root set and changes validation behavior.
Check LastErrorText after failures. It provides useful diagnostic detail for certificate loading, activation, deactivation, and inspection operations.

Summary

Chilkat.TrustedRoots is the Chilkat class for defining a Chilkat-wide trusted-root certificate collection used in PKCS7 signature validation and SSL/TLS server certificate validation. It can add individual certificates, import trusted certificates from a Java keystore, load PEM CA bundles, activate or deactivate the trust set, inspect explicitly added certificates, and control whether system CA roots and self-signed TLS server certificates are trusted.

The most important practical guidance is to add the desired trust anchors, set TrustSystemCaRoots and RejectSelfSignedCerts according to application policy, call Activate to apply the configuration, remember that NumCerts counts only explicitly added certificates, and inspect LastErrorText whenever an operation fails.