Add SSL_new_session_ticket() API

This API requests that the TLS stack generate a (TLS 1.3)
NewSessionTicket message the next time it is safe to do so (i.e., we do
not have other data pending write, which could be mid-record).  For
efficiency, defer actually generating/writing the ticket until there
is other data to write, to avoid producing server-to-client traffic when
not needed.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11416)

1 files changed, 23 insertions, 4 deletions

diff --git a/doc/man3/SSL_CTX_set_num_tickets.pod b/doc/man3/SSL_CTX_set_num_tickets.pod
index 84afe4ae6a..5d4bd6f5be 100644
--- a/doc/man3/SSL_CTX_set_num_tickets.pod
+++ b/doc/man3/SSL_CTX_set_num_tickets.pod
@@ -5,7 +5,8 @@
 SSL_set_num_tickets,
 SSL_get_num_tickets,
 SSL_CTX_set_num_tickets,
-SSL_CTX_get_num_tickets
+SSL_CTX_get_num_tickets,
+SSL_new_session_ticket
 - control the number of TLSv1.3 session tickets that are issued
 
 =head1 SYNOPSIS
@@ -16,6 +17,7 @@ SSL_CTX_get_num_tickets
  size_t SSL_get_num_tickets(SSL *s);
  int SSL_CTX_set_num_tickets(SSL_CTX *ctx, size_t num_tickets);
  size_t SSL_CTX_get_num_tickets(SSL_CTX *ctx);
+ int SSL_new_session_ticket(SSL *s);
 
 =head1 DESCRIPTION
 
@@ -40,14 +42,29 @@ handshake then SSL_set_num_tickets() can be called again prior to calling
 SSL_verify_client_post_handshake() to update the number of tickets that will be
 sent.
 
+To issue tickets after other events (such as application-layer changes),
+SSL_new_session_ticket() is used by a server application to request that a new
+ticket be sent when it is safe to do so.  New tickets are only allowed to be
+sent in this manner after the initial handshake has completed, and only for TLS
+1.3 connections.  The ticket generation and transmission are delayed until the
+server is starting a new write operation, so that it is bundled with other
+application data being written and properly aligned to a record boundary.
+SSL_new_session_ticket() can be called more than once to request additional
+tickets be sent; all such requests are queued and written together when it is
+safe to do so.  Note that a successful return from SSL_new_session_ticket()
+indicates only that the request to send a ticket was processed, not that the
+ticket itself was sent.  To be notified when the ticket itself is sent, a
+new-session callback can be registered with L<SSL_CTX_sess_set_new_cb(3)> that
+will be invoked as the ticket or tickets are generated.
+
 SSL_CTX_get_num_tickets() and SSL_get_num_tickets() return the number of
 tickets set by a previous call to SSL_CTX_set_num_tickets() or
 SSL_set_num_tickets(), or 2 if no such call has been made.
 
 =head1 RETURN VALUES
 
-SSL_CTX_set_num_tickets() and SSL_set_num_tickets() return 1 on success or 0 on
-failure.
+SSL_CTX_set_num_tickets(), SSL_set_num_tickets(), and
+SSL_new_session_ticket() return 1 on success or 0 on failure.
 
 SSL_CTX_get_num_tickets() and SSL_get_num_tickets() return the number of tickets
 that have been previously set.
@@ -58,7 +75,9 @@ L<ssl(7)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.1.1.
+SSL_new_session_ticket() was added in OpenSSL 3.0.0.
+SSL_set_num_tickets(), SSL_get_num_tickets(), SSL_CTX_set_num_tickets(), and
+SSL_CTX_get_num_tickets() were added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT