[LinuxJedi]

Summary

With KEEP_PEER_CERT, which OPENSSL_EXTRA, OPENSSL_ALL and the
application recipes turn on, every WOLFSSL embeds a whole WOLFSSL_X509
for the peer's certificate (3.4 KB on Cortex-M33, 4.3 KB with
OPENSSL_ALL), and InitSSL() zeroes it. It is paid for even when there is
no peer certificate: servers that do not ask for client authentication, PSK
connections, and every object before its handshake.

This adds WOLFSSL_DYNAMIC_PEER_CERT. With it, ssl->peerCert is a pointer,
NULL until a certificate is kept, and the WOLFSSL holds one reference. A
new certificate (renegotiation, wolfSSL_clear() and a new handshake, a
certificate restored from a ticket) replaces the object instead of reusing
it, so a reference handed out stays valid, also after wolfSSL_free().
With X509 reference counting (OPENSSL_EXTRA or OPENSSL_EXTRA_X509_SMALL),
wolfSSL_get_peer_certificate() returns the kept object with a new
reference, as OpenSSL does, instead of a copy that parses the DER again.

Gating and defaults

• On by default when KEEP_PEER_CERT and WOLFSSL_SMALL_STACK are defined,
  as large objects then already go on the heap (--enable-smallstack, or
  WOLFSSL_SMALL_STACK in user_settings.h). Default configure builds are
  unchanged.
• NO_WOLFSSL_DYNAMIC_PEER_CERT keeps the embedded object.
• Defining WOLFSSL_DYNAMIC_PEER_CERT turns it on without
  WOLFSSL_SMALL_STACK.
• Always off with WOLFSSL_NO_MALLOC, even if defined, as the certificate
  could not be allocated and so would never be kept. Undefined without
  KEEP_PEER_CERT.
• With the flag off the certificate stays embedded and behaves as before,
  including ReinitX509() and wolfSSL_get_peer_certificate() returning a
  copy.

The names (WOLFSSL_DYNAMIC_PEER_CERT, NO_WOLFSSL_DYNAMIC_PEER_CERT,
GetPeerCert(), FreePeerCert(), SetPeerCert()) match dgarske's
ossl_lowmem branch. Internal code reaches the certificate through
GetPeerCert(ssl) in either mode.

Other changes

• The leaf is copied, and with the flag on allocated, once per handshake,
  in SetupStoreCtxCallback() or ProcessPeerCerts() (peerCertSet).
• wolfSSL_get0_verified_chain() uses the kept certificate directly
  instead of taking a reference or copy and dropping it.
• TLS 1.3 dual-algorithm CertificateVerify returns PEER_KEY_ERROR when no
  peer certificate is kept.
• The wolfSSL_get_peer_certificate() Doxygen describes both modes.

Measurements

Memory harness, STM32U585 (Cortex-M33), ECC, no client auth on the server,
heap in bytes, before -> after. The harness settings define
WOLFSSL_SMALL_STACK, so the flag is on. Measured on the first version of
this change (#11925), which always used the heap pointer and matches this
PR with the flag on.

	OPENSSL_EXTRA	OPENSSL_ALL
sizeof(WOLFSSL)	4560 -> 1144	5576 -> 1304
server connection, resident	6842 -> 3426 (-50%)	12366 -> 8094 (-35%)
server wolfSSL_new()	7292 -> 3876	16916 -> 12644
client wolfSSL_new()	7726 -> 4310	14914 -> 10642
client peak, wolfSSL_new() + handshake	23694 -> 23692	34290 -> 34289
client connection, resident	13961 -> 13961	23276 -> 23276
flash	394440 -> 393152	409184 -> 407616

Client handshake and resumption times are unchanged. On x86_64,
sizeof(WOLFSSL) goes 5632 -> 1552 (EXTRA) and 6976 -> 1752 (ALL), and the
resident server connection 7986 -> 3906 and 13898 -> 8674.

Testing

• make check with the flag on and off: --enable-opensslextra,
  --enable-opensslall, --enable-all, and
  --enable-opensslextra=x509small with -DKEEP_PEER_CERT.
• Library builds: --enable-staticmemory with WOLFSSL_NO_MALLOC and the
  flag requested (it resolves off), --enable-smallstack (on by default),
  and NO_WOLFSSL_DYNAMIC_PEER_CERT (off).
• New test_wolfSSL_get_peer_certificate_ref covers both modes: no
  certificate before the handshake, none kept by a server without client
  auth, reference counts with the flag on and separate copies with it off,
  and a returned certificate that outlives wolfSSL_clear() plus a new
  handshake and wolfSSL_free(). It needs OPENSSL_EXTRA, so the x509small
  builds skip it.

Related

• Follows Reduce OpenSSL compat layer heap use and time when parsing certificates #11914 (merged) and replaces Keep the TLS peer certificate as a reference-counted heap object #11925 (closed). Not stacked on
  anything.
• Rebased on master after Size session ticket buffers for tickets without a peer cert #11991 (ticket sizing) and Reduce X509_NAME memory in the OpenSSL compat layer and fill in CA name lists #11992 (names) were
  merged. CreateTicket() now reads the certificate through
  GetPeerCert(ssl) in Size session ticket buffers for tickets without a peer cert #11991's sizing code.

[github-actions]

MemBrowse Memory Report · Explore what changed →

gcc-arm-cortex-m4-openssl-compat

• FLASH: .text -832 B (-0.1%, 800,484 B / 1,048,576 B, total: 76% used)

zephyr-frdm_rw612

• FLASH: log_const_area -8 B, rodata -8 B, text +1,544 B (+0.5%, 283,992 B / 67,108,864 B, total: 0% used)

No memory changes detected for:

• gcc-arm-cortex-m0plus
• gcc-arm-cortex-m3
• gcc-arm-cortex-m4
• gcc-arm-cortex-m4-baremetal
• gcc-arm-cortex-m4-crypto-only
• gcc-arm-cortex-m4-dtls13
• gcc-arm-cortex-m4-min-ecc
• gcc-arm-cortex-m4-pkcs7
• gcc-arm-cortex-m4-pq
• gcc-arm-cortex-m4-rsa-only
• gcc-arm-cortex-m4-sp-math
• gcc-arm-cortex-m4-tls12
• gcc-arm-cortex-m4-tls13
• gcc-arm-cortex-m7
• gcc-arm-cortex-m7-pq
• gcc-arm-cortex-m7-tls13
• stm32-sim-stm32h753

---

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

[Copilot]

🟡 Changes recommended

Shared peer certificates can trigger premature ex-data cleanup while retained references remain alive, and the new test incorrectly uses PEM loading for DER fixtures.

2 open issues

• Defer ex-data cleanup until the final certificate reference is freed · New
• Use the fixture's file type when loading the server certificate · New

What changed in this PR

Adds optional heap allocation for TLS peer certificates, reducing per-connection memory use when no certificate is kept. This extends the earlier certificate-parsing optimizations while preserving embedded storage when the feature is disabled.

Changes:

• Adds WOLFSSL_DYNAMIC_PEER_CERT, enabled by default for eligible small-stack builds.
• Centralizes certificate ownership and access, returning shared references where supported.
• Adds lifetime tests and documents reference-versus-copy behavior.

File	Description
wolfssl/​wolfcrypt/​settings.h	Defines feature defaults and allocation constraints.
wolfssl/​internal.h	Adds optional pointer storage and certificate helpers.
tests/​api/​test_tls13.c	Adapts ticket verification assertions for pointer storage.
tests/​api/​test_ssl_cert.h	Registers the new certificate lifetime test.
tests/​api/​test_ssl_cert.c	Tests ownership, reference counts, and certificate lifetime.
src/​tls13.c	Uses certificate access helpers and checks for missing certificates.
src/​ssl.c	Updates peer-name access and certificate clearing.
src/​ssl_api_cert.c	Supports shared references and direct verified-chain access.
src/​internal.c	Implements allocation, replacement, and release helpers.
doc/​dox_comments/​header_files/​ssl.h	Documents ownership and required certificate cleanup.
.wolfssl_known_macro_extras	Registers the feature and opt-out macros.

_{Review effort: Balanced}

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #11990

Scan targets checked: wolfcrypt-src, wolfcrypt-bugs, wolfssl-src, wolfssl-bugs
Not reviewed (no scan target covers them): .wolfssl_known_macro_extras, doc/dox_comments/header_files/ssl.h, tests/api/test_ssl_cert.h
Coverage: 7 of 9 in-scope changed file(s) opened by the reviewer; not opened: tests/api/test_ssl_cert.c, tests/api/test_tls13.c

Fenrir result: Approved ✅

No new issues found in the changed files.

Advisory only — this automated result does not count as a GitHub approval.

Review tier: Lite

[dgarske]

Jenkins CI seems unhappy with Valgrind and openssl

[LinuxJedi]

The Jenkins failures on this run also hit other PRs since #11991 and #11992
merged, so they come from master rather than this change:

• PRB-valgrind-check-v3: the --enable-opensslall,
  --enable-opensslall --enable-sniffer and
  --enable-openssh --enable-lighty --enable-stunnel branches fail on
  "still reachable" blocks allocated in AddSessionToCache(). These are
  session tickets that carry the peer cert, which are now heap allocated in
  the cache after Size session ticket buffers for tickets without a peer cert #11991's ticket sizing. unit.test passes and valgrind
  reports 0 errors. The same failure is on percent decode in URIs and enforce LDH #12003, x86_64 asm: load 32-bit parameters as 32-bit and ArrowLake/LunarLake change #11986, Pq fs 2026 part4 lab prep sha512 fixes #11983, F-13114 adjustment to AES-CBC autosar output length #11995,
  Add bounds check before word32 cast #12005 and Fix compressed ECC point decompression for secp224k1 and reject an x with no square root #11982.
• PRB-generic-config-parser and PRB-fips-ready-config:
  -Werror=maybe-uninitialized on dn/dnSz in Reduce X509_NAME memory in the OpenSSL compat layer and fill in CA name lists #11992's
  test_ca_names_sent_case. generic-config-parser fails the same way on
  PKCS7: reject ANY-typed eContent with trailing bytes after the first element #11963, Fix compressed ECC point decompression for secp224k1 and reject an x with no square root #11982, Add bounds check before word32 cast #12005, Pq fs 2026 part4 lab prep sha512 fixes #11983 and x86_64 asm: load 32-bit parameters as 32-bit and ArrowLake/LunarLake change #11986.

Both need a fix on master; this PR can be retested once those land.

[LinuxJedi]

Jenkins: retest this please