Commit 3fa2812f authored by Benjamin Saunders's avatar Benjamin Saunders Committed by Matt Caswell
Browse files

Introduce SSL_CTX_set_stateless_cookie_{generate,verify}_cb 



These functions are similar to SSL_CTX_set_cookie_{generate,verify}_cb,
but used for the application-controlled portion of TLS1.3 stateless
handshake cookies rather than entire DTLSv1 cookies.

Reviewed-by: default avatarBen Kaduk <kaduk@mit.edu>
Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5463)
parent 4718f449

apps/s_apps.h

+5 −0
Original line number Diff line number Diff line
@@ -58,6 +58,11 @@ int generate_cookie_callback(SSL *ssl, unsigned char *cookie, 
int verify_cookie_callback(SSL *ssl, const unsigned char *cookie,

                           unsigned int cookie_len);



int generate_stateless_cookie_callback(SSL *ssl, unsigned char *cookie,

                                       size_t *cookie_len);

int verify_stateless_cookie_callback(SSL *ssl, const unsigned char *cookie,

                                     size_t cookie_len);



typedef struct ssl_excert_st SSL_EXCERT;



void ssl_ctx_set_excert(SSL_CTX *ctx, SSL_EXCERT *exc);

apps/s_cb.c

+16 −0
Original line number Diff line number Diff line
@@ -755,6 +755,22 @@ int verify_cookie_callback(SSL *ssl, const unsigned char *cookie, 


    return 0;

}



int generate_stateless_cookie_callback(SSL *ssl, unsigned char *cookie,

                                       size_t *cookie_len)

{

    unsigned int temp;

    int res = generate_cookie_callback(ssl, cookie, &temp);

    *cookie_len = temp;

    return res;

}



int verify_stateless_cookie_callback(SSL *ssl, const unsigned char *cookie,

                                     size_t cookie_len)

{

    return verify_cookie_callback(ssl, cookie, cookie_len);

}



#endif



/*

apps/s_server.c

+4 −0
Original line number Diff line number Diff line
@@ -2038,6 +2038,10 @@ int s_server_main(int argc, char *argv[]) 
    SSL_CTX_set_cookie_generate_cb(ctx, generate_cookie_callback);

    SSL_CTX_set_cookie_verify_cb(ctx, verify_cookie_callback);



    /* Set TLS1.3 cookie generation and verification callbacks */

    SSL_CTX_set_stateless_cookie_generate_cb(ctx, generate_stateless_cookie_callback);

    SSL_CTX_set_stateless_cookie_verify_cb(ctx, verify_stateless_cookie_callback);



    if (ctx2 != NULL) {

        SSL_CTX_set_verify(ctx2, s_server_verify, verify_callback);

        if (!SSL_CTX_set_session_id_context(ctx2,

doc/man3/DTLSv1_listen.pod

+3 −2
Original line number Diff line number Diff line
@@ -64,10 +64,11 @@ does not support this), then B<*peer> will be cleared and the family set to 
AF_UNSPEC. Typically user code is expected to "connect" the underlying socket to

the peer and continue the handshake in a connected state.



Prior to calling these functions user code must ensure that cookie generation

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.

respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb()

and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead.



Since DTLSv1_listen() operates entirely statelessly whilst processing incoming

ClientHellos it is unable to process fragmented messages (since this would

doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod

0 → 100644
+58 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



SSL_CTX_set_stateless_cookie_generate_cb,

SSL_CTX_set_stateless_cookie_verify_cb

- Callback functions for stateless TLS1.3 cookies



=head1 SYNOPSIS



 #include <openssl/ssl.h>



 void SSL_CTX_set_stateless_cookie_generate_cb(

     SSL_CTX *ctx,

     int (*gen_stateless_cookie_cb) (SSL *ssl,

                                     unsigned char *cookie,

                                     size_t *cookie_len));

 void SSL_CTX_set_stateless_cookie_verify_cb(

     SSL_CTX *ctx,

     int (*verify_stateless_cookie_cb) (SSL *ssl,

                                        const unsigned char *cookie,

                                        size_t 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.



=head1 RETURN VALUES



Neither function returns a value.



=head1 SEE ALSO



L<SSL_stateless(3)>



=head1 COPYRIGHT



Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.



Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.



=cut