docs: add WPA3-SAE (PSA Crypto API 1.4) design proposal

[krish2718]

This adds a Phase 0 design proposal (docs/proposed/wpa3-sae.md) for
implementing the WPA3-SAE PAKE from the PSA Certified Crypto API 1.4
(§10.13.12–13) in the built-in driver.

It is a design note for discussion — no implementation code — intended
to reach agreement on scope, API surface, new primitives, constant-time
strategy, and PR phasing before any code is written. Relates to #709.

What it covers

• Scope: hash-to-element only; ECC groups 19/20/21; FFDH via
  PSA_DH_FAMILY_RFC3526; the FIXED and GDH algorithm variants and the
  WPA3_SAE_H2E KDF. Protocol-level concerns (anti-clogging, group
  negotiation, SAE-PK, mesh) are out of scope — they belong in the Wi-Fi stack.
• API surface from the 1.4 spec, with section citations.
• New primitives: RFC 9380 hash-to-curve (Simplified SWU), a constant-time
  modular square root, and the SAE engine.
• Constant-time strategy, per secret-dependent step (Dragonblood is the
  motivating threat).
• Test plan and a proposed P1–P5 PR phasing.

Open questions for maintainers (see §9 of the note)

1. FFDH group set — the 1.4 spec only defines PSA_DH_FAMILY_RFC3526
   (IANA 15–18) for SAE FFDH tokens; confirm this is the intended set.
2. Looping variant — proposal is to not implement it (no constant-time
   PWE; H2E supersedes it) and return PSA_ERROR_NOT_SUPPORTED.
3. Built-in vs driver-only — proposal is a full built-in implementation
   (SPAKE2+ is currently API-encoding-only).

Related

• Spec example errata found during this work are filed as
  Fix incorrect identifiers in PAKE operation example code GlobalPlatform/psa-api#372.

[gilles-peskine-arm]

Thank you for providing a detailed design plan.

I've reviewed it as someone who is familiar with PSA APIs in general and with TF-PSA-Crypto as a product, but not with the PAKE API and not with the WPA3 algorithm family. In particular, I have not confronted the proposal with the WPA3 and related specifications.

[krish2718]

Thanks, this was a useful pass — all 16 points are in the updated note (force-pushed). Substantive changes:

• §7 phasing reworked: no vectors-only PR (tests land with the code they exercise), hash_to_curve.c and sae.c split into separate PRs, PSA_DH_FAMILY_RFC3526 as a standalone phase with no SAE code, constant-time annotations and documentation as per-phase rules rather than a trailing hardening pass, fuzzing last.
• §4.1: the modular square root is now a refactor of mbedtls_ecp_sw_derive_y() rather than new code.
• new §4.3 + open question 5: bignum abstraction level.

On that last one — the answer came out more definite than "open question" suggests, so flagging it here too: bignum_mod.h has no exponentiation, no conditional assign and no comparison, and its Montgomery representation breaks RFC 9380 sgn0, so the real choice is bignum_core.h vs extending bignum_mod.h first. We'd propose the former; detail in the thread on §4. That's the one thread I've left open for your call — the rest of the review is addressed and resolved.

The three maintainer-facing open questions (§9: FFDH group set, omitting Looping, built-in vs encoding-only) are unchanged and still open.

Unrelated: the spec example errata (#372) merged, targeted for 1.5.1 — the note now reflects that.

[gilles-peskine-arm]

Thanks for the update. I'm generally happy with the plan now, except that I'm unsure about bignum_core vs bignum_mod: the arguments given against bignum_mod feel very weak to me. It's hard for me to judge because I'm not at all familiar with the algorithm.

Do you have a reading suggestion (code or math+English) that would make it clear how the representation of numbers matter? Are all the numbers involved in the same $Z_p$, or is there a mix? At which steps are conversions to/from Montgomery form needed?

Note: when I say I'm happy with the plan, that's as a general plan for implementing some calculations as a new cryptographic mechanism in TF-PSA-Crypto. I'm not familiar with the WPA3-SAE family of algorithms, so I can't vouch for difficulties or incompleteness for implementing the desired algorithms.

[gilles-peskine-arm]

To be precise, the changes inside the framework are a separate PR since it's a separate repository. Updating the framework submodule in the TF-PSA-Crypto repository should be done in the TF-PSA-Crypto PR that needs it, but the need may go away if another TF-PSA-Crypto PR updates the framework for its own needs first.

[krish2718]

Understood — I'll fix §3 to say it precisely: the framework changes are a separate PR (separate repo), and the submodule bump lands in whichever TF-PSA-Crypto PR first needs it, so the "merged first" framing was too rigid.

[gilles-peskine-arm]

Many functions in the bignum modules and in the ecp module have automatically generated tests (framework/scripts/generate_bignum_tests.py, framework/scripts/generate_ecp_tests.py). If this work introduces new functions that should have automatically generated tests, we'll need to arrange. to add new tested functions

Because the framework code and the crypto code can't be updated atomically, the first time those scripts need to cover a new test function, this will require preliminary work to split the script into two parts:

• framework/scripts/mbedtls_framwork/xxx_generator.py having almost all the code.
• A small harness tests/scripts/generate_xxx.py that calls an entry point in the framework and passes it arguments that describe which test functions should be covered.
• For a transition period, framework/scripts/generate_xxx.py still exists. It calls tests/scripts/generate_xxx.py from the consuming branch if it exists, and otherwise generates test cases for the historical set of test functions.

See scripts/maintainer/generate_mldsa_tests.py and framework/util/mbedtls_maintainer/mldsa_test_generator.py for an example of this split. Note that the file paths are different for mldsa because it needs extra python packages, and that would break some validation scripts that we run on framework/scripts, scripts and tests/scripts; that doesn't apply for bignum and ecp.

[krish2718]

This is the real deciding factor now that capability isn't. If we go bignum_mod we're adding exp_mod (and probably cmp / cond-assign) as first-class bignum_mod functions, which per your note means doing the generator split — a mbedtls_framework/..._generator.py plus a thin tests/scripts/generate_*.py harness, transition shim and all — following the mldsa example. bignum_core already has all of these, so that path adds no bignum API and touches no generator.

So the choice is: grow bignum_mod properly (better long-term home, but the first code PR then also owns a bignum-module extension + the generator split), or keep the first SSWU PR tight on bignum_core and leave bignum_mod growth as separate future work. I lean toward doing it properly on bignum_mod since you'd want those functions eventually anyway — but you're better placed to say whether you want that coupled into the first SSWU PR or kept out of it. Either way I'll write it up to match.

[krish2718]

@gilles-peskine-arm — I answered your three questions (representation/reading, single-field vs mix, where the Montgomery conversions land) on the bignum thread rather than here so they wouldn't get buried: #837 (comment)

Short version: it's a single field (F_p) throughout hash_to_curve.c, conversions are in-once and out-only-at-sgn0, and I've dropped the objection — bignum_mod is a fine fit. The one open point is scope: grow bignum_mod (which pulls in the generator split) vs keep the first PR tight on bignum_core. Your call.

[gilles-peskine-arm]

LGTM at 986f205, with the caveat that I am not familiar with WPA3-SAE and I have not checked the plan against the specification of the mechanisms.

On bignum_core vs bignum_mod, I could go either way based on my knowledge. I'll ask a colleague who's more familiar with ECC math and the planned evolution of bignum and ECP modules.

[krish2718]

@gilles-peskine-arm Should I add any other reviewer to get this merged?

[gilles-peskine-arm]

We do need a second reviewer. But I have no idea when someone will be available or who it will be.

By the way, given the size of the contribution, have you made arrangements with our product management to have the review of the code scheduled? We currently have very little bandwidth since most of the team is triaging and fixing LLM-assisted vulnerability reports.