1=pod 2 3=head1 NAME 4 5SSL_CTX_set_stateless_cookie_generate_cb, 6SSL_CTX_set_stateless_cookie_verify_cb, 7SSL_CTX_set_cookie_generate_cb, 8SSL_CTX_set_cookie_verify_cb 9- Callback functions for stateless TLS1.3 cookies 10 11=head1 SYNOPSIS 12 13 #include <openssl/ssl.h> 14 15 void SSL_CTX_set_stateless_cookie_generate_cb( 16 SSL_CTX *ctx, 17 int (*gen_stateless_cookie_cb) (SSL *ssl, 18 unsigned char *cookie, 19 size_t *cookie_len)); 20 void SSL_CTX_set_stateless_cookie_verify_cb( 21 SSL_CTX *ctx, 22 int (*verify_stateless_cookie_cb) (SSL *ssl, 23 const unsigned char *cookie, 24 size_t cookie_len)); 25 26 void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx, 27 int (*app_gen_cookie_cb) (SSL *ssl, 28 unsigned char 29 *cookie, 30 unsigned int 31 *cookie_len)); 32 void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx, 33 int (*app_verify_cookie_cb) (SSL *ssl, 34 const unsigned 35 char *cookie, 36 unsigned int 37 cookie_len)); 38 39=head1 DESCRIPTION 40 41SSL_CTX_set_stateless_cookie_generate_cb() sets the callback used by 42L<SSL_stateless(3)> to generate the application-controlled portion of the cookie 43provided to clients in the HelloRetryRequest transmitted as a response to a 44ClientHello with a missing or invalid cookie. gen_stateless_cookie_cb() must 45write at most SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number 46of bytes written to B<cookie_len>. If a cookie cannot be generated, a zero 47return value can be used to abort the handshake. 48 49SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by 50L<SSL_stateless(3)> to determine whether the application-controlled portion of a 51ClientHello cookie is valid. The cookie data is pointed to by B<cookie> and is of 52length B<cookie_len>. A nonzero return value from verify_stateless_cookie_cb() 53communicates that the cookie is valid. The integrity of the entire cookie, 54including the application-controlled portion, is automatically verified by HMAC 55before verify_stateless_cookie_cb() is called. 56 57SSL_CTX_set_cookie_generate_cb() sets the callback used by L<DTLSv1_listen(3)> 58to generate the cookie provided to clients in the HelloVerifyRequest transmitted 59as a response to a ClientHello with a missing or invalid cookie. 60app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into 61B<cookie>, and must write the number of bytes written to B<cookie_len>. If a 62cookie cannot be generated, a zero return value can be used to abort the 63handshake. 64 65SSL_CTX_set_cookie_verify_cb() sets the callback used by L<DTLSv1_listen(3)> to 66determine whether the cookie in a ClientHello is valid. The cookie data is 67pointed to by B<cookie> and is of length B<cookie_len>. A nonzero return value 68from app_verify_cookie_cb() communicates that the cookie is valid. The 69integrity of the cookie is not verified by OpenSSL. This is an application 70responsibility. 71 72=head1 RETURN VALUES 73 74Neither function returns a value. 75 76=head1 SEE ALSO 77 78L<ssl(7)>, 79L<SSL_stateless(3)>, 80L<DTLSv1_listen(3)> 81 82=head1 HISTORY 83 84SSL_CTX_set_stateless_cookie_generate_cb() and 85SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1. 86 87=head1 COPYRIGHT 88 89Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. 90 91Licensed under the Apache License 2.0 (the "License"). You may not use 92this file except in compliance with the License. You can obtain a copy 93in the file LICENSE in the source distribution or at 94L<https://www.openssl.org/source/license.html>. 95 96=cut 97