1141240Snjl=pod
2167905Snjl
3141240Snjl=head1 NAME
4141240Snjl
5141240SnjlSSL_get_session - retrieve TLS/SSL session data
6141240Snjl
7141240Snjl=head1 SYNOPSIS
8141240Snjl
9141240Snjl #include <openssl/ssl.h>
10141240Snjl
11141240Snjl SSL_SESSION *SSL_get_session(const SSL *ssl);
12141240Snjl SSL_SESSION *SSL_get0_session(const SSL *ssl);
13141240Snjl SSL_SESSION *SSL_get1_session(SSL *ssl);
14141240Snjl
15141240Snjl=head1 DESCRIPTION
16141240Snjl
17141240SnjlSSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in
18141240SnjlB<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
19141240Snjlthat the pointer can become invalid by other operations.
20141240Snjl
21141240SnjlSSL_get0_session() is the same as SSL_get_session().
22141240Snjl
23141240SnjlSSL_get1_session() is the same as SSL_get_session(), but the reference
24141240Snjlcount of the B<SSL_SESSION> is incremented by one.
25141240Snjl
26141240Snjl=head1 NOTES
27141240Snjl
28141240SnjlThe ssl session contains all information required to re-establish the
29141240Snjlconnection without a new handshake.
30141240Snjl
31141240SnjlSSL_get0_session() returns a pointer to the actual session. As the
32141240Snjlreference counter is not incremented, the pointer is only valid while
33141240Snjlthe connection is in use. If L<SSL_clear(3)|SSL_clear(3)> or
34141240SnjlL<SSL_free(3)|SSL_free(3)> is called, the session may be removed completely
35142603Snjl(if considered bad), and the pointer obtained will become invalid. Even
36141240Snjlif the session is valid, it can be removed at any time due to timeout
37141240Snjlduring L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>.
38141240Snjl
39141240SnjlIf the data is to be kept, SSL_get1_session() will increment the reference
40173204Snjlcount, so that the session will not be implicitly removed by other operations
41141240Snjlbut stays in memory. In order to remove the session
42173204SnjlL<SSL_SESSION_free(3)|SSL_SESSION_free(3)> must be explicitly called once
43141240Snjlto decrement the reference count again.
44141240Snjl
45142603SnjlSSL_SESSION objects keep internal link information about the session cache
46141814Snjllist, when being inserted into one SSL_CTX object's session cache.
47167905SnjlOne SSL_SESSION object, regardless of its reference count, must therefore
48141240Snjlonly be used with one SSL_CTX object (and the SSL objects created
49141240Snjlfrom this SSL_CTX object).
50141240Snjl
51141240Snjl=head1 RETURN VALUES
52141240Snjl
53141240SnjlThe following return values can occur:
54141240Snjl
55141240Snjl=over 4
56141240Snjl
57141240Snjl=item NULL
58142395Snjl
59141240SnjlThere is no session available in B<ssl>.
60142395Snjl
61141240Snjl=item Pointer to an SSL
62150847Sume
63150847SumeThe return value points to the data of an SSL session.
64150847Sume
65150847Sume=back
66150847Sume
67150847Sume=head1 SEE ALSO
68141240Snjl
69142603SnjlL<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>,
70141240SnjlL<SSL_clear(3)|SSL_clear(3)>,
71141923SnjlL<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
72150847Sume
73141923Snjl=cut
74141413Snjl