Skip to content

Add certificate validation events (1/6: core) - #11972

Open
sameehj wants to merge 1 commit into
wolfSSL:masterfrom
sameehj:cert-events-skeleton
Open

sameehj wants to merge 1 commit into
wolfSSL:masterfrom
sameehj:cert-events-skeleton

Conversation

@sameehj

@sameehj sameehj commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds an optional callback that reports what happened while wolfSSL checked a
certificate. It is for security logging: an application can log each failed
check with a stable code. Regulations and standards such as the EU Cyber
Resilience Act and IEC 62351 ask for this kind of logging. Today the
application gets one error code for a whole chain and cannot tell which
certificate, field or check failed.

Fixes zd#21876

Built with --enable-cert-events (WOLFSSL_CERT_EVENTS); off by default,
included in --enable-all. When off, no struct field or ABI changes. This PR
adds no error codes.

Stack

As requested in review, this work is now a stack of PRs. Each PR targets
master and holds one commit on top of the PR before it. Review only the top
commit of each PR. Merge them in order.

  1. This PR: the event struct, the certificate manager and WOLFSSL_CTX
    setters, DEFECT and RESULT events on the TLS peer chain and
    wolfSSL_CertManagerVerify*(), template ASN.1 parser only, with the
    conditions SEL asked for.
  2. #12155: X509_verify_cert(), trust anchors, parsing without a
    certificate manager.
  3. CRL events (to come).
  4. INFO events: algorithms and key size (to come).
  5. Strict profile checks and their 6 new error codes (to come).
  6. Field-level events from asn_orig.c (to come, if wanted).

What the callback receives

One WOLFSSL_CERT_EVENT per event:

  • DEFECT: one certificate check failed. Gives the certificate's role
    (peer or CA in the chain) and chain depth, the RFC 5280 field, the reason
    (malformed, missing, unsupported, expired, signature, no signer, revoked,
    policy, constraint), and the wolfSSL error code.
  • RESULT: one verification finished; error is 0 when it passed. A
    DEFECT followed by a passed RESULT means the verify callback allowed it.
    A TLS 1.2 client that asked for the server's certificate status sends it
    once that status was checked at ServerHelloDone, since revocation can
    still fail there.

Every event carries a condition value: a stable key for each kind of
failure, named after the IEC 62351-9 and IEC 62351-3 audit events. Extension
OIDs come as content octets as well as OID sums, because the sums depend on
the build.

Each event also says which certificate it is about (subject, issuer, serial
number, when decoded) and, during a handshake, the WOLFSSL* connection, so
a log line can be tied to a peer. Host name and OCSP failures appear only in
the RESULT's error for now.

The callback only observes. The verify callback still decides; nothing about
accepting or rejecting a certificate changes.

API

  • wolfSSL_CertManagerSetCertEventCb()
  • wolfSSL_CTX_SetCertEventCb()

Paths covered

TLS peer chains (each certificate with its depth) and
wolfSSL_CertManagerVerify*(). Field-level DEFECTs come from the template
ASN.1 parser. With --enable-asn=original it builds, and the RESULT and the
chain-level DEFECTs still come.

FIPS

The hooks are in asn.c, internal.c, ssl_certman.c and ssl_api_cert.c. No
FIPS module source changed.

Found while checking the RFC 5280 rules, to be fixed on their own: a
certificate version value of 3 is accepted, and a valid critical
certificatePolicies, policyConstraints or inhibitAnyPolicy extension is
rejected in the default build.

Testing

  • certs/test/gen-cert-events.py (Python 3 and the openssl command line)
    generates certs/test/cert-events/: copies of server-cert.der with one
    defect each, and chains with one fault each. All valid until 2049.
  • 8 tests in tests/api/test_certman.c, over the certificate manager and
    TLS (memio), with at least one for each condition this PR reports. Includes
    a regression test that the RESULT waits for the TLS 1.2 certificate status.
  • Built and tested locally with: --enable-cert-events --enable-crl;
    --enable-cert-events with WOLFSSL_X509_TINY; --enable-all (full API
    suite). All with -Werror -Wdeclaration-after-statement. Built only:
    --enable-asn=original (the event tests skip there), events off, and
    --enable-all --disable-cert-events.
  • Two new CI entries in os-check-linux.json: cert-events-crl and
    cert-events-tiny. --enable-all entries already cover the rest.

Checklist

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

Copilot AI balanced review requested due to automatic review settings November 3, 2026 14:42
@sameehj
sameehj requested review from MarkAtwood and dgarske November 3, 2026 14:44
@sameehj sameehj self-assigned this Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 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

Unresolved critical findings allow strict-error overrides to bypass additional enforced checks and revocation validation, or report a successful CA load without installing the CA.

6 open issues
What changed in this PR

Adds optional certificate and CRL validation events to wolfSSL for structured security logging, alongside configurable strict-profile checks.

Changes:

  • Introduces event callbacks with stable condition codes, certificate identity, algorithm details, and verification outcomes.
  • Integrates reporting and strict checks into certificate parsing, TLS, certificate-manager, X509-store, and CRL paths.
  • Adds build options, API documentation, test registrations, certificate fixtures, and CI configurations.
File Description
wolfssl/​wolfcrypt/​error-crypt.h Defines six strict-check error codes.
wolfssl/​wolfcrypt/​asn.h Adds parser event state and helper declarations.
wolfssl/​wolfcrypt/​asn_public.h Defines public event types and strict-check flags.
wolfssl/​ssl.h Declares event callback and enforcement APIs.
wolfssl/​internal.h Adds certificate-manager and handshake event state.
wolfcrypt/​src/​error.c Adds strict-check error strings.
wolfcrypt/​src/​asn.c Implements event reporting and strict certificate checks.
wolfcrypt/​src/​asn_orig.c Adds original-parser failure reporting.
tests/​api/​test_certman.h Registers certificate-event tests.
src/​x509_str.c Integrates events into X509-store verification.
src/​ssl_certman.c Adds manager APIs and verification events.
src/​ssl_api_cert.c Exposes TLS-context configuration APIs.
src/​internal.c Reports TLS certificate events and deferred status results.
src/​crl.c Adds CRL events and strict thisUpdate checks.
doc/​dox_comments/​header_files/​ssl.h Documents manager, context, and store APIs.
doc/​dox_comments/​header_files/​asn_public.h Documents standalone parser APIs.
configure.ac Adds the Autotools feature option.
CMakeLists.txt Adds the CMake feature option.
cmake/​options.h.in Exports the event feature define.
ChangeLog.md Describes validation events and strict checks.
certs/​test/​include.am Includes event fixtures in source distributions.
certs/​test/​gen-cert-events.py Generates certificate, chain, and CRL fixtures.
certs/​test/​cert-events/​chain-signer-not-ca.pem Tests a signer without CA status.
certs/​test/​cert-events/​chain-signer-no-certsign.pem Tests missing certificate-signing permission.
certs/​test/​cert-events/​chain-pathlen-exceeded.pem Tests a path-length violation.
certs/​test/​cert-events/​chain-leaf-ku-no-digsig.pem Tests missing leaf digital-signature usage.
certs/​test/​cert-events/​chain-leaf-eku-client-only.pem Tests a server leaf restricted to client authentication.
certs/​test/​cert-events/​chain-good.pem Provides a valid reference chain.
certs/​test/​catalog.txt Describes fixtures and regeneration.
.github/​configs/​os-check-linux.json Adds three certificate-event CI configurations.

Review effort: Balanced

Comment thread src/ssl_certman.c Resolved
Comment thread src/ssl_certman.c Resolved
Comment thread wolfcrypt/src/asn.c Resolved
Comment thread CMakeLists.txt Resolved
Comment thread src/crl.c Resolved
Comment thread wolfcrypt/src/asn.c Resolved
@sameehj
sameehj removed the request for review from dgarske November 3, 2026 15:36
@MarkAtwood

Copy link
Copy Markdown
Contributor

this is too big to review as one 5.3k line commit, can you split it into a stack? rough cut: 1) event struct, cm/ctx setters, defect+result on the tls peer chain and CertManagerVerify, template asn.c only, with the sel conditions. 2) x509_store, trust anchor load, no-cm parsing. 3) crl. 4) info events. 5) asn_orig parity. 6) strict checks and the 6 new error codes, those change accept/reject so they need their own review and maybe aren't needed for zd 21876. i'll review 1 first. after your vacation is fine

@sameehj
sameehj force-pushed the cert-events-skeleton branch from f797ab9 to d80f4a1 Compare November 17, 2026 06:58
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>
@sameehj
sameehj force-pushed the cert-events-skeleton branch from 4e1e0c3 to 5d78f84 Compare November 17, 2026 12:22
@sameehj sameehj changed the title Add certificate validation events Add certificate validation events (1/6: core) Nov 17, 2026
@sameehj

sameehj commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

@mark-atwood Thanks for the review. I split this PR into a stack, as you asked. Each PR targets master and has one commit on top of the PR before it. Please review only the top commit of each PR.

  1. Add certificate validation events (1/6: core) #11972 (this PR, force-pushed): the event struct, the certificate manager and WOLFSSL_CTX setters, DEFECT and RESULT events on the TLS peer chain and CertManagerVerify*(), template asn.c only, with the SEL conditions. No new error codes. About 2.8k lines, of which about half are tests and docs.
  2. Add cert events for X509_STORE, trust anchors and parsing (2/6) #12155: X509_STORE, trust anchor load, parsing without a certificate manager. About 430 lines.
  3. CRL events.
  4. INFO events.
  5. Strict checks and the 6 new ASN_STRICT_*_E error codes. SEL confirmed that they want these.
  6. asn_orig.c parity.

I will open parts 3 to 5 when the parts below them are in review. The old full branch is still in my fork if you want to compare.

Where the Copilot fixes went:

  • CMake: WOLFSSL_ALL turns on WOLFSSL_CERT_EVENTS: part 1.
  • CRL check event reports a CRL signature or signer failure (listRet): part 3.
  • ECC key size in bits from the field prime (P-521 is 521): part 4.
  • The three strict-check fixes (each enforced check goes to the verify callback, the store applies them after the context CRLs, and a trust anchor that fails one is not handed to the verify callback): part 5.

One question: do you want part 6 at all? With --enable-asn=original, part 1 builds and still sends RESULT events and chain-level DEFECT events (no signer, not a CA, path length, key usage). Only the field-level DEFECT events need the template parser. Part 6 adds about 6 asn_orig.c hooks to bring that parser to the same level. If you prefer that the original parser stays as it is, I will drop part 6.

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.

3 participants