---
product: Chilkat
product_version: 11.7.0
language: wc
language_label: Unicode C
class: TrustedRoots
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wc_CkTrustedRootsWRef.html
---
# Chilkat TrustedRoots — Unicode C — v11.7.0

> Chilkat 11.7.0 · language=wc · class=TrustedRoots
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/TrustedRoots.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/guide.md`.

## Purpose

**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](https://www.chilkatsoft.com/trustedroots_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkTrustedRootsW instance = CkTrustedRootsW_Create();
// ...
CkTrustedRootsW_Dispose(instance);
```

`HCkTrustedRootsW CkTrustedRootsW_Create(void);`

Creates an instance of the HCkTrustedRootsW object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkTrustedRootsW_Dispose(HCkTrustedRootsW handle);`

Objects created by calling CkTrustedRootsW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkTrustedRootsW_Dispose.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Unicode C.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `void CkTrustedRootsW_getDebugLogFilePath(HCkTrustedRootsW cHandle, HCkString retval); void CkTrustedRootsW_putDebugLogFilePath(HCkTrustedRootsW cHandle, const wchar_t *newVal); const wchar_t *CkTrustedRootsW_debugLogFilePath(HCkTrustedRootsW cHandle);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `void CkTrustedRootsW_getLastErrorHtml(HCkTrustedRootsW cHandle, HCkString retval); const wchar_t *CkTrustedRootsW_lastErrorHtml(HCkTrustedRootsW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkTrustedRootsW_getLastErrorText(HCkTrustedRootsW cHandle, HCkString retval); const wchar_t *CkTrustedRootsW_lastErrorText(HCkTrustedRootsW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkTrustedRootsW_getLastErrorXml(HCkTrustedRootsW cHandle, HCkString retval); const wchar_t *CkTrustedRootsW_lastErrorXml(HCkTrustedRootsW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkTrustedRootsW_getLastMethodSuccess(HCkTrustedRootsW cHandle); void CkTrustedRootsW_putLastMethodSuccess(HCkTrustedRootsW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkTrustedRootsW_getVerboseLogging(HCkTrustedRootsW cHandle); void CkTrustedRootsW_putVerboseLogging(HCkTrustedRootsW cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkTrustedRootsW_getVersion(HCkTrustedRootsW cHandle, HCkString retval); const wchar_t *CkTrustedRootsW_version(HCkTrustedRootsW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `NumCerts` | property, read-only | `int CkTrustedRootsW_getNumCerts(HCkTrustedRootsW cHandle);` |
| `RejectSelfSignedCerts` | property, read/write | `BOOL CkTrustedRootsW_getRejectSelfSignedCerts(HCkTrustedRootsW cHandle); void CkTrustedRootsW_putRejectSelfSignedCerts(HCkTrustedRootsW cHandle, BOOL newVal);` |
| `TrustSystemCaRoots` | property, read/write | `BOOL CkTrustedRootsW_getTrustSystemCaRoots(HCkTrustedRootsW cHandle); void CkTrustedRootsW_putTrustSystemCaRoots(HCkTrustedRootsW cHandle, BOOL newVal);` |
| `Activate` | method | `BOOL CkTrustedRootsW_Activate(HCkTrustedRootsW cHandle);` |
| `AddCert` | method | `BOOL CkTrustedRootsW_AddCert(HCkTrustedRootsW cHandle, HCkCertW cert);` |
| `AddJavaKeyStore` | method | `BOOL CkTrustedRootsW_AddJavaKeyStore(HCkTrustedRootsW cHandle, HCkJavaKeyStoreW keystore);` |
| `CertAt` | method | `BOOL CkTrustedRootsW_CertAt(HCkTrustedRootsW cHandle, int index, HCkCertW cert);` |
| `Deactivate` | method | `BOOL CkTrustedRootsW_Deactivate(HCkTrustedRootsW cHandle);` |
| `LoadCaCertsPem` | method | `BOOL CkTrustedRootsW_LoadCaCertsPem(HCkTrustedRootsW cHandle, const wchar_t *path);` |
| `LoadTaskCaller` | method | `BOOL CkTrustedRootsW_LoadTaskCaller(HCkTrustedRootsW cHandle, HCkTaskW task);` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### TrustedRoots.NumCerts

`Chilkat 11.7.0 · wc · TrustedRoots · NumCerts · property · read-only · since 9.5.0.38`

```c
int CkTrustedRootsW_getNumCerts(HCkTrustedRootsW cHandle);
```

The number of certificates explicitly contained in this object. The count includes certificates added by `AddCert`, `AddJavaKeyStore`, and `LoadCaCertsPem`.

Use indexes from `0` through `NumCerts - 1` with `CertAt`.

**Scope of the count:** This property does not include operating-system CA roots made available by `TrustSystemCaRoots`. It reports only the certificates stored in this object.

### TrustedRoots.RejectSelfSignedCerts

`Chilkat 11.7.0 · wc · TrustedRoots · RejectSelfSignedCerts · property · read/write · since 9.5.0.80`

```c
BOOL CkTrustedRootsW_getRejectSelfSignedCerts(HCkTrustedRootsW cHandle);
void CkTrustedRootsW_putRejectSelfSignedCerts(HCkTrustedRootsW cHandle, BOOL newVal);
```

Controls the special case in which an SSL/TLS server presents a certificate chain containing exactly one certificate and that certificate is self-signed. The default value is `FALSE`.

| Value | Behavior |
| :--- | :--- |
| `FALSE` | Do not reject a one-certificate TLS chain solely because the certificate is self-signed. |
| `TRUE` | Reject TLS server chains consisting of one self-signed certificate. |

This property applies to the TLS server-certificate case described above. It does not reject a self-signed CA certificate merely because that certificate appears as the trust anchor above a longer chain.

**Security guidance:** A self-signed certificate has no external issuer establishing trust. Accept it only when the certificate or its public-key fingerprint has been authenticated through a separate trusted channel.

### TrustedRoots.TrustSystemCaRoots

`Chilkat 11.7.0 · wc · TrustedRoots · TrustSystemCaRoots · property · read/write · since 9.5.0.41`

```c
BOOL CkTrustedRootsW_getTrustSystemCaRoots(HCkTrustedRootsW cHandle);
void CkTrustedRootsW_putTrustSystemCaRoots(HCkTrustedRootsW cHandle, BOOL newVal);
```

Controls whether operating-system CA roots are included when this object's trust configuration is activated. The default value is `TRUE`.

| Value | Behavior |
| :--- | :--- |
| `TRUE` | Trust explicitly added certificates and the system-provided CA roots available to Chilkat. |
| `FALSE` | Do not automatically trust system-provided CA roots; use the explicitly configured collection and the selected self-signed-certificate policy. |

On Windows, system roots come from registry-based certificate stores. On Linux, Chilkat may use a system CA bundle such as `/etc/ssl/certs/ca-certificates.crt` when available.

System roots are not added to this object's explicit collection and therefore are not included in `NumCerts` or returned by `CertAt`.

## Methods

### TrustedRoots.Activate

`Chilkat 11.7.0 · wc · TrustedRoots · Activate · method · since 9.5.0.38`

```c
BOOL CkTrustedRootsW_Activate(HCkTrustedRootsW cHandle);
```

Activates this object's trust configuration for Chilkat-wide certificate validation. The active configuration includes:

- Certificates explicitly added to this object by `AddCert`, `AddJavaKeyStore`, or `LoadCaCertsPem`.
- Operating-system CA roots when `TrustSystemCaRoots` is `TRUE`.
- The self-signed TLS certificate policy selected by `RejectSelfSignedCerts`.

After activation, Chilkat classes that validate PKCS7/CMS signatures or SSL/TLS server certificate chains use this trust configuration. Returns `TRUE` if the configuration was activated successfully; otherwise returns `FALSE`.

**Trust-anchor note:** Activating a certificate as trusted supplies a starting point for certificate-path validation. It does not, by itself, prove that every certificate issued beneath that anchor is valid for every purpose; the applicable validation operation may also evaluate signatures, validity periods, identity, key usage, constraints, and other policy requirements.

Returns TRUE for success, FALSE for failure.

### TrustedRoots.AddCert

`Chilkat 11.7.0 · wc · TrustedRoots · AddCert · method · since 9.5.0.41`

```c
BOOL CkTrustedRootsW_AddCert(HCkTrustedRootsW cHandle, HCkCertW cert);
```

Adds the certificate in `cert` to this object's explicit trusted-certificate collection. The certificate is subsequently treated as a trust anchor when this configuration is activated.

Returns `TRUE` if the certificate was added successfully; otherwise returns `FALSE`.

**Security-sensitive operation:** Calling this method is an explicit trust decision. It does not first determine whether the certificate is self-signed, belongs to a public CA, is currently valid, or is appropriate for the intended application. Add only certificates obtained and verified through a trustworthy process.

Returns TRUE for success, FALSE for failure.

### TrustedRoots.AddJavaKeyStore

`Chilkat 11.7.0 · wc · TrustedRoots · AddJavaKeyStore · method · since 9.5.0.44`

```c
BOOL CkTrustedRootsW_AddJavaKeyStore(HCkTrustedRootsW cHandle, HCkJavaKeyStoreW keystore);
```

Adds the certificates designated as trusted entries in the `keystore` `JavaKeyStore` to this object's explicit trusted-certificate collection.

Private keys and secret keys are not imported. Returns `TRUE` if the trusted certificates were added successfully; otherwise returns `FALSE`.

**Java keystore terminology:** A trusted-certificate entry represents a certificate that the keystore owner has chosen to trust. Importing it preserves that trust decision; it does not independently validate the certificate or build a certification path for it.

Returns TRUE for success, FALSE for failure.

Async variant: `AddJavaKeyStoreAsync` — same arguments, returns a `Task` (see Async variants below).

### TrustedRoots.CertAt

`Chilkat 11.7.0 · wc · TrustedRoots · CertAt · method · since 11.0.0`

```c
BOOL CkTrustedRootsW_CertAt(HCkTrustedRootsW cHandle, int index, HCkCertW cert);
```

Copies the certificate at zero-based `index` into the caller-supplied `Cert` object in `cert`.

Valid indexes are from `0` through `NumCerts - 1`. Returns `TRUE` if the certificate was retrieved successfully; otherwise returns `FALSE`, such as when the index is outside the valid range.

This method enumerates only certificates explicitly contained in this `TrustedRoots` object. Operating-system roots enabled through `TrustSystemCaRoots` are not included.

Returns TRUE for success, FALSE for failure.

### TrustedRoots.Deactivate

`Chilkat 11.7.0 · wc · TrustedRoots · Deactivate · method · since 9.5.0.40`

```c
BOOL CkTrustedRootsW_Deactivate(HCkTrustedRootsW cHandle);
```

Deactivates the previously activated Chilkat-wide trusted-root configuration. After deactivation, roots and single-certificate self-signed certificates are implicitly trusted.

Returns `TRUE` if the active configuration was deactivated successfully; otherwise returns `FALSE`.

**Security warning:** This is a permissive mode. It does not merely restore a conventional “trust the operating-system CA store” policy. Use `Deactivate` only when implicitly trusting arbitrary roots and self-signed certificates is intentional and acceptable for the application.

Returns TRUE for success, FALSE for failure.

### TrustedRoots.LoadCaCertsPem

`Chilkat 11.7.0 · wc · TrustedRoots · LoadCaCertsPem · method · since 9.5.0.38`

```c
BOOL CkTrustedRootsW_LoadCaCertsPem(HCkTrustedRootsW cHandle, const wchar_t *path);
```

Loads one or more PEM-encoded certificates from the file at `path` and adds them to this object's explicit trusted-certificate collection. A CA bundle normally contains consecutive `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` blocks.

This method can load a curated application bundle, a Mozilla-derived CA bundle, or a platform bundle such as `/etc/ssl/certs/ca-certificates.crt` when that file exists. Returns `TRUE` if the bundle was loaded successfully; otherwise returns `FALSE`.

**Trust implication:** Certificates loaded by this method are treated as trusted anchors after activation. The file is not merely a source of intermediate certificates. Review and protect the bundle as security-sensitive configuration.

Returns TRUE for success, FALSE for failure.

Async variant: `LoadCaCertsPemAsync` — same arguments, returns a `Task` (see Async variants below).

### TrustedRoots.LoadTaskCaller

`Chilkat 11.7.0 · wc · TrustedRoots · LoadTaskCaller · method · since 9.5.0.80`

```c
BOOL CkTrustedRootsW_LoadTaskCaller(HCkTrustedRootsW cHandle, HCkTaskW task);
```

Associates `task` with the object that initiated the task's asynchronous method call. This supports Chilkat's asynchronous task infrastructure and is not normally called directly by application code.

Returns `TRUE` if the task caller was loaded successfully; otherwise returns `FALSE`.

Returns TRUE for success, FALSE for failure.

## Events and callbacks

This binding delivers progress information through callbacks (AbortCheck, PercentDone, ProgressInfo, TaskCompleted) rather than events. See `guide.md` for how to attach them in Unicode C.

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```c
HCkTaskW CkTrustedRootsW_AddJavaKeyStoreAsync(HCkTrustedRootsW cHandle, HCkJavaKeyStoreW keystore);
HCkTaskW CkTrustedRootsW_LoadCaCertsPemAsync(HCkTrustedRootsW cHandle, const wchar_t *path);
```

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `GetCert` | method | before 11.6.1 | `CertAt` |

## Related classes

[`Cert`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/Cert.md), [`JavaKeyStore`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/JavaKeyStore.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/Task.md)