diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index c91db1441..9bcb060d0 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/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 diff --git a/src/tls13.c b/src/tls13.c index ac79d0b49..f8621977f 100644 --- a/src/tls13.c +++ b/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. * diff --git a/tests/api.c b/tests/api.c index 6a2283663..6c0630b60 100644 --- a/tests/api.c +++ b/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 diff --git a/wolfssl/ssl.h b/wolfssl/ssl.h index 0c81c9b77..9cd1cd693 100644 --- a/wolfssl/ssl.h +++ b/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);