Enable support for mandatory PSKs#10745
Merged
Merged
Conversation
|
Frauschi
force-pushed
the
mandatory_psk
branch
2 times, most recently
from
a2ced8c to
cddfe34
Compare
Contributor
Author
|
Jenkins retest this please |
wolfSSL-Fenrir-bot
left a comment
wolfSSL-Fenrir-bot
left a comment
There was a problem hiding this comment.
Fenrir Automated Review — PR #10745
Scan targets checked: wolfcrypt-rs-bugs, wolfssl-bugs, wolfssl-src
No new issues found in the changed files. ✅
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.
douzzer
approved these changes
Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add new APIs,
wolfSSL_CTX_require_psk()/wolfSSL_require_psk(), to require that an external Pre-Shared Key is negotiated for a (D)TLS 1.3 handshake to succeed. When set on an endpoint that has a PSK callback registered, a handshake that completes without negotiating an external PSK is aborted with the new errorPSK_MISSING_ERRORinstead of falling back to a certificate handshake.This is relevant for external PSKs only (not session tickets) to make sure the PSKs are used as an additional security factor (together with (EC)DHE key exchange). Session-ticket resumption is exempt, and to preserve forward secrecy, a pure
psk_kehandshake is rejected withPSK_KEY_ERROR. When used withWOLFSSL_CERT_WITH_EXTERN_PSK, it also makes sure that peers are properly authenticated with both the PSK and via certificates.The new APIs sit alongside the existing
wolfSSL_[CTX_]no_dhe_psk()/wolfSSL_[CTX_]only_dhe_psk()PSK options and do not depend on certificate support, so the feature is also usable in NO_CERTS (PSK-only) builds. They apply to (D)TLS 1.3 only and returnBAD_FUNC_ARGfor a non-TLS-1.3 context.In (D)TLS 1.2 the use of a PSK is encoded directly in the negotiated cipher suite, so a mandatory PSK is enforced simply by restricting the cipher suite list to (preferably (EC)DHE-)PSK suites.
Fixes zd#22012.
Testing
Added unit tests for the new option.
Checklist