]>
Commit | Line | Data |
---|---|---|
1 | =pod | |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); | |
12 | long SSL_CTX_get_timeout(SSL_CTX *ctx); | |
13 | ||
14 | =head1 DESCRIPTION | |
15 | ||
16 | SSL_CTX_set_timeout() sets the timeout for newly created sessions for | |
17 | B<ctx> to B<t>. The timeout value B<t> must be given in seconds. | |
18 | ||
19 | SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. | |
20 | ||
21 | =head1 NOTES | |
22 | ||
23 | Whenever a new session is created, it is assigned a maximum lifetime. This | |
24 | lifetime is specified by storing the creation time of the session and the | |
25 | timeout value valid at this time. If the actual time is later than creation | |
26 | time plus timeout, the session is not reused. | |
27 | ||
28 | Due to this realization, all sessions behave according to the timeout value | |
29 | valid at the time of the session negotiation. Changes of the timeout value | |
30 | do not affect already established sessions. | |
31 | ||
32 | The expiration time of a single session can be modified using the | |
33 | L<SSL_SESSION_get_time(3)> family of functions. | |
34 | ||
35 | Expired sessions are removed from the internal session cache, whenever | |
36 | L<SSL_CTX_flush_sessions(3)> is called, either | |
37 | directly by the application or automatically (see | |
38 | L<SSL_CTX_set_session_cache_mode(3)>) | |
39 | ||
40 | The default value for session timeout is decided on a per protocol | |
41 | basis, see L<SSL_get_default_timeout(3)>. | |
42 | All currently supported protocols have the same default timeout value | |
43 | of 300 seconds. | |
44 | ||
45 | This timeout value is used as the ticket lifetime hint for stateless session | |
46 | tickets. It is also used as the timeout value within the ticket itself. | |
47 | ||
48 | For TLSv1.3, RFC8446 limits transmission of this value to 1 week (604800 | |
49 | seconds). | |
50 | ||
51 | For TLSv1.2, tickets generated during an initial handshake use the value | |
52 | as specified. Tickets generated during a resumed handshake have a value | |
53 | of 0 for the ticket lifetime hint. | |
54 | ||
55 | =head1 RETURN VALUES | |
56 | ||
57 | SSL_CTX_set_timeout() returns the previously set timeout value. | |
58 | ||
59 | SSL_CTX_get_timeout() returns the currently set timeout value. | |
60 | ||
61 | =head1 SEE ALSO | |
62 | ||
63 | L<ssl(7)>, | |
64 | L<SSL_CTX_set_session_cache_mode(3)>, | |
65 | L<SSL_SESSION_get_time(3)>, | |
66 | L<SSL_CTX_flush_sessions(3)>, | |
67 | L<SSL_get_default_timeout(3)> | |
68 | ||
69 | =head1 COPYRIGHT | |
70 | ||
71 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
72 | ||
73 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
74 | this file except in compliance with the License. You can obtain a copy | |
75 | in the file LICENSE in the source distribution or at | |
76 | L<https://www.openssl.org/source/license.html>. | |
77 | ||
78 | =cut |