Skip to content

Add cert events for X509_STORE, trust anchors and parsing (2/6) - #12155

Open
sameehj wants to merge 2 commits into
wolfSSL:masterfrom
sameehj:cert-events/2-verify-paths
Open

sameehj wants to merge 2 commits into
wolfSSL:masterfrom
sameehj:cert-events/2-verify-paths

Conversation

@sameehj

@sameehj sameehj commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

Depends on #11972. Review only the top commit: "Add cert events for
X509_STORE, trust anchors and parsing".

Part 2 of the certificate validation events stack (zd#21876). See #11972 for
the event struct, the stack list and what each event holds.

This PR reports events from more verification paths:

  • X509_verify_cert(): wolfSSL_X509_STORE_SetCertEventCb() sets the
    callback on the store's certificate manager. Each certificate tried gets
    its chain depth, the same depth X509_STORE_CTX_get_error_depth() gives,
    and a RESULT after the date overrides, the context CRLs and the verify
    callback. As X509_verify_cert() tries several certificates while it
    builds the chain, one verification can send several RESULTs; use its
    return value for the verdict.
  • Trust anchors: a CA loaded as trusted with verification reports its
    defects in the trust anchor role.
  • No certificate manager: wc_SetCertEventCallback() sets the callback
    on a DecodedCert before wc_ParseCert(). In Add certificate validation events (1/6: core) #11972 this function is
    internal; this PR makes it public.

No new error codes. The callback still only observes.

Testing

  • 3 new tests in tests/api/test_certman.c:
    test_wolfSSL_X509_STORE_CertEvents, test_wolfSSL_CertEvents_trustAnchor
    and test_wolfSSL_CertEvents_noCertManager.
  • Built and tested locally with the same configurations as Add certificate validation events (1/6: core) #11972:
    --enable-cert-events --enable-crl; with WOLFSSL_X509_TINY;
    --enable-all; built only with --enable-asn=original and events off.

Checklist

  • added tests
  • updated/added doxygen
  • updated appropriate READMEs
  • Updated manual and documentation (ChangeLog.md)

Sameeh Jubran and others added 2 commits November 17, 2026 14:18
An optional callback that reports what happened while wolfSSL checked a
certificate, for security logging. Today an application gets one error
code for a whole chain and cannot tell which certificate, field or check
failed.

Built with --enable-cert-events (WOLFSSL_CERT_EVENTS, also in CMake and
--enable-all); off by default. When off, no struct or ABI changes.

Each WOLFSSL_CERT_EVENT says:
- kind: DEFECT for each failed certificate check, RESULT when a
  verification ends (0 when it passed, so a DEFECT then a passed RESULT
  means the verify callback allowed it).
- the certificate's role and chain depth, the RFC 5280 field, the reason
  and the error code.
- a stable condition value for each kind of failure, named after the
  IEC 62351-9 and IEC 62351-3 audit events.
- the extension OID as content octets, since OID sums depend on the build.
- which certificate: its subject, issuer and serial number, and the TLS
  connection.

Set with wolfSSL_CertManagerSetCertEventCb() or
wolfSSL_CTX_SetCertEventCb(). Events come from the TLS peer chain
(ProcessPeerCerts) and wolfSSL_CertManagerVerify*(). Field-level defects
come from the template ASN.1 parser. The callback only observes: it
cannot change a result, and the verify callback still decides.

Co-authored-by: Cursor <cursoragent@cursor.com>
Report certificate validation events from more verification paths:

- X509_verify_cert(): wolfSSL_X509_STORE_SetCertEventCb() sets the
  callback on the store's certificate manager. Each certificate tried
  gets its chain depth, the same depth X509_STORE_CTX_get_error_depth()
  gives, and a RESULT after the date overrides, the context CRLs and the
  verify callback.
- Trust anchors: a CA loaded as trusted with verification reports its
  defects in the trust anchor role.
- No certificate manager: wc_SetCertEventCallback() sets the callback on
  a DecodedCert before wc_ParseCert().
Copilot AI balanced review requested due to automatic review settings November 17, 2026 12:23
@sameehj sameehj changed the title Add cert events for X509_STORE, trust anchors and parsing Add cert events for X509_STORE, trust anchors and parsing (2/6) Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

MemBrowse Memory Report · Explore what changed →

gcc-arm-cortex-m0plus

  • FLASH: .text -4 B (-0.0%, 71,351 B / 262,144 B, total: 27% used)

gcc-arm-cortex-m4-openssl-compat

  • FLASH: .rodata +8 B (+0.0%, 805,644 B / 1,048,576 B, total: 77% used)

gcc-arm-cortex-m4-rsa-only

  • FLASH: .text -64 B (-0.0%, 345,512 B / 1,048,576 B, total: 33% used)

zephyr-frdm_rw612

  • FLASH: datas +16 B, log_const_area -8 B, rodata +104 B, text +12,184 B (+4.4%, 294,760 B / 67,108,864 B, total: 0% used)
  • RAM: bss +49 B, datas +16 B (+0.1%, 58,423 B / 983,040 B, total: 6% used)

No memory changes detected for:


Catch memory regressions in CI with MemBrowse. Free for open source.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Certificate verification events report incorrect chain depths, omit TLS connection context, and miss key-size and validity defects, leaving security logs incomplete or misleading.

4 open issues
What changed in this PR

Part 2 of the certificate-validation events stack extends the framework from #11972 to X509 store verification, verified trust-anchor loading, and parsing without a certificate manager. Events support security logging without changing certificate acceptance decisions.

Changes:

  • Adds store callback registration and per-certificate RESULT events after store checks and verification callbacks.
  • Reports trust-anchor defects and exposes wc_SetCertEventCallback() publicly.
  • Adds three API tests and documentation; the supplied diff also includes prerequisite infrastructure and fixtures.
File Description
wolfssl/​wolfcrypt/​asn.h Exposes parser callback registration and event state.
wolfssl/​wolfcrypt/​asn_public.h Defines event types, fields, and callback contract.
wolfssl/​ssl.h Declares event registration APIs, including the store setter.
wolfssl/​internal.h Declares depth-aware verification and event helpers.
wolfcrypt/​src/​asn.c Implements parser callback registration and defect reporting.
tests/​api/​test_certman.h Registers certificate-event tests.
tests/​api/​test_certman.c Tests store, trust-anchor, standalone parsing, and core events.
src/​x509_str.c Adds store registration and per-attempt event reporting.
src/​ssl_certman.c Adds depth-aware verification and trust-anchor callback setup.
src/​ssl_api_cert.c Provides TLS-context callback registration.
src/​internal.c Supplies prerequisite TLS event reporting and connection attribution.
doc/​dox_comments/​header_files/​ssl.h Documents registration APIs and store RESULT semantics.
doc/​dox_comments/​header_files/​asn_public.h Documents standalone parser callback usage.
configure.ac Provides the certificate-events build option.
CMakeLists.txt Adds corresponding CMake feature controls.
cmake/​options.h.in Exports the feature define to generated headers.
ChangeLog.md Summarizes the expanded event coverage.
certs/​test/​include.am Packages event-test fixtures and their generator.
certs/​test/​gen-cert-events.py Generates controlled certificate and chain defects.
certs/​test/​cert-events/​chain-signer-not-ca.pem Tests an issuer without CA status.
certs/​test/​cert-events/​chain-signer-no-certsign.pem Tests missing certificate-signing key usage.
certs/​test/​cert-events/​chain-pathlen-exceeded.pem Tests an exceeded path-length constraint.
certs/​test/​cert-events/​chain-leaf-ku-no-digsig.pem Tests a leaf lacking digital-signature usage.
certs/​test/​cert-events/​chain-leaf-eku-client-only.pem Tests a server certificate restricted to client authentication.
certs/​test/​cert-events/​chain-good.pem Supplies a valid baseline chain.
certs/​test/​catalog.txt Documents fixtures and regeneration instructions.
.github/​configs/​os-check-linux.json Adds event-enabled CRL and tiny-X509 CI configurations.

Review effort: Balanced

Comment thread src/ssl_certman.c
Comment on lines +3409 to +3410
wc_SetCertEventCallback(cert, cm->certEventCb, cm->certEventCtx);
wc_CertEventSetPosition(cert, WC_CEV_ROLE_TRUST_ANCHOR, -1);
Comment thread src/x509_str.c
int accepted = 0; /* callback accepted a cert that verified */
#ifdef WOLFSSL_CERT_EVENTS
/* Same depth as SetupStoreCtxError() records for this certificate. */
int depth = (ctx->chain != NULL) ? (int)ctx->chain->num : 0;
Comment thread src/x509_str.c
Comment on lines +669 to +672
ret = CM_VerifyBufferDepth(ctx->store->cm,
ctx->current_cert->derCert->buffer,
(long)ctx->current_cert->derCert->length,
WOLFSSL_FILETYPE_ASN1, depth, &crlRet);
Comment thread src/x509_str.c
Comment on lines +711 to +712
if (ret != WOLFSSL_SUCCESS) {
evErr = ret;
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants