From: Benjamin Kaduk <bkaduk@akamai.com>
Date: Fri, 9 Apr 2021 01:41:46 +0000 (-0700)
Subject: Update SSL_new_session_ticket() manual for triggered send
X-Git-Tag: openssl-3.0.0-alpha17~21
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6e495312fda0e669d105172c1ac8a8c0bf52da6d;p=thirdparty%2Fopenssl.git

Update SSL_new_session_ticket() manual for triggered send

Document the recently added functionality.

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

diff --git a/doc/man3/SSL_CTX_set_num_tickets.pod b/doc/man3/SSL_CTX_set_num_tickets.pod
index aa673bd8d07..7ab62d3ad32 100644
--- a/doc/man3/SSL_CTX_set_num_tickets.pod
+++ b/doc/man3/SSL_CTX_set_num_tickets.pod
@@ -45,17 +45,22 @@ 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.
+sent in this manner after the initial handshake has completed, and only for
+TLS 1.3 connections.  By default, 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.  If the connection was at a record boundary when
+SSL_new_session_ticket() was called, the ticket can be sent immediately
+(without waiting for the next application write) by calling
+SSL_do_handshake().  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 and triggered by SSL_write() or
+SSL_do_handshake().  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