RFC 9258 importer: remove pre-extracted EPSK option

Drop wolfSSL_external_psk_pre_extracted() and the associated
psk_externalKeyPreExtracted state and derivation branch. It was a
non-standard convenience not required by RFC 9258 (the import always
performs epskx = HKDF-Extract(0, epsk)) and is not wanted for upstreaming.

* Remove the public API and its prototype/documentation.
* Remove the Arrays.psk_externalKeyPreExtracted bitfield.
* DeriveImportedPsk()/DeriveImportedPreSharedKey() always HKDF-Extract.
* Drop the pre-extracted handshake test case.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XRMrPoMWjro4shL6W2JHXw

Author: claude

doc/dox_comments/header_files/ssl.h

@@ -15251,7 +15251,6 @@ void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl,
 
     \sa wolfSSL_set_psk_client_importer_callback
     \sa wolfSSL_CTX_set_psk_server_importer_callback
-    \sa wolfSSL_external_psk_pre_extracted
 */
 void wolfSSL_CTX_set_psk_client_importer_callback(WOLFSSL_CTX* ctx,
     wc_psk_client_importer_callback cb);
@@ -15276,7 +15275,6 @@ void wolfSSL_CTX_set_psk_client_importer_callback(WOLFSSL_CTX* ctx,
 
     \sa wolfSSL_CTX_set_psk_client_importer_callback
     \sa wolfSSL_set_psk_server_importer_callback
-    \sa wolfSSL_external_psk_pre_extracted
 */
 void wolfSSL_set_psk_client_importer_callback(WOLFSSL* ssl,
     wc_psk_client_importer_callback cb);
@@ -15307,7 +15305,6 @@ void wolfSSL_set_psk_client_importer_callback(WOLFSSL* ssl,
 
     \sa wolfSSL_set_psk_server_importer_callback
     \sa wolfSSL_CTX_set_psk_client_importer_callback
-    \sa wolfSSL_external_psk_pre_extracted
 */
 void wolfSSL_CTX_set_psk_server_importer_callback(WOLFSSL_CTX* ctx,
     wc_psk_server_importer_callback cb);
@@ -15332,38 +15329,10 @@ void wolfSSL_CTX_set_psk_server_importer_callback(WOLFSSL_CTX* ctx,
 
     \sa wolfSSL_CTX_set_psk_server_importer_callback
     \sa wolfSSL_set_psk_client_importer_callback
-    \sa wolfSSL_external_psk_pre_extracted
 */
 void wolfSSL_set_psk_server_importer_callback(WOLFSSL* ssl,
     wc_psk_server_importer_callback cb);
 
-/*!
-    \ingroup Setup
-
-    \brief This function marks whether the external PSK supplied by the importer
-    callback is already a pre-extracted pseudorandom key. When enabled, the
-    imported-PSK derivation skips the HKDF-Extract step (RFC 9258, Section 3.1).
-    Both peers must agree on this setting. Requires WOLFSSL_EXTERNAL_PSK_IMPORTER.
-
-    \return 0 on success.
-    \return BAD_FUNC_ARG when ssl is NULL.
-
-    \param [in,out] ssl a pointer to a WOLFSSL structure, created using
-    wolfSSL_new().
-    \param [in] opt non-zero to treat the external PSK as pre-extracted.
-
-    _Example_
-    \code
-    WOLFSSL* ssl;
-    ...
-    wolfSSL_external_psk_pre_extracted(ssl, 1);
-    \endcode
-
-    \sa wolfSSL_set_psk_client_importer_callback
-    \sa wolfSSL_set_psk_server_importer_callback
-*/
-int wolfSSL_external_psk_pre_extracted(WOLFSSL* ssl, int opt);
-
 /*!
     \ingroup Setup
 

src/tls13.c

@@ -1213,8 +1213,7 @@ static const byte derivedPskLabel[DERIVED_PSK_LABEL_SZ + 1] =
  * (RFC 9258, Section 3.1). This core routine is independent of WOLFSSL state so
  * it can be exercised directly with known-answer test vectors.
  *
- *   epsk/epskSz        External PSK base key (or a pre-extracted PRK).
- *   preExtracted       Non-zero if epsk is already a PRK (skip HKDF-Extract).
+ *   epsk/epskSz        External PSK base key.
  *   importedIdentity   Serialized ImportedIdentity (hashed as the context).
  *   importedIdentitySz Length of importedIdentity.
  *   importerHash       Hash associated with the EPSK (e.g. WC_SHA256), used for
@@ -1231,10 +1230,9 @@ static const byte derivedPskLabel[DERIVED_PSK_LABEL_SZ + 1] =
  * Returns 0 on success, otherwise a negative error.
  */
 WOLFSSL_LOCAL int DeriveImportedPsk(const byte* epsk, word32 epskSz,
-        int preExtracted, const byte* importedIdentity,
-        word32 importedIdentitySz, int importerHash, byte targetKdfMac,
-        byte protocolMinor, int isDtls, byte* out, word32* outSz,
-        void* heap, int devId)
+        const byte* importedIdentity, word32 importedIdentitySz,
+        int importerHash, byte targetKdfMac, byte protocolMinor, int isDtls,
+        byte* out, word32* outSz, void* heap, int devId)
 {
     int         ret;
     const byte* protocol;
@@ -1357,28 +1355,19 @@ WOLFSSL_LOCAL int DeriveImportedPsk(const byte* epsk, word32 epskSz,
         /* okm holds ipskx; prk holds epskx. Both are dedicated buffers so the
          * HKDF input may safely alias the output buffer. */
         PRIVATE_KEY_UNLOCK();
-        if (preExtracted) {
-            /* The external PSK is already a pseudorandom key (the result of an
-             * earlier HKDF-Extract), so derive ipskx directly with an
-             * HKDF-Expand-Label. */
-            ret = wc_HKDF_Expand_ex(importerHash, epsk, epskSz, hkdfLabel, idx,
-                    okm, outputLen, heap, devId);
-        }
-        else {
-            /* epskx = HKDF-Extract(0, epsk) */
-        #if !defined(HAVE_FIPS) || \
-            (defined(FIPS_VERSION_GE) && FIPS_VERSION_GE(6,0))
-            ret = wc_HKDF_Extract_ex(importerHash, NULL, 0, epsk, epskSz, prk,
-                    heap, devId);
-        #else
-            ret = wc_HKDF_Extract(importerHash, NULL, 0, epsk, epskSz, prk);
-        #endif
-            if (ret == 0) {
-                /* ipskx = HKDF-Expand-Label(epskx, "derived psk",
-                 *                           Hash(ImportedIdentity), L) */
-                ret = wc_HKDF_Expand_ex(importerHash, prk, (word32)hashSz,
-                        hkdfLabel, idx, okm, outputLen, heap, devId);
-            }
+        /* epskx = HKDF-Extract(0, epsk) */
+    #if !defined(HAVE_FIPS) || \
+        (defined(FIPS_VERSION_GE) && FIPS_VERSION_GE(6,0))
+        ret = wc_HKDF_Extract_ex(importerHash, NULL, 0, epsk, epskSz, prk,
+                heap, devId);
+    #else
+        ret = wc_HKDF_Extract(importerHash, NULL, 0, epsk, epskSz, prk);
+    #endif
+        if (ret == 0) {
+            /* ipskx = HKDF-Expand-Label(epskx, "derived psk",
+             *                           Hash(ImportedIdentity), L) */
+            ret = wc_HKDF_Expand_ex(importerHash, prk, (word32)hashSz,
+                    hkdfLabel, idx, okm, outputLen, heap, devId);
         }
         PRIVATE_KEY_LOCK();
 
@@ -1424,10 +1413,9 @@ static int DeriveImportedPreSharedKey(WOLFSSL* ssl, PreSharedKey* psk,
 
     keySz = ssl->arrays->psk_keySz;
     ret = DeriveImportedPsk(ssl->arrays->psk_key, ssl->arrays->psk_keySz,
-            ssl->arrays->psk_externalKeyPreExtracted, psk->identity,
-            psk->identityLen, importerHash, psk->hmac, ssl->version.minor,
-            ssl->options.dtls, ssl->arrays->psk_key, &keySz, ssl->heap,
-            ssl->devId);
+            psk->identity, psk->identityLen, importerHash, psk->hmac,
+            ssl->version.minor, ssl->options.dtls, ssl->arrays->psk_key, &keySz,
+            ssl->heap, ssl->devId);
     if (ret == 0)
         ssl->arrays->psk_keySz = keySz;
 
@@ -15833,29 +15821,6 @@ const char* wolfSSL_get_cipher_name_by_hash(WOLFSSL* ssl, const char* hash)
     }
     return name;
 }
-
-#if defined(WOLFSSL_EXTERNAL_PSK_IMPORTER)
-/* Mark whether the external PSK provided by the importer callback is already a
- * pre-extracted pseudorandom key. When set, the imported-PSK derivation skips
- * the HKDF-Extract step (RFC 9258, Section 3.1).
- *
- * ssl  The SSL/TLS object.
- * opt  Non-zero to treat the external PSK as pre-extracted.
- * returns BAD_FUNC_ARG when ssl is NULL and 0 on success.
- */
-int wolfSSL_external_psk_pre_extracted(WOLFSSL* ssl, int opt)
-{
-    if (ssl == NULL)
-        return BAD_FUNC_ARG;
-
-    if (opt)
-        ssl->arrays->psk_externalKeyPreExtracted = 1;
-    else
-        ssl->arrays->psk_externalKeyPreExtracted = 0;
-
-    return 0;
-}
-#endif /* WOLFSSL_EXTERNAL_PSK_IMPORTER */
 #endif /* !NO_PSK */
 
 

tests/api.c

@@ -30496,7 +30496,7 @@ static int test_psk_importer_server_cb(WOLFSSL* ssl, const unsigned char* id,
 /* Run a single TLS 1.3 handshake that authenticates with an imported external
  * PSK (RFC 9258), restricted to the given cipher suite. */
 static int test_tls13_external_psk_importer_one(const char* cipher,
-        int expectedSuite, int useContext, int preExtracted, int expectFail)
+        int expectedSuite, int useContext, int expectFail)
 {
     EXPECT_DECLS;
     WOLFSSL_CTX *ctx_c = NULL, *ctx_s = NULL;
@@ -30519,11 +30519,6 @@ static int test_tls13_external_psk_importer_one(const char* cipher,
     wolfSSL_set_psk_server_importer_callback(ssl_s,
         test_psk_importer_server_cb);
 
-    if (preExtracted) {
-        ExpectIntEQ(wolfSSL_external_psk_pre_extracted(ssl_c, 1), 0);
-        ExpectIntEQ(wolfSSL_external_psk_pre_extracted(ssl_s, 1), 0);
-    }
-
     /* Restrict both sides to the suite under test (importer callback setup
      * rebuilds the suite list, so set the cipher list afterwards). */
     ExpectIntEQ(wolfSSL_set_cipher_list(ssl_c, cipher), WOLFSSL_SUCCESS);
@@ -30556,16 +30551,13 @@ static int test_tls13_external_psk_importer(void)
 
     /* HKDF_SHA256 target_kdf, without and with an optional context. */
     ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES128-GCM-SHA256",
-        0x1301, 0, 0, 0), TEST_SUCCESS);
-    ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES128-GCM-SHA256",
-        0x1301, 1, 0, 0), TEST_SUCCESS);
-    /* Pre-extracted EPSK (HKDF-Extract is skipped during import). */
+        0x1301, 0, 0), TEST_SUCCESS);
     ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES128-GCM-SHA256",
-        0x1301, 1, 1, 0), TEST_SUCCESS);
+        0x1301, 1, 0), TEST_SUCCESS);
 #if defined(WOLFSSL_SHA384) && defined(WOLFSSL_AES_256)
     /* HKDF_SHA384 target_kdf exercises the L = 48 derived-PSK length. */
     ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES256-GCM-SHA384",
-        0x1302, 1, 0, 0), TEST_SUCCESS);
+        0x1302, 1, 0), TEST_SUCCESS);
 #endif
 
 #if defined(WOLFSSL_SHA384)
@@ -30574,15 +30566,15 @@ static int test_tls13_external_psk_importer(void)
      * target KDF (RFC 9258 Section 3.1). */
     test_psk_importer_hash = WC_SHA384;
     ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES128-GCM-SHA256",
-        0x1301, 1, 0, 0), TEST_SUCCESS);
+        0x1301, 1, 0), TEST_SUCCESS);
     test_psk_importer_hash = WC_SHA256;
 #endif
 
     /* Negative: server derives a different imported PSK -> binder mismatch
      * -> handshake must fail. */
     test_psk_importer_server_wrong_key = 1;
     ExpectIntEQ(test_tls13_external_psk_importer_one("TLS13-AES128-GCM-SHA256",
-        0x1301, 1, 0, 1), TEST_SUCCESS);
+        0x1301, 1, 1), TEST_SUCCESS);
     test_psk_importer_server_wrong_key = 0;
 
     return EXPECT_RESULT();
@@ -30733,7 +30725,7 @@ static int test_tls13_psk_importer_kat_one(const byte* ctx, word16 ctxLen,
 
     /* Derived imported PSK (ipskx) matches the independent vector. */
     ExpectIntEQ(DeriveImportedPsk(test_kat_epsk, (word32)sizeof(test_kat_epsk),
-        0, expII, expIISz, importerHash, targetKdfMac, TLSv1_3_MINOR, 0, out,
+        expII, expIISz, importerHash, targetKdfMac, TLSv1_3_MINOR, 0, out,
         &outSz, NULL, INVALID_DEVID), 0);
     ExpectIntEQ((int)outSz, (int)expIpskSz);
     ExpectIntEQ(XMEMCMP(out, expIpsk, expIpskSz), 0);

wolfssl/internal.h

@@ -3874,10 +3874,9 @@ WOLFSSL_LOCAL int TLSX_PreSharedKey_ParseImportedIdentity(byte* input,
         word16 length, byte** id, word16* id_len, byte** ctx,word16* ctx_len,
         byte* hkdf, ProtocolVersion* protocol);
 WOLFSSL_LOCAL int DeriveImportedPsk(const byte* epsk, word32 epskSz,
-        int preExtracted, const byte* importedIdentity,
-        word32 importedIdentitySz, int importerHash, byte targetKdfMac,
-        byte protocolMinor, int isDtls, byte* out, word32* outSz,
-        void* heap, int devId);
+        const byte* importedIdentity, word32 importedIdentitySz,
+        int importerHash, byte targetKdfMac, byte protocolMinor, int isDtls,
+        byte* out, word32* outSz, void* heap, int devId);
 #endif
 #endif /* HAVE_SESSION_TICKET || !NO_PSK */
 
@@ -5417,9 +5416,6 @@ typedef struct Arrays {
     char            client_identity[MAX_PSK_ID_LEN + NULL_TERM_LEN];
     char            server_hint[MAX_PSK_ID_LEN + NULL_TERM_LEN];
     byte            psk_key[MAX_PSK_KEY_LEN];
-#if defined(WOLFSSL_TLS13) && defined(WOLFSSL_EXTERNAL_PSK_IMPORTER)
-    byte            psk_externalKeyPreExtracted:1;
-#endif /* WOLFSSL_TLS13 && WOLFSSL_EXTERNAL_PSK_IMPORTER */
 #endif /* HAVE_SESSION_TICKET || !NO_PSK */
     byte            clientRandom[RAN_LEN];
 #if defined(WOLFSSL_TLS13) && defined(HAVE_ECH)

wolfssl/ssl.h

@@ -3355,10 +3355,6 @@ enum { /* ssl Constants */
 #ifdef WOLFSSL_TLS13
     WOLFSSL_API const char* wolfSSL_get_cipher_name_by_hash(WOLFSSL* ssl,
         const char* hash);
-
-    #ifdef WOLFSSL_EXTERNAL_PSK_IMPORTER
-    WOLFSSL_API int wolfSSL_external_psk_pre_extracted(WOLFSSL* ssl, int opt);
-    #endif
 #endif
 #endif /* NO_PSK */