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 <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10033)

(cherry picked from commit 84f471ecab76a16281a16c53d259bbcae358816f)

diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod
index 76be40b68f10cf75473098421ebbe227fb7da740..98511a475f9fda35f56b30b6c330749ebd560896 100644 (file)
--- 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<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)>
+respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)>
+and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> 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<SSL_get_error(3)>, L<SSL_accept(3)>,
-L<ssl(7)>, L<bio(7)>
+L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>,
+L<SSL_CTX_set_stateless_cookie_generate_cb(3)>,
+L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>,
+L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>
 
 =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 f29153ed25d8ab1b91e16d504a15696140ec1af1..aa167f6332ed54f56bd7179b78e878c0c1fbdd52 100644 (file)
--- 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<SSL_stateless(3)>
-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<cookie>, and must write the number of bytes
-written to B<cookie_len>. 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<SSL_stateless(3)> 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<SSL_stateless(3)> 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<cookie>, and must write the number
+of bytes written to B<cookie_len>. 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<SSL_stateless(3)> to determine whether the application-controlled portion of a
+ClientHello cookie is valid. The cookie data is pointed to by B<cookie> and is of
+length B<cookie_len>. 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<DTLSv1_listen(3)>
+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<cookie>, and must write the number of bytes written to B<cookie_len>. 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<DTLSv1_listen(3)> to
+determine whether the cookie in a ClientHello is valid. The cookie data is
+pointed to by B<cookie> and is of length B<cookie_len>. 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<SSL_stateless(3)>
+L<SSL_stateless(3)>,
+L<DTLSv1_listen(3)>
+
+=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