diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index 114f3c5bc..84bb9dcca 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -81,6 +81,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_method(void); \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method \sa wolfDTLSv1_server_method \sa wolfSSLv23_server_method \sa wolfSSL_CTX_new @@ -124,6 +125,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_server_method(void); \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method \sa wolfDTLSv1_client_method \sa wolfSSLv23_client_method \sa wolfSSL_CTX_new @@ -166,6 +168,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_client_method(void); \sa wolfSSLv3_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method \sa wolfDTLSv1_server_method \sa wolfSSLv23_server_method \sa wolfSSL_CTX_new @@ -208,6 +211,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_server_method(void); \sa wolfSSLv3_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method \sa wolfDTLSv1_client_method \sa wolfSSLv23_client_method \sa wolfSSL_CTX_new @@ -250,6 +254,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_client_method(void); \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method \sa wolfDTLSv1_server_method \sa wolfSSLv23_server_method \sa wolfSSL_CTX_new @@ -292,6 +297,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_server_method(void); \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method \sa wolfDTLSv1_client_method \sa wolfSSLv23_client_method \sa wolfSSL_CTX_new @@ -334,6 +340,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_client_method(void); \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_3_server_method \sa wolfDTLSv1_server_method \sa wolfSSLv23_server_method \sa wolfSSL_CTX_new @@ -376,6 +383,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_server_method(void); \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_3_client_method \sa wolfDTLSv1_client_method \sa wolfSSLv23_client_method \sa wolfSSL_CTX_new @@ -419,6 +427,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_client_method(void); \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method \sa wolfSSLv23_client_method \sa wolfSSL_CTX_new */ @@ -461,6 +470,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_client_method(void); \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method \sa wolfSSLv23_server_method \sa wolfSSL_CTX_new */ @@ -1948,55 +1958,6 @@ WOLFSSL_API int wolfSSL_peek(WOLFSSL*, void*, int); */ WOLFSSL_API int wolfSSL_accept(WOLFSSL*); -/*! - \brief This function is called on the client side and initiates an - SSL/TLS handshake with a server. When this function is called, the - underlying communication channel has already been set up. - wolfSSL_connect() works with both blocking and non-blocking I/O. - When the underlying I/O is non-blocking, wolfSSL_connect() will return - when the underlying I/O could not satisfy the needs of wolfSSL_connect - to continue the handshake. In this case, a call to wolfSSL_get_error() - will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The - calling process must then repeat the call to wolfSSL_connect() when - the underlying I/O is ready and wolfSSL will pick up where it left off. - When using a non-blocking socket, nothing needs to be done, but select() - can be used to check for the required condition. If the underlying I/O is - blocking, wolfSSL_connect() will only return once the handshake has been - finished or an error occurred. wolfSSL takes a different approach to - certificate verification than OpenSSL does. The default policy for the - client is to verify the server, this means that if you don't load CAs to - verify the server you'll get a connect error, unable to verify (-155). It - you want to mimic OpenSSL behavior of having SSL_connect succeed even if - verifying the server fails and reducing security you can do this by - calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling - SSL_new(); Though it's not recommended. - - \return SSL_SUCCESS upon success. - \return SSL_FATAL_ERROR will be returned if an error occurred. To get a - more detailed error code, call wolfSSL_get_error(). - - \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - - _Example_ - \code - int ret = 0; - int err = 0; - WOLFSSL* ssl; - char buffer[80]; - ... - - ret = wolfSSL_connect(ssl); - if (ret != SSL_SUCCESS) { - err = wolfSSL_get_error(ssl, ret); - printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); - } - \endcode - - \sa wolfSSL_get_error - \sa wolfSSL_accept -*/ -WOLFSSL_API int wolfSSL_connect_TLSv13(WOLFSSL*); - /*! \ingroup Setup @@ -3810,6 +3771,7 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl); \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method \sa wolfDTLSv1_client_method \sa wolfSSL_CTX_new */ @@ -5284,6 +5246,7 @@ WOLFSSL_API int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*); \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method \sa wolfDTLSv1_server_method \sa wolfSSL_CTX_new */ @@ -12401,3 +12364,1168 @@ wolfSSL takes a different approach to certificate verification than OpenSSL does \sa wolfSSL_accept */ int wolfSSL_connect(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function is called on the server side to indicate that a + HelloRetryRequest message must contain a Cookie. + The Cookie holds a hash of the current transcript so that another server + process can handle the ClientHello in reply. + The secret is used when generting the integrity check on the Cookie data. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] secret a pointer to a buffer holding the secret. + Passing NULL indicates to generate a new random secret. + \param [in] secretSz Size of the secret in bytes. + Passing 0 indicates to use the default size: WC_SHA256_DIGEST_SIZE (or WC_SHA_DIGEST_SIZE when SHA-256 not available). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a client. + \return WOLFSSL_SUCCESS if succesful. + \return MEMORY_ERROR if allocating dynamic memory for storing secret failed. + \return Another -ve value on internal error. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + char secret[32]; + ... + ret = wolfSSL__send_hrr_cookie(ssl, secret, sizeof(secret)); + if (ret != WOLFSSL_SUCCESS) { + // failed to set use of Cookie and secret + } + \endcode + + \sa wolfSSL_new +*/ +WOLFSSL_API int wolfSSL_send_hrr_cookie(WOLFSSL* ssl, + const unsigned char* secret, unsigned int secretSz); + +/*! + \ingroup Setup + + \brief This function is called on the server to stop it from sending + a resumption session ticket once the handshake is complete. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + + \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a client. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_no_ticket_TLSv13(ctx); + if (ret != 0) { + // failed to set no ticket + } + \endcode + + \sa wolfSSL_no_ticket_TLSv13 +*/ +WOLFSSL_API int wolfSSL_CTX_no_ticket_TLSv13(WOLFSSL_CTX* ctx); + +/*! + \ingroup Setup + + \brief This function is called on the server to stop it from sending + a resumption session ticket once the handshake is complete. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a client. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_no_ticket_TLSv13(ssl); + if (ret != 0) { + // failed to set no ticket + } + \endcode + + \sa wolfSSL_CTX_no_ticket_TLSv13 +*/ +WOLFSSL_API int wolfSSL_no_ticket_TLSv13(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function is called on a TLS v1.3 wolfSSL context to disallow + Diffie-Hellman (DH) style key exchanges when handshakes are using + pre-shared keys for authentication. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + + \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_no_dhe_psk(ctx); + if (ret != 0) { + // failed to set no DHE for PSK handshakes + } + \endcode + + \sa wolfSSL_no_dhe_psk +*/ +WOLFSSL_API int wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX* ctx); + +/*! + \ingroup Setup + + \brief This function is called on a TLS v1.3 client or server wolfSSL to + disallow Diffie-Hellman (DH) style key exchanges when handshakes are using + pre-shared keys for authentication. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_no_dhe_psk(ssl); + if (ret != 0) { + // failed to set no DHE for PSK handshakes + } + \endcode + + \sa wolfSSL_CTX_no_dhe_psk +*/ +WOLFSSL_API int wolfSSL_no_dhe_psk(WOLFSSL* ssl); + +/*! + \ingroup IO + + \brief This function is called on a TLS v1.3 client or server wolfSSL to + force the rollover of keys. A KeyUpdate message is sent to the peer and + new keys are calculated for encryption. The peer will send back a KeyUpdate + message and the new decryption keys wil then be calculated. + This function can only be called after a handshake has been completed. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return WANT_WRITE if the writing is not ready. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_update_keys(ssl); + if (ret == WANT_WRITE) { + // need to call again when I/O ready + } + else if (ret != WOLFSSL_SUCCESS) { + // failed to send key update + } + \endcode + + \sa wolfSSL_write +*/ +WOLFSSL_API int wolfSSL_update_keys(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function is called on a TLS v1.3 client wolfSSL context to allow + a client certifcate to be sent post handshake upon request from server. + This is useful when connecting to a web server that has some pages that + require client authentication and others that don't. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + + \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a server. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_allow_post_handshake_auth(ctx); + if (ret != 0) { + // failed to allow post handshake authentication + } + \endcode + + \sa wolfSSL_allow_post_handshake_auth + \sa wolfSSL_request_certificate +*/ +WOLFSSL_API int wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX* ctx); + +/*! + \ingroup Setup + + \brief This function is called on a TLS v1.3 client wolfSSL to allow + a client certifcate to be sent post handshake upon request from server. + A Post-Handshake Client Authentication extension is sent in the ClientHello. + This is useful when connecting to a web server that has some pages that + require client authentication and others that don't. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a server. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_allow_post_handshake_auth(ssl); + if (ret != 0) { + // failed to allow post handshake authentication + } + \endcode + + \sa wolfSSL_CTX_allow_post_handshake_auth + \sa wolfSSL_request_certificate +*/ +WOLFSSL_API int wolfSSL_allow_post_handshake_auth(WOLFSSL* ssl); + +/*! + \ingroup IO + + \brief This function requests a client certificate from the TLS v1.3 client. + This is useful when a web server is serving some pages that require client + authentication and others that don't. + A maximum of 256 requests can be sent on a connection. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return WANT_WRITE if the writing is not ready. + \return SIDE_ERROR if called with a client. + \return NOT_READY_ERROR if called when the handshake is not finished. + \return POST_HAND_AUTH_ERROR if posthandshake authentication is disallowed. + \return MEMORY_E if dynamic memory allocation fails. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_request_certificate(ssl); + if (ret == WANT_WRITE) { + // need to call again when I/O ready + } + else if (ret != WOLFSSL_SUCCESS) { + // failed to request a client certificate + } + \endcode + + \sa wolfSSL_allow_post_handshake_auth + \sa wolfSSL_write +*/ +WOLFSSL_API int wolfSSL_request_certificate(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function sets the list of elliptic curve groups to allow on + a wolfSSL context in order of preference. + The list is a null-terminated text string, and a colon-delimited list. + Call this function to set the key exchange elliptic curve parameters to + use with the TLS v1.3 connections. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + \param [in] list a string that is a colon-delimited list of elliptic curve + groups. + + \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than + WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not + using TLS v1.3. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + const char* list = "P-384:P-256"; + ... + ret = wolfSSL_CTX_set1_groups_list(ctx, list); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_set1_groups_list + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_UseKeyShare + \sa wolfSSL_preferred_group +*/ +WOLFSSL_API int wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX *ctx, char *list); + +/*! + \ingroup Setup + + \brief This function sets the list of elliptic curve groups to allow on + a wolfSSL in order of preference. + The list is a null-terminated text string, and a colon-delimited list. + Call this function to set the key exchange elliptic curve parameters to + use with the TLS v1.3 connections. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] list a string that is a colon separated list of key exchange + groups. + + \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than + WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not + using TLS v1.3. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + const char* list = "P-384:P-256"; + ... + ret = wolfSSL_CTX_set1_groups_list(ssl, list); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_CTX_set1_groups_list + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_UseKeyShare + \sa wolfSSL_preferred_group +*/ +WOLFSSL_API int wolfSSL_set1_groups_list(WOLFSSL *ssl, char *list); + +/*! + \ingroup TLS + + \brief This function returns the key exchange group the client prefers to + use in the TLS v1.3 handshake. + Call this function to after a handshake is complete to determine which + group the server prefers so that this information can be used in future + connections to pre-generate a key pair for key exchange. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a server. + \return NOT_READY_ERROR if called before handshake is complete. + \return Group identifier if successful. + + _Example_ + \code + int ret; + int group; + WOLFSSL* ssl; + ... + ret = wolfSSL_CTX_set1_groups_list(ssl) + if (ret < 0) { + // failed to get group + } + group = ret; + \endcode + + \sa wolfSSL_UseKeyShare + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_CTX_set1_groups_list + \sa wolfSSL_set1_groups_list +*/ +WOLFSSL_API int wolfSSL_preferred_group(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function sets the list of elliptic curve groups to allow on + a wolfSSL context in order of preference. + The list is an array of group identifiers with the number of identifiers + specified in count. + Call this function to set the key exchange elliptic curve parameters to + use with the TLS v1.3 connections. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + \param [in] groups a list of key exhange groups by identifier. + \param [in] count the number of key exchange groups in groups. + + \return BAD_FUNC_ARG if a pointer parameter is null, the number of groups + exceeds WOLFSSL_MAX_GROUP_COUNT or not using TLS v1.3. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 }; + int count = 2; + ... + ret = wolfSSL_CTX_set1_groups_list(ctx, groups, count); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_set_groups + \sa wolfSSL_UseKeyShare + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_CTX_set1_groups_list + \sa wolfSSL_set1_groups_list + \sa wolfSSL_preferred_group +*/ +WOLFSSL_API int wolfSSL_CTX_set_groups(WOLFSSL_CTX* ctx, int* groups, + int count); + +/*! + \ingroup Setup + + \brief This function sets the list of elliptic curve groups to allow on + a wolfSSL. + The list is an array of group identifiers with the number of identifiers + specified in count. + Call this function to set the key exchange elliptic curve parameters to + use with the TLS v1.3 connections. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] groups a list of key exhange groups by identifier. + \param [in] count the number of key exchange groups in groups. + + \return BAD_FUNC_ARG if a pointer parameter is null, the number of groups + exceeds WOLFSSL_MAX_GROUP_COUNT or not using TLS v1.3. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 }; + int count = 2; + ... + ret = wolfSSL_set1_groups_list(ssl, groups, count); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_UseKeyShare + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_CTX_set1_groups_list + \sa wolfSSL_set1_groups_list + \sa wolfSSL_preferred_group +*/ +WOLFSSL_API int wolfSSL_set_groups(WOLFSSL* ssl, int* groups, int count); + +/*! + \ingroup IO + + \brief This function is called on the client side and initiates a + TLS v1.3 handshake with a server. When this function is called, the + underlying communication channel has already been set up. + wolfSSL_connect() works with both blocking and non-blocking I/O. + When the underlying I/O is non-blocking, wolfSSL_connect() will return + when the underlying I/O could not satisfy the needs of wolfSSL_connect + to continue the handshake. In this case, a call to wolfSSL_get_error() + will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The + calling process must then repeat the call to wolfSSL_connect() when + the underlying I/O is ready and wolfSSL will pick up where it left off. + When using a non-blocking socket, nothing needs to be done, but select() + can be used to check for the required condition. If the underlying I/O is + blocking, wolfSSL_connect() will only return once the handshake has been + finished or an error occurred. wolfSSL takes a different approach to + certificate verification than OpenSSL does. The default policy for the + client is to verify the server, this means that if you don't load CAs to + verify the server you'll get a connect error, unable to verify (-155). It + you want to mimic OpenSSL behavior of having SSL_connect succeed even if + verifying the server fails and reducing security you can do this by + calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling + SSL_new(); Though it's not recommended. + + \return SSL_SUCCESS upon success. + \return SSL_FATAL_ERROR will be returned if an error occurred. To get a + more detailed error code, call wolfSSL_get_error(). + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + + ret = wolfSSL_connect_TLSv13(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_get_error + \sa wolfSSL_connect + \sa wolfSSL_accept_TLSv13 + \sa wolfSSL_accept +*/ +WOLFSSL_API int wolfSSL_connect_TLSv13(WOLFSSL*); + +/*! + \ingroup IO + + \brief This function is called on the server side and waits for a SSL/TLS + client to initiate the SSL/TLS handshake. When this function is called, + the underlying communication channel has already been set up. + wolfSSL_accept() works with both blocking and non-blocking I/O. + When the underlying I/O is non-blocking, wolfSSL_accept() will return + when the underlying I/O could not satisfy the needs of wolfSSL_accept + to continue the handshake. In this case, a call to wolfSSL_get_error() + will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. + The calling process must then repeat the call to wolfSSL_accept when + data is available to read and wolfSSL will pick up where it left off. + When using a non-blocking socket, nothing needs to be done, but select() + can be used to check for the required condition. If the underlying I/O + is blocking, wolfSSL_accept() will only return once the handshake has + been finished or an error occurred. + Call this function when expecting a TLS v1.3 connection though older + version ClientHello messages are supported. + + \return SSL_SUCCESS upon success. + \return SSL_FATAL_ERROR will be returned if an error occurred. To get a + more detailed error code, call wolfSSL_get_error(). + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + + ret = wolfSSL_accept_TLSv13(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_get_error + \sa wolfSSL_connect_TLSv13 + \sa wolfSSL_connect + \sa wolfSSL_accept_TLSv13 + \sa wolfSSL_accept +*/ +WOLFSSL_API wolfSSL_accept_TLSv13(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function sets the maximum amount of early data that will be + accepted by a TLS v1.3 server using the wolfSSL context. + Call this function to limit the amount of early data to process to mitigate + replay attacks. Early data is protected by keys derived from those of the + connection that the session ticket was sent and therefore will be the same + every time a session ticket is used in resumption. + The value is included in the session ticket for resumption. + A value of zero indicates no early data is to be sent by client using + session tickets. + It is recommended that the number of early data bytes be kept as low as + practically possible in the application. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + \param [in] sz the amount of early data to accept in bytes. + + \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a client. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_set_max_early_data(ctx, 128); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_set_max_early_data + \sa wolfSSL_write_early_data + \sa wolfSSL_read_early_data +*/ +WOLFSSL_API int wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX* ctx, + unsigned int sz); + +/*! + \ingroup Setup + + \brief This function sets the maximum amount of early data that will be + accepted by a TLS v1.3 server using the wolfSSL context. + Call this function to limit the amount of early data to process to mitigate + replay attacks. Early data is protected by keys derived from those of the + connection that the session ticket was sent and therefore will be the same + every time a session ticket is used in resumption. + The value is included in the session ticket for resumption. + A value of zero indicates no early data is to be sent by client using + session tickets. + It is recommended that the number of early data bytes be kept as low as + practically possible in the application. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] sz the amount of early data to accept from client in bytes. + + \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3. + \return SIDE_ERROR if called with a client. + \return 0 if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_set_max_early_data(ssl, 128); + if (ret != WOLFSSL_SUCCESS) { + // failed to set group list + } + \endcode + + \sa wolfSSL_CTX_set_max_early_data + \sa wolfSSL_write_early_data + \sa wolfSSL_read_early_data +*/ +WOLFSSL_API int wolfSSL_set_max_early_data(WOLFSSL* ssl, unsigned int sz); + +/*! + \ingroup IO + + \brief This function writes early data to the server on resumption. + Call this function instead of wolfSSL_connect() or wolfSSL_connect_TLSv13() + to connect to the server and send the data in the handshake. + This function is only used with clients. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] data the buffer holding the early data to write to server. + \param [in] sz the amount of early data to write in bytes. + \param [out] outSz the amount of early data written in bytes. + + \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or + not using TLSv1.3. + \return SIDE_ERROR if called with a server. + \return WOLFSSL_FATAL_ERROR if the connection is not made. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + byte earlyData[] = { early data }; + int outSz; + char buffer[80]; + ... + + ret = wolfSSL_write_early_data(ssl, earlyData, sizeof(earlyData), &outSz); + if (ret != WOLFSSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + goto err_label; + } + if (outSz < sizeof(earlyData)) { + // not all early data was sent + } + ret = wolfSSL_connect_TLSv13(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_read_early_data + \sa wolfSSL_connect + \sa wolfSSL_connect_TLSv13 +*/ +WOLFSSL_API int wolfSSL_write_early_data(OLFSSL* ssl, const void* data, + int sz, int* outSz); + +/*! + \ingroup IO + + \brief This function reads any early data from a client on resumption. + Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13() + to accept a client and read any early data in the handshake. + If there is no early data than the handshake will be processed as normal. + This function is only used with servers. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [out] data a buffer to hold the early data read from client. + \param [in] sz size of the buffer in bytes. + \param [out] outSz number of bytes of early data read. + + \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or + not using TLSv1.3. + \return SIDE_ERROR if called with a client. + \return WOLFSSL_FATAL_ERROR if accepting a connection fails. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + byte earlyData[128]; + int outSz; + char buffer[80]; + ... + + ret = wolfSSL_read_early_data(ssl, earlyData, sizeof(earlyData), &outSz); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + if (outSz > 0) { + // early data available + } + ret = wolfSSL_accept_TLSv13(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_write_early_data + \sa wolfSSL_accept + \sa wolfSSL_accept_TLSv13 +*/ +WOLFSSL_API int wolfSSL_read_early_data(WOLFSSL* ssl, void* data, int sz, + int* outSz); + +/*! + \ingroup Setup + + \brief This function sets the Pre-Shared Key (PSK) client side callback + for TLS v1.3 connections. + The callback is used to find a PSK identity and return its key and + the name of the cipher to use for the handshake. + The function sets the client_psk_tls13_cb member of the + WOLFSSL_CTX structure. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client. + + _Example_ + \code + WOLFSSL_CTX* ctx; + ... + wolfSSL_CTX_set_psk_client_tls13_callback(ctx, my_psk_client_tls13_cb); + \endcode + + \sa wolfSSL_set_psk_client_tls13_callback + \sa wolfSSL_CTX_set_psk_server_tls13_callback + \sa wolfSSL_set_psk_server_tls13_callback +*/ +WOLFSSL_API void wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX* ctx, + wc_psk_client_tls13_callback cb); + +/*! + \ingroup Setup + + \brief This function sets the Pre-Shared Key (PSK) client side callback + for TLS v1.3 connections. + The callback is used to find a PSK identity and return its key and + the name of the cipher to use for the handshake. + The function sets the client_psk_tls13_cb member of the options field in + WOLFSSL structure. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client. + + _Example_ + \code + WOLFSSL* ssl; + ... + wolfSSL_set_psk_client_tls13_callback(ssl, my_psk_client_tls13_cb); + \endcode + + \sa wolfSSL_CTX_set_psk_client_tls13_callback + \sa wolfSSL_CTX_set_psk_server_tls13_callback + \sa wolfSSL_set_psk_server_tls13_callback +*/ +WOLFSSL_API void wolfSSL_set_psk_client_tls13_callback(WOLFSSL* ssl, + wc_psk_client_tls13_callback cb); + +/*! + \ingroup Setup + + \brief This function sets the Pre-Shared Key (PSK) server side callback + for TLS v1.3 connections. + The callback is used to find a PSK identity and return its key and + the name of the cipher to use for the handshake. + The function sets the server_psk_tls13_cb member of the + WOLFSSL_CTX structure. + + \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created + with wolfSSL_CTX_new(). + \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server. + + _Example_ + \code + WOLFSSL_CTX* ctx; + ... + wolfSSL_CTX_set_psk_server_tls13_callback(ctx, my_psk_client_tls13_cb); + \endcode + + \sa wolfSSL_CTX_set_psk_client_tls13_callback + \sa wolfSSL_set_psk_client_tls13_callback + \sa wolfSSL_set_psk_server_tls13_callback +*/ +WOLFSSL_API void wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX* ctx, + wc_psk_server_tls13_callback cb); + +/*! + \ingroup Setup + + \brief This function sets the Pre-Shared Key (PSK) server side callback + for TLS v1.3 connections. + The callback is used to find a PSK identity and return its key and + the name of the cipher to use for the handshake. + The function sets the server_psk_tls13_cb member of the options field in + WOLFSSL structure. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server. + + _Example_ + \code + WOLFSSL* ssl; + ... + wolfSSL_set_psk_server_tls13_callback(ssl, my_psk_server_tls13_cb); + \endcode + + \sa wolfSSL_CTX_set_psk_client_tls13_callback + \sa wolfSSL_set_psk_client_tls13_callback + \sa wolfSSL_CTX_set_psk_server_tls13_callback +*/ +WOLFSSL_API void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl, + wc_psk_server_tls13_callback cb); + +/*! + \ingroup Setup + + \brief This function creates a key share entry from the group including + generating a key pair. + The KeyShare extension contains all the generated public keys for key + exchange. If this function is called, then only the groups specified will + be included. + Call this function when a preferred group has been previously established + for the server. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param [in] group a key exchange group identifier. + + \return BAD_FUNC_ARG if ssl is NULL. + \return MEMORY_E when dynamic memory allocation fails. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_UseKeyShare(ssl, WOLFSSL_ECC_X25519); + if (ret != WOLFSSL_SUCCESS) { + // failed to set key share + } + \endcode + + \sa wolfSSL_preferred_group + \sa wolfSSL_CTX_set1_groups_list + \sa wolfSSL_set1_groups_list + \sa wolfSSL_CTX_set_groups + \sa wolfSSL_set_groups + \sa wolfSSL_NoKeyShares +*/ +WOLFSSL_API int wolfSSL_UseKeyShare(WOLFSSL* ssl, word16 group); + +/*! + \ingroup Setup + + \brief This function is called to ensure no key shares are sent in the + ClientHello. This will force the server to respond with a HelloRetryRequest + if a key exchange is required in the handshake. + Call this function when the expected key exchange group is not known and + to avoid the generation of keys unnecessarily. + Note that an extra round-trip will be required to complete the handshake + when a key exchange is required. + + \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + \return BAD_FUNC_ARG if ssl is NULL. + \return SIDE_ERROR if called with a server. + \return WOLFSSL_SUCCESS if successful. + + _Example_ + \code + int ret; + WOLFSSL* ssl; + ... + ret = wolfSSL_NoKeyShares(ssl); + if (ret != WOLFSSL_SUCCESS) { + // failed to set no key shares + } + \endcode + + \sa wolfSSL_UseKeyShare +*/ +WOLFSSL_API int wolfSSL_NoKeyShares(WOLFSSL* ssl); + +/*! + \ingroup Setup + + \brief This function is used to indicate + that the application is a server and will only support the TLS 1.3 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context + with wolfSSL_CTX_new(). + + \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation. + + \return If successful, the call will return a pointer to the newly + created WOLFSSL_METHOD structure. + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned + (typically NULL with errno will be set to ENOMEM). + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_3_server_method_ex(NULL); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_server_method_ex(void* heap); + +/*! + \ingroup Setup + + \brief This function is used to indicate + that the application is a client and will only support the TLS 1.3 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context + with wolfSSL_CTX_new(). + + \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation. + + \return If successful, the call will return a pointer to the newly + created WOLFSSL_METHOD structure. + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned + (typically NULL with errno will be set to ENOMEM). + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_3_client_method_ex(NULL); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_client_method_ex(void* heap); + +/*! + \ingroup Setup + + \brief This function is used to indicate + that the application is a server and will only support the TLS 1.3 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context + with wolfSSL_CTX_new(). + + \return If successful, the call will return a pointer to the newly + created WOLFSSL_METHOD structure. + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned + (typically NULL with errno will be set to ENOMEM). + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_3_server_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfTLSv1_3_server_method_ex + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_server_method(void); + +/*! + \ingroup Setup + + \brief This function is used to indicate + that the application is a client and will only support the TLS 1.3 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context + with wolfSSL_CTX_new(). + + \return If successful, the call will return a pointer to the newly + created WOLFSSL_METHOD structure. + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned + (typically NULL with errno will be set to ENOMEM). + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_3_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfTLSv1_3_client_method_ex + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_client_method(void); + +/*! + \ingroup Setup + + \brief This function returns a WOLFSSL_METHOD similar to + wolfTLSv1_3_client_method except that it is not determined + which side yet (server/client). + + \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation. + + \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD + pointer + \return NULL Null if memory allocation error or failure to create method + + _Example_ + \code + WOLFSSL* ctx; + ctx = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL)); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_method_ex(void* heap); + +/*! + \ingroup Setup + + \brief This function returns a WOLFSSL_METHOD similar to + wolfTLSv1_3_client_method except that it is not determined + which side yet (server/client). + + \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD + pointer + \return NULL Null if memory allocation error or failure to create method + + _Example_ + \code + WOLFSSL* ctx; + ctx = wolfSSL_CTX_new(wolfTLSv1_3_method()); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_3_method(void); + diff --git a/wolfssl/ssl.h b/wolfssl/ssl.h index 606e2c12d..f01f121d6 100644 --- a/wolfssl/ssl.h +++ b/wolfssl/ssl.h @@ -891,8 +891,10 @@ WOLFSSL_API int wolfSSL_accept_TLSv13(WOLFSSL*); WOLFSSL_API int wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX* ctx, unsigned int sz); WOLFSSL_API int wolfSSL_set_max_early_data(WOLFSSL* ssl, unsigned int sz); -WOLFSSL_API int wolfSSL_write_early_data(WOLFSSL*, const void*, int, int*); -WOLFSSL_API int wolfSSL_read_early_data(WOLFSSL*, void*, int, int*); +WOLFSSL_API int wolfSSL_write_early_data(WOLFSSL* ssl, const void* data, + int sz, int* outSz); +WOLFSSL_API int wolfSSL_read_early_data(WOLFSSL* ssl, void* data, int sz, + int* outSz); #endif /* WOLFSSL_EARLY_DATA */ #endif /* WOLFSSL_TLS13 */ WOLFSSL_ABI WOLFSSL_API void wolfSSL_CTX_free(WOLFSSL_CTX*);