Skip to content

Drive non-blocking ML-DSA and ML-KEM from the TLS 1.3 handshake and fix encapsulate-only ML-KEM servers - #12146

Open
dgarske wants to merge 1 commit into
wolfSSL:masterfrom
dgarske:pq_tls_nonblock
Open

dgarske wants to merge 1 commit into
wolfSSL:masterfrom
dgarske:pq_tls_nonblock

Conversation

@dgarske

@dgarske dgarske commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Description

Follows #12052: the TLS 1.3 handshake now runs the non-blocking ML-DSA and ML-KEM operations a chunk per wolfSSL_AsyncPoll(), through the software async device (WOLFSSL_ASYNC_CRYPT_SW) that ECC, X25519, RSA and DH non-blocking already use.

What it adds

  • async.h / async.c, wc_mldsa.c, wc_mlkem.c - async-SW operation types and a prelude in the six public operations, active only when the key has a non-blocking context. As with X25519, the operation pends once and the poll completes it: wait with wc_AsyncWait(..., WC_ASYNC_FLAG_NONE) and do not call it again.
  • internal.c / tls13.c - MlDsaSign() / MlDsaVerify() for CertificateVerify, attaching the non-blocking context for the operation only.
  • tls.c - standalone and hybrid ML-KEM key shares, client and server, including resumption with a PSK key exchange. A pended operation keeps its key object and partial share on the key share entry.
  • configure.ac - --enable-mldsa=yes,nonblock and --enable-mlkem=yes,nonblock, auto-enabling asynccrypt-sw; rejects asynccrypt-sw with Intel QAT or Cavium.

Also fixes

  • tls.c - a TLS 1.3 server built with ML-KEM encapsulation only (--enable-mlkem=enc) failed every ML-KEM and hybrid handshake with ECC_PEERKEY_ERROR after its ServerHello: the server's no-op in TLSX_KeyShare_Process() was compiled only with decapsulation, so it fell through to the ECC handler.

Testing

  • test_tls13_pq_nonblock_async - ML-DSA-44 certificate with ML-KEM-768, SecP256r1MLKEM768 and X25519MLKEM768, full and resumed handshakes, asserting both sides pend.
  • test.c - each operation through the async device, checked against the blocking path.
  • pq-all.json row pq-nonblock-tls.
  • mlkem-encap-server.yml - an encapsulate-only server, blocking and non-blocking, against a full build's client for ML-KEM-768 and both hybrid groups.

@dgarske dgarske self-assigned this Nov 16, 2026
@dgarske
dgarske requested review from wolfSSL-Fenrir-bot and a balanced review from Copilot November 16, 2026 17:12
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

MemBrowse Memory Report · Explore what changed →

gcc-arm-cortex-m4-pq

  • FLASH: .text +64 B (+0.0%, 315,312 B / 1,048,576 B, total: 30% used)

gcc-arm-cortex-m7-pq

  • FLASH: .text +64 B (+0.0%, 316,144 B / 1,048,576 B, total: 30% used)

zephyr-frdm_rw612

  • FLASH: datas +16 B, log_const_area -8 B, rodata +104 B, text +12,168 B (+4.3%, 294,744 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

A critical issue allows non-blocking TLS with encoded-key storage, causing pending hybrid client decapsulation to leak the key/context and preventing retries from collecting the completed result.

1 open issue
What changed in this PR

Builds on #12052 by connecting chunked ML-DSA and ML-KEM operations to TLS 1.3 through the software async device, allowing handshake work to advance through wolfSSL_AsyncPoll().

Changes:

  • Adds async dispatch for ML-DSA and ML-KEM, with handshake state retained across pending operations.
  • Integrates ML-DSA CertificateVerify and standalone/hybrid ML-KEM key shares, including session resumption.
  • Adds configure options, backend compatibility checks, crypto tests, handshake tests, and CI coverage.
File Description
wolfssl/​wolfcrypt/​wc_mlkem.h Adds async key state and documents completion semantics.
wolfssl/​wolfcrypt/​wc_mldsa.h Adds async key state and documents completion semantics.
wolfssl/​wolfcrypt/​async.h Defines ML-DSA and ML-KEM async operations and markers.
wolfssl/​internal.h Declares ML-DSA handshake helpers and verification state.
wolfcrypt/​test/​test.c Adds software-async crypto checks against blocking operations.
wolfcrypt/​src/​wc_mlkem.c Adds async dispatch and device lifecycle handling.
wolfcrypt/​src/​wc_mldsa.c Adds async dispatch and device lifecycle handling.
wolfcrypt/​src/​async.c Dispatches pending ML-DSA and ML-KEM operations.
tests/​api/​test_tls13.h Registers the non-blocking handshake test.
tests/​api/​test_tls13.c Adds full and resumed post-quantum handshake tests.
src/​tls13.c Routes CertificateVerify through ML-DSA handshake helpers.
src/​tls.c Preserves ML-KEM keys and share data across pending operations.
src/​internal.c Manages ML-DSA non-blocking contexts and async handshake calls.
configure.ac Adds non-blocking options and rejects conflicting async backends.
.wolfssl_known_macro_extras Registers the new async opt-out macros.
.github/​configs/​pq-all.json Adds a non-blocking post-quantum TLS CI configuration.

Review effort: Balanced

Comment thread src/tls.c Resolved

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Fenrir Automated Review — PR #12146

Scan targets checked: wolfcrypt-src, wolfcrypt-bugs, wolfssl-src, wolfssl-bugs
Not reviewed (no scan target covers them): .github/configs/pq-all.json, .wolfssl_known_macro_extras, configure.ac, tests/api/test_tls13.h
Coverage: 11 of 12 in-scope changed file(s) opened by the reviewer; not opened: tests/api/test_tls13.c

Findings: 3
3 finding(s) posted as inline comments (see file-level comments below)

This review was generated automatically by Fenrir. Reported findings require changes before merge.

Review tier: Max

@dgarske dgarske changed the title Drive non-blocking ML-DSA and ML-KEM from the TLS 1.3 handshake Drive non-blocking ML-DSA and ML-KEM from the TLS 1.3 handshake and fix encapsulate-only ML-KEM servers Nov 16, 2026
@dgarske
dgarske requested review from wolfSSL-Fenrir-bot and a balanced review from Copilot November 16, 2026 18:30

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

Terminal ML-DSA verification errors leave stale async state that can break subsequent operations, and TLS 1.3 test guards incorrectly require async behavior in valid opt-out builds.

2 open issues
1 resolved since last review

Review effort: Balanced

Comment thread tests/api/test_tls13.c Resolved
Comment thread wolfcrypt/src/async.c Resolved

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Fenrir Automated Review — PR #12146

⚠️ An internal error occurred during the automated review. This error has been logged. Please contact the Fenrir team if you need assistance.

Error: TimeoutExpired

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Fenrir Automated Review — PR #12146

Scan targets checked: wolfcrypt-src, wolfcrypt-bugs, wolfssl-src, wolfssl-bugs
Not reviewed (no scan target covers them): .github/configs/pq-all.json, .github/workflows/mlkem-encap-server.yml, .wolfssl_known_macro_extras, configure.ac, tests/api/test_tls13.h
Coverage: 4 of 5 in-scope changed file(s) opened by the reviewer; not opened: 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

@wolfSSL-Fenrir-bot
wolfSSL-Fenrir-bot dismissed their stale review November 16, 2026 19:12

Fenrir's latest completed scan found no issues; clearing the prior automated change request.

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