---
product: Chilkat
product_version: 11.7.0
language: ckperl
language_label: Perl
class: CertChain
class_name: CkCertChain
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/perlCkCertChainRef.html
---
# Chilkat CertChain — Perl — v11.7.0

> Chilkat 11.7.0 · language=ckperl · class=CertChain (CkCertChain)
> 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/ckperl/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

**Object Creation**

```perl
$obj = chilkat::CkCertChain->new();
```

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 Perl.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## 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` | `# $strVal is a string # $ckStr is a CkString $certChain->get_DebugLogFilePath($ckStr); $strVal = $certChain->debugLogFilePath(); $certChain->put_DebugLogFilePath($strVal);` | 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` | `# $strVal is a string # $ckStr is a CkString $certChain->get_LastErrorHtml($ckStr); $strVal = $certChain->lastErrorHtml();` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `# $strVal is a string # $ckStr is a CkString $certChain->get_LastErrorText($ckStr); $strVal = $certChain->lastErrorText();` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `# $strVal is a string # $ckStr is a CkString $certChain->get_LastErrorXml($ckStr); $strVal = $certChain->lastErrorXml();` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `# $boolVal is a boolean $boolVal = $certChain->get_LastMethodSuccess(); $certChain->put_LastMethodSuccess($boolVal);` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `Utf8` | `# $boolVal is a boolean $boolVal = $certChain->get_Utf8(); $certChain->put_Utf8($boolVal);` | read/write | When set to `1`, all `string` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `# $boolVal is a boolean $boolVal = $certChain->get_VerboseLogging(); $certChain->put_VerboseLogging($boolVal);` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `# $strVal is a string # $ckStr is a CkString $certChain->get_Version($ckStr); $strVal = $certChain->version();` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `NumCerts` | property, read-only | `# $intVal is an integer $intVal = $certChain->get_NumCerts();` |
| `NumExpiredCerts` | property, read-only | `# $intVal is an integer $intVal = $certChain->get_NumExpiredCerts();` |
| `ReachesRoot` | property, read-only | `# $boolVal is a boolean $boolVal = $certChain->get_ReachesRoot();` |
| `UncommonOptions` | property, read/write | `# $strVal is a string # $ckStr is a CkString $certChain->get_UncommonOptions($ckStr); $strVal = $certChain->uncommonOptions(); $certChain->put_UncommonOptions($strVal);` |
| `CertAt` | method | `# $index is an integer # $cert is a CkCert $status = $certChain->CertAt($index, $cert);` |
| `IsRootTrusted` | method | `# $trustedRoots is a CkTrustedRoots $retBool = $certChain->IsRootTrusted($trustedRoots);` |
| `LoadX5C` | method | `# $jwk is a CkJsonObject $status = $certChain->LoadX5C($jwk);` |
| `VerifyCertSignatures` | method | `$retBool = $certChain->VerifyCertSignatures();` |
| `X509PKIPathv1` | method | `# $outStr is a CkString (output) $status = $certChain->X509PKIPathv1($outStr); $retStr = $certChain->x509PKIPathv1();` |

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 · ckperl · CertChain · NumCerts · property · read-only · since 9.5.0.40`

```perl
# $intVal is an integer

$intVal = $certChain->get_NumCerts();
```

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 `0`, 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 · ckperl · CertChain · NumExpiredCerts · property · read-only · since 9.5.0.40`

```perl
# $intVal is an integer

$intVal = $certChain->get_NumExpiredCerts();
```

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 · ckperl · CertChain · ReachesRoot · property · read-only · since 9.5.0.44`

```perl
# $boolVal is a boolean

$boolVal = $certChain->get_ReachesRoot();
```

`1` if the chain extends to a terminal root certificate rather than stopping at an intermediate certificate. When this property is `1`, 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 `0` 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 · ckperl · CertChain · UncommonOptions · property · read/write · since 9.5.0.98`

```perl
# $strVal is a string

# $ckStr is a CkString

$certChain->get_UncommonOptions($ckStr);

$strVal = $certChain->uncommonOptions();

$certChain->put_UncommonOptions($strVal);
```

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 · ckperl · CertChain · CertAt · method · since 11.0.0`

```perl
# $index is an integer

# $cert is a CkCert

$status = $certChain->CertAt($index, $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 `1` |

Returns `1` on success. Returns `0` 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 1 for success, 0 for failure.

### CertChain.IsRootTrusted

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

```perl
# $trustedRoots is a CkTrustedRoots

$retBool = $certChain->IsRootTrusted($trustedRoots);
```

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

**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 · ckperl · CertChain · LoadX5C · method · since 9.5.0.66`

```perl
# $jwk is a CkJsonObject

$status = $certChain->LoadX5C($jwk);
```

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

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 1 for success, 0 for failure.

### CertChain.VerifyCertSignatures

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

```perl
$retBool = $certChain->VerifyCertSignatures();
```

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 `1` when the certificate signatures are valid through the root end of the chain; otherwise returns `0`.

**Signature verification is not full path validation:** A `1` 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 · ckperl · CertChain · X509PKIPathv1 · method · since 9.5.0.88`

```perl
# $outStr is a CkString (output)

$status = $certChain->X509PKIPathv1($outStr);

$retStr = $certChain->x509PKIPathv1();
```

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