mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-07-05 09:30:51 +02:00
Tobias Frauenschläger
79b30aa268
Add a new option to require that an external Pre-Shared Key is negotiated for a handshake to succeed, configured via the new APIs wolfSSL_CTX_require_psk()/wolfSSL_require_psk(). When set, a handshake that completes without negotiating an external PSK is aborted with PSK_MISSING_ERROR instead of falling back to a certificate handshake, so the PSK acts as an additional security factor. This is a TLS 1.3 / DTLS 1.3 feature. In (D)TLS 1.2 the use of a PSK is determined by the negotiated cipher suite, so a mandatory PSK is instead configured there by restricting the cipher suite list to PSK suites; the new APIs therefore reject non-TLS-1.3 contexts with BAD_FUNC_ARG. To keep the requirement fail-closed, the APIs also disable version downgrade on the object so a downgrade-capable context (e.g. one created from a v23 method) cannot silently fall back to (D)TLS 1.2 and complete without a PSK; a peer that does not support (D)TLS 1.3 fails to connect. The requirement applies to external PSKs only (not session tickets): session-ticket resumption is exempt. To preserve forward secrecy a mandatory external PSK must also use an (EC)DHE key exchange; a pure psk_ke handshake is rejected with PSK_KEY_ERROR. When used with WOLFSSL_CERT_WITH_EXTERN_PSK, it also ensures that peers are properly authenticated with both the PSK and via certificates. The new APIs live alongside the existing wolfSSL_[CTX_]no_dhe_psk()/ only_dhe_psk() PSK options and do not depend on certificate support, so the feature is usable in NO_CERTS (PSK-only) builds. Added unit tests for the new APIs and enforcement.
The wolfSSL manual is available at: http://www.wolfssl.com/documentation/wolfSSL-Manual.pdf The wolfSSL API guide is available at: https://www.wolfssl.com/doxygen/wolfssl_API.html The wolfCrypt API guide is available at: https://www.wolfssl.com/doxygen/wolfcrypt_API.html