Add RFC8773bis cert_with_extern_psk support

Implement RFC8773bis (draft-ietf-tls-8773bis-13)
cert_with_extern_psk for TLS 1.3, including protocol checks
and API support.

Includes unit tests for API and handshake behavior as well
as tests in the testsuite using extended examples.

Author: Frauschi

.github/workflows/cmake.yml

@@ -73,6 +73,7 @@ jobs:
             -DWOLFSSL_X963KDF:BOOL=yes -DWOLFSSL_DILITHIUM:BOOL=yes -DWOLFSSL_PKCS11:BOOL=yes \
             -DWOLFSSL_ECCSI:BOOL=yes -DWOLFSSL_SAKKE:BOOL=yes -DWOLFSSL_SIPHASH:BOOL=yes \
             -DWOLFSSL_WC_RSA_DIRECT:BOOL=yes -DWOLFSSL_PUBLIC_MP:BOOL=yes \
+            -DWOLFSSL_CERT_WITH_EXTERN_PSK:BOOL=yes \
             -DWOLFSSL_EXTRA_PQC_HYBRIDS:BOOL=yes -DWOLFSSL_TLS_NO_MLKEM_STANDALONE:BOOL=no \
             ..
         cmake --build .

.github/workflows/psk.yml

@@ -18,6 +18,7 @@ jobs:
       matrix:
         config: [
           # Add new configs here
+          '--enable-psk --enable-cert-with-extern-psk --disable-mlkem',
           '--enable-psk  --disable-mlkem C_EXTRA_FLAGS="-DWOLFSSL_STATIC_PSK -DWOLFSSL_OLDTLS_SHA2_CIPHERSUITES"',
           '--enable-psk  --disable-mlkem C_EXTRA_FLAGS=-DWOLFSSL_STATIC_PSK --disable-rsa --disable-ecc --disable-dh',
           '--disable-oldtls --disable-tls13 --enable-psk -disable-rsa --disable-dh -disable-ecc --disable-asn C_EXTRA_FLAGS=-DWOLFSSL_STATIC_PSK --enable-lowresource --enable-singlethreaded --disable-asm --disable-errorstrings --disable-pkcs12 --disable-sha3 --disable-sha224 --disable-sha384 --disable-sha512 --disable-sha --disable-md5 -disable-aescbc --disable-chacha --disable-poly1305 --disable-coding --disable-sp-math-all --disable-mlkem',

CMakeLists.txt

@@ -376,6 +376,24 @@ if(WOLFSSL_POSTAUTH)
     endif()
 endif()
 
+# Certificate Authentication with External PSK (RFC 8773bis)
+add_option("WOLFSSL_CERT_WITH_EXTERN_PSK"
+    "Enable Certificate Authentication with External PSKs for TLS 1.3 (default: disabled)"
+    "no" "yes;no")
+
+if(WOLFSSL_CERT_WITH_EXTERN_PSK)
+    if(NOT WOLFSSL_TLS13)
+        message(WARNING "TLS 1.3 is disabled - disabling cert-with-extern-psk")
+        override_cache(WOLFSSL_CERT_WITH_EXTERN_PSK "no")
+    elseif(NOT WOLFSSL_PSK)
+        message(WARNING "PSK is disabled - disabling cert-with-extern-psk")
+        override_cache(WOLFSSL_CERT_WITH_EXTERN_PSK "no")
+    else()
+        list(APPEND WOLFSSL_DEFINITIONS
+            "-DWOLFSSL_CERT_WITH_EXTERN_PSK")
+    endif()
+endif()
+
 # Hello Retry Request Cookie
 add_option("WOLFSSL_HRR_COOKIE"
     "Enable the server to send Cookie Extension in HRR with state (default: disabled)"

cmake/options.h.in

@@ -308,6 +308,8 @@ extern "C" {
 #cmakedefine WOLFSSL_DTLS13
 #undef WOLFSSL_DTLS_CH_FRAG
 #cmakedefine WOLFSSL_DTLS_CH_FRAG
+#undef WOLFSSL_CERT_WITH_EXTERN_PSK
+#cmakedefine WOLFSSL_CERT_WITH_EXTERN_PSK
 #undef WOLFSSL_EITHER_SIDE
 #cmakedefine WOLFSSL_EITHER_SIDE
 #undef WOLFSSL_ENCRYPTED_KEYS
@@ -427,4 +429,3 @@ extern "C" {
 
 
 #endif /* WOLFSSL_OPTIONS_H */
-

configure.ac

@@ -5142,6 +5142,27 @@ then
     AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_PSK_ONE_ID"
 fi
 
+# Certificate Authentication with External PSK (RFC 8773bis)
+AC_ARG_ENABLE([cert-with-extern-psk],
+    [AS_HELP_STRING([--enable-cert-with-extern-psk],[Enable Certificate Authentication with External PSKs for TLS 1.3 (default: disabled)])],
+    [ ENABLED_CERT_WITH_EXTERN_PSK=$enableval ],
+    [ ENABLED_CERT_WITH_EXTERN_PSK=no ]
+    )
+if test "$ENABLED_CERT_WITH_EXTERN_PSK" = "yes"
+then
+    if test "$ENABLED_TLS13" = "no"
+    then
+        AC_MSG_NOTICE([TLS 1.3 is disabled - disabling cert-with-extern-psk])
+        ENABLED_CERT_WITH_EXTERN_PSK="no"
+    elif test "$ENABLED_PSK" = "no"
+    then
+        AC_MSG_NOTICE([PSK is disabled - disabling cert-with-extern-psk])
+        ENABLED_CERT_WITH_EXTERN_PSK="no"
+    else
+        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_CERT_WITH_EXTERN_PSK"
+    fi
+fi
+
 # ERROR STRINGS
 AC_ARG_ENABLE([errorstrings],
     [AS_HELP_STRING([--enable-errorstrings],[Enable error strings table (default: enabled)])],

doc/dox_comments/header_files/ssl.h

@@ -14721,6 +14721,75 @@ void wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX* ctx,
 void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl,
     wc_psk_server_tls13_callback cb);
 
+/*!
+    \ingroup Setup
+
+    \brief Enable or disable TLS 1.3 certificate authentication with external
+    PSK (RFC8773bis) on a context.
+
+    When enabled, wolfSSL advertises and accepts the
+    `tls_cert_with_extern_psk` extension for TLS 1.3 handshakes using external
+    PSKs. Any non-zero \p state value enables the feature and zero disables it.
+
+    Availability:
+      - Built with `--enable-tls13 --enable-psk --enable-cert-with-extern-psk`
+      - Or with `WOLFSSL_TLS13` and `WOLFSSL_CERT_WITH_EXTERN_PSK` defined
+
+    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created with
+                        wolfSSL_CTX_new().
+    \param [in] state 0 to disable, non-zero to enable.
+
+    \return WOLFSSL_SUCCESS on success.
+    \return WOLFSSL_FAILURE when \p ctx is NULL.
+
+    _Example_
+    \code
+    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method());
+    if (wolfSSL_CTX_set_cert_with_extern_psk(ctx, 1) != WOLFSSL_SUCCESS) {
+        /* handle error */
+    }
+    \endcode
+
+    \sa wolfSSL_set_cert_with_extern_psk
+    \sa wolfSSL_CTX_set_psk_client_tls13_callback
+    \sa wolfSSL_CTX_set_psk_server_tls13_callback
+*/
+int wolfSSL_CTX_set_cert_with_extern_psk(WOLFSSL_CTX* ctx, int state);
+
+/*!
+    \ingroup Setup
+
+    \brief Enable or disable TLS 1.3 certificate authentication with external
+    PSK (RFC8773bis) on a connection.
+
+    This call applies to a single WOLFSSL object. Any non-zero \p state value
+    enables the feature and zero disables it.
+
+    Availability:
+      - Built with `--enable-tls13 --enable-psk --enable-cert-with-extern-psk`
+      - Or with `WOLFSSL_TLS13` and `WOLFSSL_CERT_WITH_EXTERN_PSK` defined
+
+    \param [in,out] ssl a pointer to a WOLFSSL structure, created using
+                        wolfSSL_new().
+    \param [in] state 0 to disable, non-zero to enable.
+
+    \return WOLFSSL_SUCCESS on success.
+    \return WOLFSSL_FAILURE when \p ssl is NULL.
+
+    _Example_
+    \code
+    WOLFSSL* ssl = wolfSSL_new(ctx);
+    if (wolfSSL_set_cert_with_extern_psk(ssl, 1) != WOLFSSL_SUCCESS) {
+        /* handle error */
+    }
+    \endcode
+
+    \sa wolfSSL_CTX_set_cert_with_extern_psk
+    \sa wolfSSL_set_psk_client_tls13_callback
+    \sa wolfSSL_set_psk_server_tls13_callback
+*/
+int wolfSSL_set_cert_with_extern_psk(WOLFSSL* ssl, int state);
+
 /*!
     \ingroup Setup
 

examples/client/client.c

@@ -1209,7 +1209,7 @@ static int ClientWriteRead(WOLFSSL* ssl, const char* msg, int msgSz,
 /*  4. add the same message into Japanese section         */
 /*     (will be translated later)                         */
 /*  5. add printf() into suitable position of Usage()     */
-static const char* client_usage_msg[][80] = {
+static const char* client_usage_msg[][81] = {
     /* English */
     {
         " NOTE: All files relative to wolfSSL home dir\n",          /* 0 */
@@ -1454,24 +1454,28 @@ static const char* client_usage_msg[][80] = {
 #ifndef NO_PSK
         "--openssl-psk  Use TLS 1.3 PSK callback compatible with OpenSSL\n", /* 73 */
 #endif
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+        "--psk-with-certs  Use TLS 1.3 PSK with certificates\n",        /* 74 */
+#endif
 #ifdef HAVE_RPK
-        "--rpk  Use RPK for the defined certificates\n", /* 74 */
+        "--rpk  Use RPK for the defined certificates\n", /* 75 */
 #endif
-        "--files-are-der Specified files are in DER, not PEM format\n", /* 75 */
+        "--files-are-der Specified files are in DER, not PEM format\n", /* 76 */
 #ifdef WOLFSSL_SYS_CRYPTO_POLICY
-        "--crypto-policy  <path to crypto policy file>\n", /* 76 */
+        "--crypto-policy  <path to crypto policy file>\n", /* 77 */
 #endif
 #ifdef HAVE_ECC_BRAINPOOL
-        "--bpKs  Use Brainpool ECC group for key share\n",             /* 77 */
+        "--bpKs  Use Brainpool ECC group for key share\n",             /* 78 */
 #endif
 #if defined(WOLFSSL_TLS13) && defined(HAVE_ECH)
         "--ech <base64>  Use Encrypted Client Hello with base64 encoded "
             "ECH configs\n",
-                                                                        /* 78 */
+                                                                        /* 79 */
 #endif
         "\n"
            "For simpler wolfSSL TLS client examples, visit\n"
-           "https://github.com/wolfSSL/wolfssl-examples/tree/master/tls\n", /* 79 */
+           "https://github.com/wolfSSL/wolfssl-examples/tree/master/tls\n", /* 80 */
         NULL,
     },
 #ifndef NO_MULTIBYTE_PRINT
@@ -1720,20 +1724,24 @@ static const char* client_usage_msg[][80] = {
 #ifndef NO_PSK
         "--openssl-psk  Use TLS 1.3 PSK callback compatible with OpenSSL\n", /* 73 */
 #endif
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+        "--psk-with-certs  Use TLS 1.3 PSK with certificates\n",        /* 74 */
+#endif
 #ifdef HAVE_RPK
-        "--rpk  Use RPK for the defined certificates\n", /* 74 */
+        "--rpk  Use RPK for the defined certificates\n", /* 75 */
 #endif
-        "--files-are-der Specified files are in DER, not PEM format\n", /* 75 */
+        "--files-are-der Specified files are in DER, not PEM format\n", /* 76 */
 #ifdef WOLFSSL_SYS_CRYPTO_POLICY
-        "--crypto-policy  <path to crypto policy file>\n", /* 76 */
+        "--crypto-policy  <path to crypto policy file>\n", /* 77 */
 #endif
 #ifdef HAVE_ECC_BRAINPOOL
-        "--bpKs  Use Brainpool ECC group for key share\n",             /* 77 */
+        "--bpKs  Use Brainpool ECC group for key share\n",             /* 78 */
 #endif
         "\n"
         "より簡単なwolfSSL TLS クライアントの例については"
                                          "下記にアクセスしてください\n"
-        "https://github.com/wolfSSL/wolfssl-examples/tree/master/tls\n", /* 78 */
+        "https://github.com/wolfSSL/wolfssl-examples/tree/master/tls\n", /* 79 */
         NULL,
     },
 #endif
@@ -1969,6 +1977,10 @@ static void Usage(void)
 #ifndef NO_PSK
     printf("%s", msg[++msgid]); /* --openssl-psk */
 #endif
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+    printf("%s", msg[++msgid]); /* --psk-with-certs */
+#endif
 #ifdef HAVE_RPK
     printf("%s", msg[++msgid]); /* --rpk */
 #endif
@@ -2168,6 +2180,10 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
 #endif
 #if defined(WOLFSSL_TLS13) && defined(HAVE_ECH)
         { "ech", 1, 271 },
+#endif
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+        { "psk-with-certs", 0, 272 },
 #endif
         { 0, 0, 0 }
     };
@@ -2176,6 +2192,7 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
     int    minVersion = CLIENT_INVALID_VERSION;
     int    usePsk   = 0;
     int    opensslPsk = 0;
+    int    usePskWithCerts = 0;
     int    useAnon  = 0;
     int    sendGET  = 0;
     int    benchmark = 0;
@@ -2415,6 +2432,7 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
     (void)pqcAlg;
     (void)opensslPsk;
     (void)fileFormat;
+    (void)usePskWithCerts;
     StackTrap();
 
     /* Reinitialize the global myVerifyAction. */
@@ -3070,6 +3088,12 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
                 echConfigs64 = myoptarg;
                 break;
 #endif
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+            case 272:
+                usePskWithCerts = 1;
+                break;
+#endif
 
             default:
                 Usage();
@@ -3080,6 +3104,18 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
     myoptind = 0;      /* reset for test cases */
 #endif /* !WOLFSSL_VXWORKS */
 
+#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_CERT_WITH_EXTERN_PSK) && \
+    !defined(NO_PSK)
+    if (usePskWithCerts) {
+        usePsk = 1;
+        if (noPskDheKe) {
+            LOG_ERROR("--psk-with-certs requires PSK key exchange with (EC)DHE");
+            Usage();
+            XEXIT_T(MY_EX_USAGE);
+        }
+    }
+#endif
+
     if (externalTest) {
         /* detect build cases that wouldn't allow test against wolfssl.com */
         int done = 0;
@@ -3486,6 +3522,14 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
             wolfSSL_CTX_set_psk_client_tls13_callback(ctx,
                 my_psk_client_tls13_cb);
         }
+#if defined(WOLFSSL_CERT_WITH_EXTERN_PSK)
+        if (usePskWithCerts) {
+            if (wolfSSL_CTX_set_cert_with_extern_psk(ctx, 1) != WOLFSSL_SUCCESS) {
+                wolfSSL_CTX_free(ctx); ctx = NULL;
+                err_sys("client can't enable cert_with_extern_psk");
+            }
+        }
+#endif
 #endif
         if (defaultCipherList == NULL) {
         #if defined(HAVE_AESGCM) && !defined(NO_DH)
@@ -3637,7 +3681,8 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
     #endif
     }
 
-    if (!usePsk && !useAnon && !useVerifyCb && myVerifyAction != VERIFY_FORCE_FAIL) {
+    if ((!usePsk || usePskWithCerts) && !useAnon && !useVerifyCb &&
+            myVerifyAction != VERIFY_FORCE_FAIL) {
     #if defined(OPENSSL_ALL) && defined(WOLFSSL_CERT_GEN) && \
     (defined(WOLFSSL_CERT_REQ) || defined(WOLFSSL_CERT_EXT)) && \
     !defined(NO_FILESYSTEM) && !defined(NO_WOLFSSL_DIR)
@@ -3721,10 +3766,11 @@ THREAD_RETURN WOLFSSL_THREAD client_test(void* args)
             myVerifyAction == VERIFY_USE_PREVERIFY) {
         wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_PEER, myVerify);
     }
-    else if (!usePsk && !useAnon && doPeerCheck == 0) {
+    else if ((!usePsk || usePskWithCerts) && !useAnon && doPeerCheck == 0) {
         wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_NONE, NULL);
     }
-    else if (!usePsk && !useAnon && myVerifyAction == VERIFY_OVERRIDE_DATE_ERR) {
+    else if ((!usePsk || usePskWithCerts) && !useAnon &&
+            myVerifyAction == VERIFY_OVERRIDE_DATE_ERR) {
         wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_PEER, myVerify);
     }
 #endif /* !NO_CERTS */