Verify certificate chain (the RFC 5280 §6 verdict, offline revocation)
verify_certificate_chainValidates a leaf certificate chain against your trust anchors, checking signatures, validity, name constraints, policies, server hostname/IP, key purposes, and offline CRL/OCSP revocation.
Instructions
The one-call trust verdict for a certificate: builds a path from leaf through candidates to one of YOUR trustAnchors, verifies every signature, validates the path at at (RFC 5280 §6: validity, basic constraints, key usage, name constraints, policies — policy inputs), checks serverName (RFC 6125 host or IP) and purposes (extended key usage along the path), and judges revocation from the CRL / OCSP bytes YOU supply (crls, ocspResponses; requireRevocation:true demands evidence for every certificate below the anchor; this server never fetches). A negative verdict is valid:false + reasons[] (PKI_REASON_* codes) in structuredContent — never isError; isError is reserved for inputs the engine refuses. Pin at (ISO 8601) for a reproducible, cacheable verdict; evaluatedAt echoes the instant used. Token-frugal: verbosity:'summary' (valid, reasonCodes, pathLength). Prefer it over inspect_certificate.signature for any trust question; build_certificate_path / validate_certificate_path explain a failing path.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | The instant the verdict is evaluated at. An ISO 8601 date-time (UTC unless zoned; e.g. 2027-01-01T00:00:00Z), epoch milliseconds as digits, or 'now'. Omitted: PKINATIVE_MCP_AT when the operator pinned it, else the wall clock (a clock-dependent result is never cached). | |
| crls | No | CRLs (DER or X509 CRL PEM) for offline revocation (every PEM block of every item is taken). Optional; this server never fetches a CRL — pass the bytes you obtained. | |
| leaf | Yes | The end-entity certificate to judge: exactly one of pem / derBase64 / path. | |
| fields | No | Dot-paths to keep after verbosity (arrays map over elements); unmatched paths land in _meta.unmatchedFields. | |
| limits | No | Raise pkinative's 22 named security bounds for this call (trusted input only; absent keys keep the engine defaults). A value above an operator ceiling (PKINATIVE_MCP_MAX_INPUT_BYTES, PKINATIVE_MCP_MAX_KDF_ITERATIONS, PKINATIVE_MCP_MAX_PATHS_EXPLORED) is LIMIT_CEILING_EXCEEDED; describe_engine lists the defaults and the ceilings. | |
| policy | No | RFC 5280 §6.1.1 policy inputs. | |
| strict | No | Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[]. | |
| pemMode | No | 'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers). | strict |
| purposes | No | Extended key usages the leaf must allow: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, ocspSigning, any, or a dotted OID. | |
| allowSha1 | No | Accept or produce SHA-1 signatures (legacy material you already trust). Default false: refused with PKI_CRYPTO_ALGORITHM_REFUSED on read, VALIDATION_ERROR on write. | |
| ocspNonce | No | The nonce you put in the OCSP request (1–32 bytes), to be matched in the responses. Hexadecimal (an 0x prefix, colons and spaces are tolerated). | |
| verbosity | No | 'summary' keeps the scalar fields only (token-frugal). | full |
| candidates | No | Untrusted intermediate certificates the path may use (every PEM block of every item is taken). Optional; the certificates embedded in a CMS message are also candidates. | |
| serverName | No | The identity the leaf must be valid for (RFC 6125): exactly one of host / ip. | |
| trustAnchors | Yes | Trust anchors (root certificates you trust) (every PEM block of every item is taken). At least one is required: a verdict is relative to the anchors you name. | |
| encodingRules | No | 'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write). | der |
| ocspResponses | No | OCSP responses (DER) for offline revocation (every PEM block of every item is taken). Optional; this server never queries a responder — pass the bytes you obtained. | |
| requireOcspNonce | No | Refuse an OCSP response that does not echo the nonce. | |
| requireRevocation | No | Require fresh revocation evidence for the end-entity certificate (PKI_REASON_REVOCATION_UNKNOWN otherwise — the engine demands it for the leaf; an intermediate is judged from the evidence you pass); default false = revocation is checked when evidence is given. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | The path found, leaf first, up to (and including) the trust anchor. | |
| valid | No | The verdict. false is a negative verdict (reasons[]), never an error. | |
| reasons | No | Why the verdict is negative (empty when valid): the engine PKI_REASON_* codes, each with the standard it cites and the path of the offending element. A reason is returned, never thrown. | |
| explored | No | Candidate paths explored (bounded by limits.maxPathsExplored). | |
| pathLength | No | ||
| diagnostics | No | Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one). | |
| evaluatedAt | No | The ISO instant the verdict was evaluated at — re-pass it as `at` to reproduce the verdict. | |
| reasonCodes | No | ||
| diagnosticCount | No | ||
| diagnosticCounts | No | Occurrences per diagnostic code. | |
| evaluatedAtSource | No | ||
| revocationEvidence | No | ||
| diagnosticsTruncated | No | true when distinct diagnostics beyond the 200 listed were dropped. | |
| signatureVerifications | No |