Merge pull request #3780 from SparkiDev/tls13_key_up_resp

TLS 1.3: add API to tell if a KeyUpdate response is required

doc/dox_comments/header_files/ssl.h

@@ -12743,6 +12743,40 @@ WOLFSSL_API int  wolfSSL_no_dhe_psk(WOLFSSL* ssl);
 */
 WOLFSSL_API int  wolfSSL_update_keys(WOLFSSL* ssl);
 
+/*!
+    \ingroup IO
+
+    \brief This function is called on a TLS v1.3 client or server wolfSSL to
+    determine whether a rollover of keys is in progress. When
+    wolfSSL_update_keys() is called, a KeyUpdate message is sent and the
+    encryption key is updated. The decryption key is updated when the response
+    is received.
+
+    \param [in] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
+    \param [out] required   0 when no key update response required. 1 when no key update response required.
+
+    \return 0 on successful.
+    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
+
+    _Example_
+    \code
+    int ret;
+    WOLFSSL* ssl;
+    int required;
+    ...
+    ret = wolfSSL_key_update_response(ssl, &required);
+    if (ret != 0) {
+        // bad parameters
+    }
+    if (required) {
+        // encrypt Key updated, awaiting response to change decrypt key
+    }
+    \endcode
+
+    \sa wolfSSL_update_keys
+*/
+WOLFSSL_API int  wolfSSL_key_update_response(WOLFSSL* ssl, int* required);
+
 /*!
     \ingroup Setup
 

src/tls13.c

@@ -7972,6 +7972,24 @@ int wolfSSL_update_keys(WOLFSSL* ssl)
     return ret;
 }
 
+/* Whether a response is waiting for key update request.
+ *
+ * ssl        The SSL/TLS object.
+ * required   0 when no key update response required.
+ *            1 when no key update response required.
+ * return  0 on success.
+ * return  BAD_FUNC_ARG when ssl is NULL or not using TLS v1.3
+ */
+int wolfSSL_key_update_response(WOLFSSL* ssl, int* required)
+{
+    if (required == NULL || ssl == NULL || !IsAtLeastTLSv1_3(ssl->version))
+        return BAD_FUNC_ARG;
+
+    *required = ssl->keys.updateResponseReq;
+
+    return 0;
+}
+
 #if !defined(NO_CERTS) && defined(WOLFSSL_POST_HANDSHAKE_AUTH)
 /* Allow post-handshake authentication in TLS v1.3 connections.
  *

tests/api.c

@@ -37439,6 +37439,7 @@ static int test_tls13_apis(void)
     const char*  ourKey  = svrKeyFile;
 #endif
 #endif
+    int          required;
 #ifdef WOLFSSL_EARLY_DATA
     int          outSz;
 #endif
@@ -37628,6 +37629,19 @@ static int test_tls13_apis(void)
     AssertIntEQ(wolfSSL_update_keys(serverSsl), BUILD_MSG_ERROR);
 #endif
 
+    AssertIntEQ(wolfSSL_key_update_response(NULL, NULL), BAD_FUNC_ARG);
+    AssertIntEQ(wolfSSL_key_update_response(NULL, &required), BAD_FUNC_ARG);
+#ifndef NO_WOLFSSL_CLIENT
+#ifndef WOLFSSL_NO_TLS12
+    AssertIntEQ(wolfSSL_key_update_response(clientTls12Ssl, &required),
+                BAD_FUNC_ARG);
+#endif
+    AssertIntEQ(wolfSSL_key_update_response(clientSsl, NULL), BAD_FUNC_ARG);
+#endif
+#ifndef NO_WOLFSSL_SERVER
+    AssertIntEQ(wolfSSL_key_update_response(serverSsl, NULL), BAD_FUNC_ARG);
+#endif
+
 #if !defined(NO_CERTS) && defined(WOLFSSL_POST_HANDSHAKE_AUTH)
     AssertIntEQ(wolfSSL_CTX_allow_post_handshake_auth(NULL), BAD_FUNC_ARG);
 #ifndef NO_WOLFSSL_SERVER

wolfssl/ssl.h

@@ -914,6 +914,7 @@ WOLFSSL_API int  wolfSSL_no_ticket_TLSv13(WOLFSSL* ssl);
 WOLFSSL_API int  wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX* ctx);
 WOLFSSL_API int  wolfSSL_no_dhe_psk(WOLFSSL* ssl);
 WOLFSSL_API int  wolfSSL_update_keys(WOLFSSL* ssl);
+WOLFSSL_API int  wolfSSL_key_update_response(WOLFSSL* ssl, int* required);
 WOLFSSL_API int  wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX* ctx);
 WOLFSSL_API int  wolfSSL_allow_post_handshake_auth(WOLFSSL* ssl);
 WOLFSSL_API int  wolfSSL_request_certificate(WOLFSSL* ssl);