---
product: Chilkat
product_version: 11.7.0
language: c
language_label: C
class: CertChain
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/c_CkCertChainRef.html
---
# Chilkat CertChain — C — v11.7.0

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

## Purpose

**Inspect, verify, export, and work with X.509 certificate chains.**

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

**Chain inspection**

Examine the certificates in chain order and retrieve individual certificates with `CertAt`.

**Root and trust checks**

Determine whether the chain reaches a root certificate and whether that root is trusted.

**Signature verification**

Verify that each certificate in the chain is signed by the next certificate in the chain.

**Expiration checks**

Detect whether one or more certificates in the chain are expired.

**JWK x5c support**

Load certificate chains from JWK `x5c` arrays used by JWT, JWS, and other security-token workflows.

**Chain export**

Export the certificate chain in `X509PKIPathv1` format when that representation is required.

**Common pattern:** Use `CertChain` to reason about the chain as a whole. For certificate-level details such as subject, issuer, SAN values, key usage, validity dates, fingerprints, serial numbers, and extensions, retrieve each certificate with `CertAt` and inspect it using `Chilkat.Cert`.

For an extended overview, see [CertChain Class Overview](https://www.chilkatsoft.com/certchain_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkCertChain instance = CkCertChain_Create();
// ...
CkCertChain_Dispose(instance);
```

`HCkCertChain CkCertChain_Create(void);`

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

`void CkCertChain_Dispose(HCkCertChain handle);`

Objects created by calling CkCertChain_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 CkCertChain_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 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 CkCertChain_getDebugLogFilePath(HCkCertChain cHandle, HCkString retval); void CkCertChain_putDebugLogFilePath(HCkCertChain cHandle, const char *newVal); const char *CkCertChain_debugLogFilePath(HCkCertChain 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 CkCertChain_getLastErrorHtml(HCkCertChain cHandle, HCkString retval); const char *CkCertChain_lastErrorHtml(HCkCertChain cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkCertChain_getLastErrorText(HCkCertChain cHandle, HCkString retval); const char *CkCertChain_lastErrorText(HCkCertChain cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkCertChain_getLastErrorXml(HCkCertChain cHandle, HCkString retval); const char *CkCertChain_lastErrorXml(HCkCertChain cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkCertChain_getLastMethodSuccess(HCkCertChain cHandle); void CkCertChain_putLastMethodSuccess(HCkCertChain cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkCertChain_getUtf8(HCkCertChain cHandle); void CkCertChain_putUtf8(HCkCertChain cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkCertChain_getVerboseLogging(HCkCertChain cHandle); void CkCertChain_putVerboseLogging(HCkCertChain 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 CkCertChain_getVersion(HCkCertChain cHandle, HCkString retval); const char *CkCertChain_version(HCkCertChain cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `NumCerts` | property, read-only | `int CkCertChain_getNumCerts(HCkCertChain cHandle);` |
| `NumExpiredCerts` | property, read-only | `int CkCertChain_getNumExpiredCerts(HCkCertChain cHandle);` |
| `ReachesRoot` | property, read-only | `BOOL CkCertChain_getReachesRoot(HCkCertChain cHandle);` |
| `UncommonOptions` | property, read/write | `void CkCertChain_getUncommonOptions(HCkCertChain cHandle, HCkString retval); void CkCertChain_putUncommonOptions(HCkCertChain cHandle, const char *newVal); const char *CkCertChain_uncommonOptions(HCkCertChain cHandle);` |
| `CertAt` | method | `BOOL CkCertChain_CertAt(HCkCertChain cHandle, int index, HCkCert cert);` |
| `IsRootTrusted` | method | `BOOL CkCertChain_IsRootTrusted(HCkCertChain cHandle, HCkTrustedRoots trustedRoots);` |
| `LoadX5C` | method | `BOOL CkCertChain_LoadX5C(HCkCertChain cHandle, HCkJsonObject jwk);` |
| `VerifyCertSignatures` | method | `BOOL CkCertChain_VerifyCertSignatures(HCkCertChain cHandle);` |
| `X509PKIPathv1` | method | `BOOL CkCertChain_X509PKIPathv1(HCkCertChain cHandle, HCkString outStr); const char *CkCertChain_x509PKIPathv1(HCkCertChain cHandle);` |

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

## Properties

### CertChain.NumCerts

`Chilkat 11.7.0 · c · CertChain · NumCerts · property · read-only · since 9.5.0.40`

```c
int CkCertChain_getNumCerts(HCkCertChain cHandle);
```

The number of certificates currently contained in the chain.

| Index | Meaning |
| :--- | :--- |
| `0` | The target or end-entity certificate—the certificate farthest from the root end of the chain |
| `1 ... NumCerts - 2` | Intermediate CA certificates, when present |
| `NumCerts - 1` | The highest certificate available in the chain |

**Do not assume the final certificate is trusted:** If `ReachesRoot` is `FALSE`, the final certificate may only be the highest intermediate that was available. Even when the chain ends in a self-signed root, trust must be established separately.

### CertChain.NumExpiredCerts

`Chilkat 11.7.0 · c · CertChain · NumExpiredCerts · property · read-only · since 9.5.0.40`

```c
int CkCertChain_getNumExpiredCerts(HCkCertChain cHandle);
```

The number of certificates in the chain whose validity period has expired.

**Expiration is only one validation check:** A value of `0` does not mean the chain is valid or trusted. It does not by itself establish that certificates are already valid, correctly signed, unrevoked, issued by an accepted trust anchor, or suitable for the intended identity and key usage.

Retrieve individual certificates with `CertAt` when the application needs to inspect exact validity dates or identify which certificates are expired.

### CertChain.ReachesRoot

`Chilkat 11.7.0 · c · CertChain · ReachesRoot · property · read-only · since 9.5.0.44`

```c
BOOL CkCertChain_getReachesRoot(HCkCertChain cHandle);
```

`TRUE` if the chain extends to a terminal root certificate rather than stopping at an intermediate certificate. When this property is `TRUE`, the certificate at index `NumCerts - 1` is the root-end certificate of the chain.

**Root presence is not root trust:** An included root is commonly self-signed, but its presence does not make it a trusted anchor. Use `IsRootTrusted` with the application's approved `TrustedRoots` collection to test trust-anchor membership.

A value of `FALSE` means the chain is incomplete at the root end; the final certificate may be an intermediate CA for which no issuer certificate was available.

### CertChain.UncommonOptions

`Chilkat 11.7.0 · c · CertChain · UncommonOptions · property · read/write · since 9.5.0.98`

```c
void CkCertChain_getUncommonOptions(HCkCertChain cHandle, HCkString retval);
void CkCertChain_putUncommonOptions(HCkCertChain cHandle, const char *newVal);
const char *CkCertChain_uncommonOptions(HCkCertChain cHandle);
```

Specifies uncommon behavior as a comma-separated list of keywords. The default is the empty string, which enables the standard behavior.

| Keyword | Effect |
| :--- | :--- |
| `PkiPathV1.ExcludeRoot` | Omits the root certificate from the value returned by `X509PKIPathv1`. This option affects that method only. |

**Interoperability note:** Some protocols transport the trust anchor with the path, while others expect the recipient to obtain or trust it independently. Use this option according to the format required by the receiving system.

## Methods

### CertChain.CertAt

`Chilkat 11.7.0 · c · CertChain · CertAt · method · since 11.0.0`

```c
BOOL CkCertChain_CertAt(HCkCertChain cHandle, int index, HCkCert cert);
```

Populates `cert` with the certificate at the specified zero-based `index`. Valid indices range from `0` through `NumCerts - 1`.

| Index | Position in the chain |
| :--- | :--- |
| `0` | Target or end-entity certificate |
| `1 ... NumCerts - 2` | Intermediate CA certificates, when present |
| `NumCerts - 1` | Highest certificate available in the chain; a root certificate only when `ReachesRoot` is `TRUE` |

Returns `TRUE` on success. Returns `FALSE` if the index is invalid or the certificate cannot be returned; in that case, do not use the contents of `cert` as a successful result.

Returns TRUE for success, FALSE for failure.

### CertChain.IsRootTrusted

`Chilkat 11.7.0 · c · CertChain · IsRootTrusted · method · since 9.5.0.40`

```c
BOOL CkCertChain_IsRootTrusted(HCkCertChain cHandle, HCkTrustedRoots trustedRoots);
```

Tests whether the certificate at the root end of this chain is present in the `TrustedRoots` collection passed in `trustedRoots`. Returns `TRUE` when a matching trusted-root certificate is found; otherwise returns `FALSE`.

**Trust is a local policy decision:** A self-signed certificate is not trusted merely because it appears at the end of a chain. This method checks membership in the supplied trust collection; it does not, by itself, establish that the entire chain is valid for a particular application or identity.

A complete certificate-validation decision may also require checking signature linkage, certificate validity periods, revocation status, basic constraints, key usage, policies, name constraints, and application-specific identity requirements.

### CertChain.LoadX5C

`Chilkat 11.7.0 · c · CertChain · LoadX5C · method · since 9.5.0.66`

```c
BOOL CkCertChain_LoadX5C(HCkCertChain cHandle, HCkJsonObject jwk);
```

Loads the certificate chain from the `x5c` member of the JWK contained in `jwk`. Returns `TRUE` if the chain is loaded successfully; otherwise returns `FALSE`.

As defined by RFC 7517, `x5c` is a JSON array of DER-encoded X.509 certificates represented using standard Base64—not Base64URL. The first certificate contains the key associated with the JWK. Each following certificate should certify the certificate immediately before it, so the array order is target certificate first and rootward certificates afterward.

**Security note:** Loading an `x5c` array does not make its certificates trusted. Treat the chain as untrusted input until the required signature, validity, trust-anchor, revocation, and application-policy checks have been completed.

Returns TRUE for success, FALSE for failure.

### CertChain.VerifyCertSignatures

`Chilkat 11.7.0 · c · CertChain · VerifyCertSignatures · method · since 9.5.0.40`

```c
BOOL CkCertChain_VerifyCertSignatures(HCkCertChain cHandle);
```

Verifies the cryptographic signature linkage of the certificates in this chain. Starting with the target certificate at index `0`, each certificate's signature is checked using the public key of the next issuer certificate in the chain. Returns `TRUE` when the certificate signatures are valid through the root end of the chain; otherwise returns `FALSE`.

**Signature verification is not full path validation:** A `TRUE` result confirms the issuer-signature relationships represented by the chain. It does not by itself prove that the root is trusted, that certificates are within their validity periods, that none are revoked, that CA constraints and policies are acceptable, or that the target certificate is valid for a particular hostname or usage.

### CertChain.X509PKIPathv1

`Chilkat 11.7.0 · c · CertChain · X509PKIPathv1 · method · since 9.5.0.88`

```c
BOOL CkCertChain_X509PKIPathv1(HCkCertChain cHandle, HCkString outStr);
const char *CkCertChain_x509PKIPathv1(HCkCertChain cHandle);
```

Returns the Base64 representation of a DER-encoded ASN.1 `PkiPath` containing the certificates in this chain. This representation is commonly identified as the `X509PKIPathv1` token type in WS-Security and may also be encountered in XML-signature workflows.

A `PkiPath` is a `SEQUENCE OF Certificate` ordered from the root or most-trusted end toward the target certificate. This is the reverse of the indexing used by `CertAt`, where index `0` is the target certificate.

| Representation | Certificate order |
| :--- | :--- |
| `CertChain` indexing | Target/leaf → intermediates → root |
| `X509PKIPathv1` | Root → intermediates → target/leaf |

By default, the root certificate is included when it is present in the chain. Set `UncommonOptions` to `PkiPathV1.ExcludeRoot` when the receiving protocol expects the trust anchor to be supplied separately.

**Return-value note:** This is a string-returning method. Check `LastMethodSuccess` before using the returned text, and inspect `LastErrorText` if the operation fails.

Returns TRUE for success, FALSE for failure.

## 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/c/classes/Cert.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/JsonObject.md), [`TrustedRoots`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/TrustedRoots.md)