[openssl] master update
Matt Caswell
matt at openssl.org
Mon Sep 30 14:31:28 UTC 2019
The branch master has been updated
via 84f471ecab76a16281a16c53d259bbcae358816f (commit)
from 7e3ae24832e0705583b1471febf3dc0eb1cc021f (commit)
- Log -----------------------------------------------------------------
commit 84f471ecab76a16281a16c53d259bbcae358816f
Author: Matt Caswell <matt at openssl.org>
Date: Fri Sep 27 11:24:26 2019 +0100
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 at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10033)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/DTLSv1_listen.pod | 12 ++--
.../SSL_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<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 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<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
More information about the openssl-commits
mailing list