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: Ben Kaduk <kaduk@mit.edu>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5463)

2 files changed, 61 insertions, 2 deletions

diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod
index 70f6a25cde..858e393161 100644
--- a/doc/man3/DTLSv1_listen.pod
+++ b/doc/man3/DTLSv1_listen.pod
@@ -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
diff --git a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
new file mode 100644
index 0000000000..f29153ed25
--- /dev/null
+++ b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
@@ -0,0 +1,58 @@
+=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