diff options
author | Matt Caswell <matt@openssl.org> | 2019-09-27 11:24:26 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-09-30 15:30:57 +0100 |
commit | 84f471ecab76a16281a16c53d259bbcae358816f (patch) | |
tree | e917bc4198aff26cee1480521f23780c757a25ea /doc | |
parent | 7e3ae24832e0705583b1471febf3dc0eb1cc021f (diff) | |
download | openssl-84f471ecab76a16281a16c53d259bbcae358816f.tar.gz |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/DTLSv1_listen.pod | 12 | ||||
-rw-r--r-- | doc/man3/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 |