Support for importing external PSKs (RFC 9258)

[Frauschi]

Summary

Adds support for importing external PSKs for TLS 1.3 per RFC 9258, gated behind WOLFSSL_EXTERNAL_PSK_IMPORTER. This is a port of commit 3d5c9e3 from the Laboratory-for-Safe-and-Secure-Systems fork onto current master, adapted to upstream APIs and hardened.

The importer transforms an external PSK (EPSK) — external identity, optional context, base key — into the ImportedIdentity carried on the wire and the internal (imported) PSK used in the handshake.

What's included

• New client/server importer callback interface (in addition to the existing TLS 1.3 PSK callbacks).
• ImportedIdentity (external_identity, context, target_protocol, target_kdf) construction/serialization on the client and parsing on the server.
• Imported-PSK derivation per RFC 9258 §3.1:
  epskx = HKDF-Extract(0, epsk) then
  ipskx = HKDF-Expand-Label(epskx, "derived psk", Hash(ImportedIdentity), L),
  with L = target_kdf output length.
• "imp binder" binder-key label for imported PSKs (§5).
• Pre-extracted EPSK support (wolfSSL_external_psk_pre_extracted) — skips HKDF-Extract.
• Configurable EPSK hash: the importer hash defaults to SHA-256 (the RFC 9258 default) and is settable per-EPSK via the callbacks' int* hashAlgo argument (pre-initialized to WC_SHA256). The whole derivation — Hash(ImportedIdentity) + HKDF — honors devId/CryptoCb.
• Build plumbing: --enable-psk-importer (autotools) and the CMake/options.h.in equivalents.

API (behind WOLFSSL_EXTERNAL_PSK_IMPORTER)

typedef int (*wc_psk_client_importer_callback)(WOLFSSL* ssl,
    unsigned char* identity, word32* identitySz,
    unsigned char* context, word32* contextSz,
    unsigned char* key, word32* keySz, int* hashAlgo);
typedef int (*wc_psk_server_importer_callback)(WOLFSSL* ssl,
    const unsigned char* identity, word32 identitySz,
    const unsigned char* context, word32 contextSz,
    unsigned char* key, word32* keySz, int* hashAlgo);

void wolfSSL_CTX_set_psk_client_importer_callback(WOLFSSL_CTX*, wc_psk_client_importer_callback);
void wolfSSL_set_psk_client_importer_callback(WOLFSSL*, wc_psk_client_importer_callback);
void wolfSSL_CTX_set_psk_server_importer_callback(WOLFSSL_CTX*, wc_psk_server_importer_callback);
void wolfSSL_set_psk_server_importer_callback(WOLFSSL*, wc_psk_server_importer_callback);
int  wolfSSL_external_psk_pre_extracted(WOLFSSL* ssl, int opt);

Identity, context and key are opaque, length-delimited buffers (each *Sz is capacity-in / length-out), so identities may contain arbitrary bytes per the RFC.

Notable adaptations vs. the source commit

• Retargeted the derivation from the fork's streaming Hkdf struct API (not in master) to master's functional wc_HKDF_*_ex API, preserving devId support.
• Dropped the PKCS#11 key-by-id/label external-key path (it depended on the un-upstreamed streaming HKDF + PKCS#11 V3.0 work); pre-extracted EPSK support is retained.

RFC 9258 compliance

Audited against the RFC; compliant on the cryptographic essentials — ImportedIdentity layout, the "derived psk" Expand-Label with L = target-KDF length, epskx = HKDF-Extract(0, epsk), the "imp binder" label, the KDF registry values (HKDF_SHA256/HKDF_SHA384), and the EPSK-associated importer hash (default SHA-256, now configurable). Imported PSKs are treated as external (non-resumption, obfuscated_ticket_age = 0). The server also validates target_protocol/target_kdf against what's negotiated.

DTLS 1.3 is outside the RFC's scope; the implementation is self-consistent there but uses the "dtls13" protocol label.

Hardening (from review)

• Reject a zero-length external_identity when parsing (removes an unauthenticated server NULL-pointer write).
• Server passes the received identity/context as opaque (ptr,len) — no buffer mutation, no heap copy.
• Client deduplicates by target KDF (one IPSK per KDF) and skips suites whose MAC isn't a defined RFC 9258 KDF.
• Derived-key buffers registered with WOLFSSL_CHECK_MEM_ZERO.

Tests

tests/api.c:

• Memio handshake covering SHA-256 and SHA-384 target KDFs, with/without context, pre-extracted, and a non-default (SHA-384-associated) EPSK hash. Runs in PSK-only / no-certificate builds too.
• Negative binder-mismatch handshake.
• Direct ImportedIdentity (de)serialization unit test covering empty-identity, truncated, length-overflow, and bad-KDF inputs.

Verification

Builds clean (-Werror) with: feature on, feature off (default), WOLFSSL_CHECK_MEM_ZERO + WOLFSSL_SMALL_STACK, DTLS 1.3, and a no-SHA384 build. ./tests/unit.test passes with 0 failures.

🤖 Generated with Claude Code

---

Generated by Claude Code