Repository navigation
Conversation
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().
4 tasks done
|
Contributor
There was a problem hiding this comment.
🟡 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 on lines
+3409
to
+3410
| wc_SetCertEventCallback(cert, cm->certEventCb, cm->certEventCtx); | ||
| wc_CertEventSetPosition(cert, WC_CEV_ROLE_TRUST_ANCHOR, -1); |
| 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 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 on lines
+711
to
+712
| if (ret != WOLFSSL_SUCCESS) { | ||
| evErr = ret; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

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 thecallback 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 itbuilds the chain, one verification can send several RESULTs; use its
return value for the verdict.
defects in the trust anchor role.
wc_SetCertEventCallback()sets the callbackon a
DecodedCertbeforewc_ParseCert(). In Add certificate validation events (1/6: core) #11972 this function isinternal; this PR makes it public.
No new error codes. The callback still only observes.
Testing
tests/api/test_certman.c:test_wolfSSL_X509_STORE_CertEvents,test_wolfSSL_CertEvents_trustAnchorand
test_wolfSSL_CertEvents_noCertManager.--enable-cert-events --enable-crl; withWOLFSSL_X509_TINY;--enable-all; built only with--enable-asn=originaland events off.Checklist