mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-11 04:23:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Correct the function names in SSL_CTX_set_stateless_cookie_generate_cb.pod

Browse Source 
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)
This commit is contained in:
Matt Caswell 2019-09-27 11:24:26 +01:00
parent 7e3ae24832
commit 84f471ecab
2 changed files with 59 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/man3/DTLSv1_listen.pod
View File

@ -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

67
doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
View File

@ -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_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_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_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