xref: /openssl/doc/man3/SSL_SESSION_get_time.pod (revision 0f77b6f1) 
1=pod
2
3=head1 NAME
4
5SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout,
6SSL_SESSION_set_timeout, SSL_SESSION_get_time_ex, SSL_SESSION_set_time_ex,
7SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout
8- retrieve and manipulate session time and timeout settings
9
10=head1 SYNOPSIS
11
12 #include <openssl/ssl.h>
13
14 long SSL_SESSION_get_timeout(const SSL_SESSION *s);
15 long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm);
16
17 long SSL_get_timeout(const SSL_SESSION *s);
18 long SSL_set_timeout(SSL_SESSION *s, long tm);
19
20 time_t SSL_SESSION_get_time_ex(const SSL_SESSION *s);
21 time_t SSL_SESSION_set_time_ex(SSL_SESSION *s, time_t tm);
22
23The following functions have been deprecated since OpenSSL 3.4, and can be
24hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
25see L<openssl_user_macros(7)>:
26
27 long SSL_SESSION_get_time(const SSL_SESSION *s);
28 long SSL_SESSION_set_time(SSL_SESSION *s, long tm);
29 long SSL_get_time(const SSL_SESSION *s);
30 long SSL_set_time(SSL_SESSION *s, long tm);
31
32=head1 DESCRIPTION
33
34SSL_SESSION_get_time_ex() returns the time at which the session B<s> was
35established. The time is given in seconds since the Epoch and therefore
36compatible to the time delivered by the time() call.
37
38SSL_SESSION_set_time_ex() replaces the creation time of the session B<s> with
39the chosen value B<tm>.
40
41SSL_SESSION_get_timeout() returns the timeout value set for session B<s>
42in seconds.
43
44SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds
45to B<tm>.
46
47SSL_SESSION_get_time() and SSL_SESSION_set_time() functions use
48the long datatype instead of time_t and are therefore deprecated due to not
49being Y2038-safe on 32 bit systems. Note that such systems still need
50to be configured to use 64 bit time_t to be able to avoid overflow in system time.
51
52The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout()
53functions are synonyms for the SSL_SESSION_*() counterparts.
54
55=head1 NOTES
56
57Sessions are expired by examining the creation time and the timeout value.
58Both are set at creation time of the session to the actual time and the
59default timeout value at creation, respectively, as set by
60L<SSL_CTX_set_timeout(3)>.
61Using these functions it is possible to extend or shorten the lifetime
62of the session.
63
64=head1 RETURN VALUES
65
66SSL_SESSION_get_time_ex() and SSL_SESSION_get_timeout() return the currently
67valid values.
68
69SSL_SESSION_set_time_ex() returns time on success.
70
71SSL_SESSION_set_timeout() returns 1 on success.
72
73If any of the function is passed the NULL pointer for the session B<s>,
740 is returned.
75
76=head1 BUGS
77
78The data type long is typically 32 bits on many systems, hence the old
79functions SSL_SESSION_get_time() and SSL_SESSION_set_time() are not always
80Y2038 safe.
81
82=head1 SEE ALSO
83
84L<ssl(7)>,
85L<SSL_CTX_set_timeout(3)>,
86L<SSL_get_default_timeout(3)>
87
88=head1 HISTORY
89
90The functions SSL_SESSION_get_time_ex() and SSL_SESSION_set_time_ex() were
91added in OpenSSL 3.3.
92
93=head1 COPYRIGHT
94
95Copyright 2001-2024 The OpenSSL Project Authors. All Rights Reserved.
96
97Licensed under the Apache License 2.0 (the "License").  You may not use
98this file except in compliance with the License.  You can obtain a copy
99in the file LICENSE in the source distribution or at
100L<https://www.openssl.org/source/license.html>.
101
102=cut
103