]>
Commit | Line | Data |
---|---|---|
56548e86 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_set_num_tickets, | |
6 | SSL_get_num_tickets, | |
7 | SSL_CTX_set_num_tickets, | |
3bfacb5f BK |
8 | SSL_CTX_get_num_tickets, |
9 | SSL_new_session_ticket | |
56548e86 MC |
10 | - control the number of TLSv1.3 session tickets that are issued |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/ssl.h> | |
15 | ||
16 | int SSL_set_num_tickets(SSL *s, size_t num_tickets); | |
17 | size_t SSL_get_num_tickets(SSL *s); | |
18 | int SSL_CTX_set_num_tickets(SSL_CTX *ctx, size_t num_tickets); | |
19 | size_t SSL_CTX_get_num_tickets(SSL_CTX *ctx); | |
3bfacb5f | 20 | int SSL_new_session_ticket(SSL *s); |
56548e86 MC |
21 | |
22 | =head1 DESCRIPTION | |
23 | ||
24 | SSL_CTX_set_num_tickets() and SSL_set_num_tickets() can be called for a server | |
7ffb7fbe MC |
25 | application and set the number of TLSv1.3 session tickets that will be sent to |
26 | the client after a full handshake. Set the desired value (which could be 0) in | |
27 | the B<num_tickets> argument. Typically these functions should be called before | |
28 | the start of the handshake. | |
56548e86 MC |
29 | |
30 | The default number of tickets is 2; the default number of tickets sent following | |
31 | a resumption handshake is 1 but this cannot be changed using these functions. | |
32 | The number of tickets following a resumption handshake can be reduced to 0 using | |
33 | custom session ticket callbacks (see L<SSL_CTX_set_session_ticket_cb(3)>). | |
34 | ||
35 | Tickets are also issued on receipt of a post-handshake certificate from the | |
36 | client following a request by the server using | |
37 | L<SSL_verify_client_post_handshake(3)>. These new tickets will be associated | |
38 | with the updated client identity (i.e. including their certificate and | |
39 | verification status). The number of tickets issued will normally be the same as | |
40 | was used for the initial handshake. If the initial handshake was a full | |
41 | handshake then SSL_set_num_tickets() can be called again prior to calling | |
42 | SSL_verify_client_post_handshake() to update the number of tickets that will be | |
43 | sent. | |
44 | ||
3bfacb5f BK |
45 | To issue tickets after other events (such as application-layer changes), |
46 | SSL_new_session_ticket() is used by a server application to request that a new | |
47 | ticket be sent when it is safe to do so. New tickets are only allowed to be | |
48 | sent in this manner after the initial handshake has completed, and only for TLS | |
49 | 1.3 connections. The ticket generation and transmission are delayed until the | |
50 | server is starting a new write operation, so that it is bundled with other | |
51 | application data being written and properly aligned to a record boundary. | |
52 | SSL_new_session_ticket() can be called more than once to request additional | |
53 | tickets be sent; all such requests are queued and written together when it is | |
54 | safe to do so. Note that a successful return from SSL_new_session_ticket() | |
55 | indicates only that the request to send a ticket was processed, not that the | |
56 | ticket itself was sent. To be notified when the ticket itself is sent, a | |
57 | new-session callback can be registered with L<SSL_CTX_sess_set_new_cb(3)> that | |
58 | will be invoked as the ticket or tickets are generated. | |
59 | ||
56548e86 MC |
60 | SSL_CTX_get_num_tickets() and SSL_get_num_tickets() return the number of |
61 | tickets set by a previous call to SSL_CTX_set_num_tickets() or | |
62 | SSL_set_num_tickets(), or 2 if no such call has been made. | |
63 | ||
64 | =head1 RETURN VALUES | |
65 | ||
3bfacb5f BK |
66 | SSL_CTX_set_num_tickets(), SSL_set_num_tickets(), and |
67 | SSL_new_session_ticket() return 1 on success or 0 on failure. | |
56548e86 MC |
68 | |
69 | SSL_CTX_get_num_tickets() and SSL_get_num_tickets() return the number of tickets | |
70 | that have been previously set. | |
71 | ||
98ca37e4 RS |
72 | =head1 SEE ALSO |
73 | ||
74 | L<ssl(7)> | |
75 | ||
56548e86 MC |
76 | =head1 HISTORY |
77 | ||
3bfacb5f BK |
78 | SSL_new_session_ticket() was added in OpenSSL 3.0.0. |
79 | SSL_set_num_tickets(), SSL_get_num_tickets(), SSL_CTX_set_num_tickets(), and | |
80 | SSL_CTX_get_num_tickets() were added in OpenSSL 1.1.1. | |
56548e86 MC |
81 | |
82 | =head1 COPYRIGHT | |
83 | ||
454afd98 | 84 | Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. |
56548e86 | 85 | |
4746f25a | 86 | Licensed under the Apache License 2.0 (the "License"). You may not use |
56548e86 MC |
87 | this file except in compliance with the License. You can obtain a copy |
88 | in the file LICENSE in the source distribution or at | |
89 | L<https://www.openssl.org/source/license.html>. | |
90 | ||
91 | =cut |