TrustedRoots Python 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.

Object Creation

obj = chilkat2.TrustedRoots()

Properties

DebugLogFilePath
string DebugLogFilePath

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
top
LastErrorHtml
string LastErrorHtml (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
string LastErrorText (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.

top
LastErrorXml
string LastErrorXml (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
bool LastMethodSuccess

Indicates the success or failure of the most recent method call: True means success, False 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
int NumCerts (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
bool RejectSelfSignedCerts
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 False.

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
bool TrustSystemCaRoots
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 True. Set this property equal to False to prevent Chilkat from automatically trusting system-provided root CA certificates.

More Information and Examples
top
VerboseLogging
bool VerboseLogging

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

top
Version
string Version (read-only)

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

More Information and Examples
top

Methods

Activate
bool Activate()
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
top
AddCert
bool AddCert(Cert cert)
Introduced in version 9.5.0.41

Adds a certificate to the collection of trusted roots.

top
AddJavaKeyStore
bool AddJavaKeyStore(JavaKeyStore keystore)
Introduced in version 9.5.0.44

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

Returns True for success, False for failure.

top
AddJavaKeyStoreAsync (1)
Task AddJavaKeyStoreAsync(JavaKeyStore keystore)
Introduced in version 9.5.0.44

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

Returns None on failure

top
CertAt
bool CertAt(int index, Cert cert)
Introduced in version 11.0.0

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

Returns True for success, False for failure.

top
Deactivate
bool Deactivate()
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 True for success, False for failure.

top
LoadCaCertsPem
bool LoadCaCertsPem(string path)
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
top
LoadCaCertsPemAsync (1)
Task LoadCaCertsPemAsync(string path)
Introduced in version 9.5.0.38

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

Returns None on failure

top
LoadTaskCaller
bool LoadTaskCaller(Task task)
Introduced in version 9.5.0.80

Loads the caller of the task's async method.

Returns True for success, False for failure.

top

Deprecated

GetCert
Cert GetCert(int index)
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 None on failure

More Information and Examples
top