1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/ssl.h> 10*4724848cSchristos 11*4724848cSchristos SSL_SESSION *SSL_get_session(const SSL *ssl); 12*4724848cSchristos SSL_SESSION *SSL_get0_session(const SSL *ssl); 13*4724848cSchristos SSL_SESSION *SSL_get1_session(SSL *ssl); 14*4724848cSchristos 15*4724848cSchristos=head1 DESCRIPTION 16*4724848cSchristos 17*4724848cSchristosSSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in 18*4724848cSchristosB<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so 19*4724848cSchristosthat the pointer can become invalid by other operations. 20*4724848cSchristos 21*4724848cSchristosSSL_get0_session() is the same as SSL_get_session(). 22*4724848cSchristos 23*4724848cSchristosSSL_get1_session() is the same as SSL_get_session(), but the reference 24*4724848cSchristoscount of the B<SSL_SESSION> is incremented by one. 25*4724848cSchristos 26*4724848cSchristos=head1 NOTES 27*4724848cSchristos 28*4724848cSchristosThe ssl session contains all information required to re-establish the 29*4724848cSchristosconnection without a full handshake for SSL versions up to and including 30*4724848cSchristosTLSv1.2. In TLSv1.3 the same is true, but sessions are established after the 31*4724848cSchristosmain handshake has occurred. The server will send the session information to the 32*4724848cSchristosclient at a time of its choosing, which may be some while after the initial 33*4724848cSchristosconnection is established (or never). Calling these functions on the client side 34*4724848cSchristosin TLSv1.3 before the session has been established will still return an 35*4724848cSchristosSSL_SESSION object but that object cannot be used for resuming the session. See 36*4724848cSchristosL<SSL_SESSION_is_resumable(3)> for information on how to determine whether an 37*4724848cSchristosSSL_SESSION object can be used for resumption or not. 38*4724848cSchristos 39*4724848cSchristosAdditionally, in TLSv1.3, a server can send multiple messages that establish a 40*4724848cSchristossession for a single connection. In that case, on the client side, the above 41*4724848cSchristosfunctions will only return information on the last session that was received. On 42*4724848cSchristosthe server side they will only return information on the last session that was 43*4724848cSchristossent, or if no session tickets were sent then the session for the current 44*4724848cSchristosconnection. 45*4724848cSchristos 46*4724848cSchristosThe preferred way for applications to obtain a resumable SSL_SESSION object is 47*4724848cSchristosto use a new session callback as described in L<SSL_CTX_sess_set_new_cb(3)>. 48*4724848cSchristosThe new session callback is only invoked when a session is actually established, 49*4724848cSchristosso this avoids the problem described above where an application obtains an 50*4724848cSchristosSSL_SESSION object that cannot be used for resumption in TLSv1.3. It also 51*4724848cSchristosenables applications to obtain information about all sessions sent by the 52*4724848cSchristosserver. 53*4724848cSchristos 54*4724848cSchristosA session will be automatically removed from the session cache and marked as 55*4724848cSchristosnon-resumable if the connection is not closed down cleanly, e.g. if a fatal 56*4724848cSchristoserror occurs on the connection or L<SSL_shutdown(3)> is not called prior to 57*4724848cSchristosL<SSL_free(3)>. 58*4724848cSchristos 59*4724848cSchristosIn TLSv1.3 it is recommended that each SSL_SESSION object is only used for 60*4724848cSchristosresumption once. 61*4724848cSchristos 62*4724848cSchristosSSL_get0_session() returns a pointer to the actual session. As the 63*4724848cSchristosreference counter is not incremented, the pointer is only valid while 64*4724848cSchristosthe connection is in use. If L<SSL_clear(3)> or 65*4724848cSchristosL<SSL_free(3)> is called, the session may be removed completely 66*4724848cSchristos(if considered bad), and the pointer obtained will become invalid. Even 67*4724848cSchristosif the session is valid, it can be removed at any time due to timeout 68*4724848cSchristosduring L<SSL_CTX_flush_sessions(3)>. 69*4724848cSchristos 70*4724848cSchristosIf the data is to be kept, SSL_get1_session() will increment the reference 71*4724848cSchristoscount, so that the session will not be implicitly removed by other operations 72*4724848cSchristosbut stays in memory. In order to remove the session 73*4724848cSchristosL<SSL_SESSION_free(3)> must be explicitly called once 74*4724848cSchristosto decrement the reference count again. 75*4724848cSchristos 76*4724848cSchristosSSL_SESSION objects keep internal link information about the session cache 77*4724848cSchristoslist, when being inserted into one SSL_CTX object's session cache. 78*4724848cSchristosOne SSL_SESSION object, regardless of its reference count, must therefore 79*4724848cSchristosonly be used with one SSL_CTX object (and the SSL objects created 80*4724848cSchristosfrom this SSL_CTX object). 81*4724848cSchristos 82*4724848cSchristos=head1 RETURN VALUES 83*4724848cSchristos 84*4724848cSchristosThe following return values can occur: 85*4724848cSchristos 86*4724848cSchristos=over 4 87*4724848cSchristos 88*4724848cSchristos=item NULL 89*4724848cSchristos 90*4724848cSchristosThere is no session available in B<ssl>. 91*4724848cSchristos 92*4724848cSchristos=item Pointer to an SSL_SESSION 93*4724848cSchristos 94*4724848cSchristosThe return value points to the data of an SSL session. 95*4724848cSchristos 96*4724848cSchristos=back 97*4724848cSchristos 98*4724848cSchristos=head1 SEE ALSO 99*4724848cSchristos 100*4724848cSchristosL<ssl(7)>, L<SSL_free(3)>, 101*4724848cSchristosL<SSL_clear(3)>, 102*4724848cSchristosL<SSL_SESSION_free(3)> 103*4724848cSchristos 104*4724848cSchristos=head1 COPYRIGHT 105*4724848cSchristos 106*4724848cSchristosCopyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 107*4724848cSchristos 108*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 109*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 110*4724848cSchristosin the file LICENSE in the source distribution or at 111*4724848cSchristosL<https://www.openssl.org/source/license.html>. 112*4724848cSchristos 113*4724848cSchristos=cut 114