TrustedRoots PureBasic Reference Documentation

TrustedRoots

Current Version: 11.5.0

Chilkat.TrustedRoots

Configure the trusted root certificates used by Chilkat certificate validation.

Chilkat.TrustedRoots manages a collection of trusted CA and self-signed root certificates used Chilkat-wide for PKCS7/CMS 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 trusted-root set, and control whether system CA roots and self-signed server certificates are trusted.

Custom trusted roots

Add root or CA certificates that should be trusted by Chilkat validation operations.

PEM CA bundles

Load one or more trusted CA certificates from PEM bundle files used by many TLS and certificate-validation workflows.

Java keystore import

Import trusted certificates from a JavaKeyStore when trust anchors are maintained in JKS-style storage.

System CA root control

Choose whether Chilkat should also trust the operating system's CA root certificates.

Self-signed certificate policy

Control whether self-signed server certificates are rejected or accepted during certificate validation.

Activate Chilkat-wide trust

Activate the configured trusted-root set so it is used by Chilkat classes that perform TLS or signature certificate validation.

Common pattern: Create a TrustedRoots object, add trusted certificates or load a PEM CA bundle, configure whether system roots and self-signed certificates should be trusted, then call Activate. Treat trusted roots as Chilkat-wide validation configuration, not as private state for a single object.

For an extended overview, see TrustedRoots Class Overview.

Object Creation

obj.i = CkTrustedRoots::ckCreate()

; Make sure to dispose of the object when finished like this:
CkTrustedRoots::ckDispose(obj);

Properties

DebugLogFilePath
Declare.s ckDebugLogFilePath(obj.i)
Declare setCkDebugLogFilePath(obj.i, value.s)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
LastErrorHtml
Declare.s ckLastErrorHtml(obj.i) ; (read-only)

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
Declare.s ckLastErrorText(obj.i) ; (read-only)

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
Declare.s ckLastErrorXml(obj.i) ; (read-only)

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
Declare.i ckLastMethodSuccess(obj.i)
Declare setCkLastMethodSuccess(obj.i, value.i)

Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
NumCerts
Declare.i ckNumCerts(obj.i) ; (read-only)
Introduced in version 9.5.0.38

The number of certificates contained within this object.

This is the number of certificates explicitly added by the methods AddCert, AddJavaKeyStore, and LoadCaCertsPem.

top
RejectSelfSignedCerts
Declare.i ckRejectSelfSignedCerts(obj.i)
Declare setCkRejectSelfSignedCerts(obj.i, value.i)
Introduced in version 9.5.0.80

Indicates whether all self-signed certificates are to be rejected in SSL/TLS connections. The default value of this property is 0.

Note: This is for the case where the server certificate chain of authentication is 1 certificate long (i.e. the TLS server certificate itself is self-signed).

top
TrustSystemCaRoots
Declare.i ckTrustSystemCaRoots(obj.i)
Declare setCkTrustSystemCaRoots(obj.i, value.i)
Introduced in version 9.5.0.41

Indicates whether the operating system's CA root certificates are automatically trusted.

On a Windows operating system, this would be the registry-based CA certificate stores. On a Linux system, this could be /etc/ssl/certs/ca-certificates.crt, if it exists. The default value is 1. Set this property equal to 0 to prevent Chilkat from automatically trusting system-provided root CA certificates.

More Information and Examples
HTTP - Verify Server is a Trusted Root CA
top
VerboseLogging
Declare.i ckVerboseLogging(obj.i)
Declare setCkVerboseLogging(obj.i, value.i)

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
Declare.s ckVersion(obj.i) ; (read-only)

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

Activate
Declare.i ckActivate(obj.i)
Introduced in version 9.5.0.38

Activates this collection of trusted roots as the set of CA and self-signed root certificates that are to be trusted Chilkat-wide for PKCS7 signature validation and SSL/TLS server certificate validation.

More Information and Examples
HTTP - Verify Server is a Trusted Root CA
top
AddCert
Declare.i ckAddCert(obj.i, cert.i)
Introduced in version 9.5.0.41

Adds a certificate to the collection of trusted roots.

More Information and Examples
Use a Custom Set of Trusted Root CertificatesTrust Specific Root CA Certificates
top
AddJavaKeyStore
Declare.i ckAddJavaKeyStore(obj.i, keystore.i)
Introduced in version 9.5.0.44

Adds the trusted certificates from a Java key store to the collection of trusted roots.

Returns 1 for success, 0 for failure.

More Information and Examples
Load Certs from Java KeyStore into Trusted CA Roots
top
AddJavaKeyStoreAsync (1)
Declare.i ckAddJavaKeyStoreAsync(obj.i, keystore.i)
Introduced in version 9.5.0.44

Creates an asynchronous task to call the AddJavaKeyStore method with the arguments provided.

Returns 0 on failure

top
CertAt
Declare.i ckCertAt(obj.i, index.l, cert.i)
Introduced in version 11.0.0

Returns in cert the Nth cert contained within this object. The 1st certificate is at index 0.

Returns 1 for success, 0 for failure.

top
Deactivate
Declare.i ckDeactivate(obj.i)
Introduced in version 9.5.0.40

Deactivates a previous set of activated trusted roots so that all roots / self-signed certificates are implicitly trusted.

Returns 1 for success, 0 for failure.

top
LoadCaCertsPem
Declare.i ckLoadCaCertsPem(obj.i, path.s)
Introduced in version 9.5.0.38

Loads a CA bundle in PEM format. This is a file containing CA root certificates that are to be trusted. An example of one such file is the CA certs from mozilla.org exported to a cacert.pem file by the mk-ca-bundle tool located here: http://curl.haxx.se/docs/caextract.html.

Note: This can also be called to load the /etc/ssl/certs/ca-certificates.crt file on Linux systems.

More Information and Examples
Load CA Cert Bundle into Trusted Roots
top
LoadCaCertsPemAsync (1)
Declare.i ckLoadCaCertsPemAsync(obj.i, path.s)
Introduced in version 9.5.0.38

Creates an asynchronous task to call the LoadCaCertsPem method with the arguments provided.

Returns 0 on failure

top
LoadTaskCaller
Declare.i ckLoadTaskCaller(obj.i, task.i)
Introduced in version 9.5.0.80

Loads the caller of the task's async method.

Returns 1 for success, 0 for failure.

top

Deprecated

GetCert
Declare.i ckGetCert(obj.i, index.l)
Introduced in version 9.5.0.38
This method is deprecated and replaced by CertAt

This method is deprecated. Applications should instead call CertAt.

Returns the Nth cert contained within this object. The 1st certificate is at index 0.

Returns 0 on failure

More Information and Examples
Load CA Cert Bundle into Trusted Roots
top