Enable support for mandatory PSKs

[Frauschi]

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 error PSK_MISSING_ERROR instead 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_ke handshake is rejected with PSK_KEY_ERROR. When used with WOLFSSL_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 return BAD_FUNC_ARG for 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

• added tests
• updated/added doxygen
• updated appropriate READMEs
• Updated manual and documentation

[github-actions]

MemBrowse Memory Report

gcc-arm-cortex-m3

• FLASH: .text +16 B (+0.0%, 121,425 B / 262,144 B, total: 46% used)

gcc-arm-cortex-m4

• FLASH: .rodata.wolfSSL_ERR_reason_error_string.str1.1 +18 B (+0.0%, 199,070 B / 262,144 B, total: 76% used)

gcc-arm-cortex-m4-dtls13

• FLASH: .text +64 B (+0.0%, 179,864 B / 1,048,576 B, total: 17% used)

gcc-arm-cortex-m4-openssl-compat

• FLASH: .rodata +16 B, .text +320 B (+0.0%, 768,468 B / 1,048,576 B, total: 73% used)

gcc-arm-cortex-m4-pq

• FLASH: .rodata +24 B, .text +192 B (+0.1%, 278,152 B / 1,048,576 B, total: 27% used)

gcc-arm-cortex-m4-rsa-only

• FLASH: .rodata +24 B, .text +256 B (+0.1%, 323,752 B / 1,048,576 B, total: 31% used)

gcc-arm-cortex-m4-tls13

• FLASH: .rodata.wolfSSL_ERR_reason_error_string.str1.1 +18 B, .text +192 B (+0.1%, 234,896 B / 262,144 B, total: 90% used)

gcc-arm-cortex-m7

• FLASH: .rodata.wolfSSL_ERR_reason_error_string.str1.1 +18 B (+0.0%, 199,070 B / 262,144 B, total: 76% used)

gcc-arm-cortex-m7-pq

• FLASH: .rodata +24 B, .text +192 B (+0.1%, 278,728 B / 1,048,576 B, total: 27% used)

gcc-arm-cortex-m7-tls13

• FLASH: .rodata.wolfSSL_ERR_reason_error_string.str1.1 +18 B, .text +128 B (+0.1%, 234,896 B / 262,144 B, total: 90% used)

linuxkm-standard

• Data: __patchable_function_entries +16 B (+0.0%, 46,032 B)
  No memory changes detected for:
• gcc-arm-cortex-m0plus
• gcc-arm-cortex-m4-baremetal
• gcc-arm-cortex-m4-crypto-only
• gcc-arm-cortex-m4-min-ecc
• gcc-arm-cortex-m4-pkcs7
• gcc-arm-cortex-m4-sp-math
• gcc-arm-cortex-m4-tls12
• linuxkm-pie
• stm32-sim-stm32h753

[Frauschi]

Jenkins retest this please