12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091 |
- =pod
- =head1 NAME
- SSL_set_num_tickets,
- SSL_get_num_tickets,
- SSL_CTX_set_num_tickets,
- SSL_CTX_get_num_tickets,
- SSL_new_session_ticket
- - control the number of TLSv1.3 session tickets that are issued
- =head1 SYNOPSIS
- #include <openssl/ssl.h>
- int SSL_set_num_tickets(SSL *s, size_t 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
- SSL_CTX_set_num_tickets() and SSL_set_num_tickets() can be called for a server
- application and set the number of TLSv1.3 session tickets that will be sent to
- the client after a full handshake. Set the desired value (which could be 0) in
- the B<num_tickets> argument. Typically these functions should be called before
- the start of the handshake.
- The default number of tickets is 2; the default number of tickets sent following
- a resumption handshake is 1 but this cannot be changed using these functions.
- The number of tickets following a resumption handshake can be reduced to 0 using
- custom session ticket callbacks (see L<SSL_CTX_set_session_ticket_cb(3)>).
- Tickets are also issued on receipt of a post-handshake certificate from the
- client following a request by the server using
- L<SSL_verify_client_post_handshake(3)>. These new tickets will be associated
- with the updated client identity (i.e. including their certificate and
- verification status). The number of tickets issued will normally be the same as
- was used for the initial handshake. If the initial handshake was a full
- 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(), 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.
- =head1 SEE ALSO
- L<ssl(7)>
- =head1 HISTORY
- 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
- Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
- Licensed under the Apache License 2.0 (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
|