diff options
author | Benjamin Kaduk <bkaduk@akamai.com> | 2020-03-16 11:25:58 -0700 |
---|---|---|
committer | Ben Kaduk <kaduk@mit.edu> | 2020-05-01 15:10:11 -0700 |
commit | 3bfacb5fd4679812a7b9ec61d296b1add64669c0 (patch) | |
tree | bc10cebef57dc828c7da742dada9a3e05910884a /doc/man3/SSL_CTX_set_num_tickets.pod | |
parent | 6250282f7fc37c5903d051174a69053a80e1b1bd (diff) |
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)
Diffstat (limited to 'doc/man3/SSL_CTX_set_num_tickets.pod')
-rw-r--r-- | doc/man3/SSL_CTX_set_num_tickets.pod | 27 |
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 |