From 84f471ecab76a16281a16c53d259bbcae358816f Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 27 Sep 2019 11:24:26 +0100 Subject: [PATCH] Correct the function names in SSL_CTX_set_stateless_cookie_generate_cb.pod Although the synopsis used the correct function names, the description did not. Also the description of the equivalent DTLSv1_listen() callbacks was missing, so these have been added. Fixes #10030 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10033) --- doc/man3/DTLSv1_listen.pod | 12 ++-- ...L_CTX_set_stateless_cookie_generate_cb.pod | 69 ++++++++++++++----- 2 files changed, 60 insertions(+), 21 deletions(-) diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod index be4d53143c..ebbb9b8bc6 100644 --- a/doc/man3/DTLSv1_listen.pod +++ b/doc/man3/DTLSv1_listen.pod @@ -66,9 +66,9 @@ the peer and continue the handshake in a connected state. Prior to calling DTLSv1_listen() user code must ensure that cookie generation and verification callbacks have been set up using -SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() -respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb() -and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead. +L and L +respectively. For SSL_stateless(), L +and L must be used instead. Since DTLSv1_listen() operates entirely statelessly whilst processing incoming ClientHellos it is unable to process fragmented messages (since this would @@ -112,8 +112,10 @@ errors as non-fatal), whilst return codes >0 indicate success. =head1 SEE ALSO -L, L, -L, L +L, L, +L, +L, L, +L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod index bb5c1fd130..7ec276a48d 100644 --- a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod +++ b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod @@ -3,7 +3,9 @@ =head1 NAME SSL_CTX_set_stateless_cookie_generate_cb, -SSL_CTX_set_stateless_cookie_verify_cb +SSL_CTX_set_stateless_cookie_verify_cb, +SSL_CTX_set_cookie_generate_cb, +SSL_CTX_set_cookie_verify_cb - Callback functions for stateless TLS1.3 cookies =head1 SYNOPSIS @@ -21,22 +23,51 @@ SSL_CTX_set_stateless_cookie_verify_cb const unsigned char *cookie, size_t cookie_len)); + void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx, + int (*app_gen_cookie_cb) (SSL *ssl, + unsigned char + *cookie, + unsigned int + *cookie_len)); + void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx, + int (*app_verify_cookie_cb) (SSL *ssl, + const unsigned + char *cookie, + unsigned int + cookie_len)); + =head1 DESCRIPTION -SSL_CTX_set_cookie_generate_cb() sets the callback used by L -to generate the application-controlled portion of the cookie provided to clients -in the HelloRetryRequest transmitted as a response to a ClientHello with a -missing or invalid cookie. gen_stateless_cookie_cb() must write at most -SSL_COOKIE_LENGTH bytes into B, and must write the number of bytes -written to B. If a cookie cannot be generated, a zero return value -can be used to abort the handshake. - -SSL_CTX_set_cookie_verify_cb() sets the callback used by L to -determine whether the application-controlled portion of a ClientHello cookie is -valid. A nonzero return value from app_verify_cookie_cb() communicates that the -cookie is valid. The integrity of the entire cookie, including the -application-controlled portion, is automatically verified by HMAC before -verify_stateless_cookie_cb() is called. +SSL_CTX_set_stateless_cookie_generate_cb() sets the callback used by +L to generate the application-controlled portion of the cookie +provided to clients in the HelloRetryRequest transmitted as a response to a +ClientHello with a missing or invalid cookie. gen_stateless_cookie_cb() must +write at most SSL_COOKIE_LENGTH bytes into B, and must write the number +of bytes written to B. If a cookie cannot be generated, a zero +return value can be used to abort the handshake. + +SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by +L to determine whether the application-controlled portion of a +ClientHello cookie is valid. The cookie data is pointed to by B and is of +length B. A nonzero return value from verify_stateless_cookie_cb() +communicates that the cookie is valid. The integrity of the entire cookie, +including the application-controlled portion, is automatically verified by HMAC +before verify_stateless_cookie_cb() is called. + +SSL_CTX_set_cookie_generate_cb() sets the callback used by L +to generate the cookie provided to clients in the HelloVerifyRequest transmitted +as a response to a ClientHello with a missing or invalid cookie. +app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into +B, and must write the number of bytes written to B. If a +cookie cannot be generated, a zero return value can be used to abort the +handshake. + +SSL_CTX_set_cookie_verify_cb() sets the callback used by L to +determine whether the cookie in a ClientHello is valid. The cookie data is +pointed to by B and is of length B. A nonzero return value +from app_verify_cookie_cb() communicates that the cookie is valid. The +integrity of the cookie is not verified by OpenSSL. This is an application +responsibility. =head1 RETURN VALUES @@ -44,7 +75,13 @@ Neither function returns a value. =head1 SEE ALSO -L +L, +L + +=head1 HISTORY + +SSL_CTX_set_stateless_cookie_generate_cb() and +SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1. =head1 COPYRIGHT -- 2.25.1