.\"
.\"	$OpenBSD: SSL_get_session.3,v 1.3 2014/12/04 18:27:10 schwarze Exp $
.\"
.Dd $Mdocdate: December 4 2014 $
.Dt SSL_GET_SESSION 3
.Os
.Sh NAME
.Nm SSL_get_session ,
.Nm SSL_get0_session ,
.Nm SSL_get1_session
.Nd retrieve TLS/SSL session data
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft SSL_SESSION *
.Fn SSL_get_session "const SSL *ssl"
.Ft SSL_SESSION *
.Fn SSL_get0_session "const SSL *ssl"
.Ft SSL_SESSION *
.Fn SSL_get1_session "SSL *ssl"
.Sh DESCRIPTION
.Fn SSL_get_session
returns a pointer to the
.Vt SSL_SESSION
actually used in
.Fa ssl .
The reference count of the
.Vt SSL_SESSION
is not incremented, so that the pointer can become invalid by other operations.
.Pp
.Fn SSL_get0_session
is the same as
.Fn SSL_get_session .
.Pp
.Fn SSL_get1_session
is the same as
.Fn SSL_get_session ,
but the reference count of the
.Vt SSL_SESSION
is incremented by one.
.Sh NOTES
The
Fa ssl
session contains all information required to re-establish the connection
without a new handshake.
.Pp
.Fn SSL_get0_session
returns a pointer to the actual session.
As the reference counter is not incremented,
the pointer is only valid while the connection is in use.
If
.Xr SSL_clear 3
or
.Xr SSL_free 3
is called, the session may be removed completely (if considered bad),
and the pointer obtained will become invalid.
Even if the session is valid,
it can be removed at any time due to timeout during
.Xr SSL_CTX_flush_sessions 3 .
.Pp
If the data is to be kept,
.Fn SSL_get1_session
will increment the reference count, so that the session will not be implicitly
removed by other operations but stays in memory.
In order to remove the session
.Xr SSL_SESSION_free 3
must be explicitly called once to decrement the reference count again.
.Pp
.Vt SSL_SESSION
objects keep internal link information about the session cache list when being
inserted into one
.Vt SSL_CTX
object's session cache.
One
.Vt SSL_SESSION
object, regardless of its reference count, must therefore only be used with one
.Vt SSL_CTX
object (and the
.Vt SSL
objects created from this
.Vt SSL_CTX
object).
.Sh RETURN VALUES
The following return values can occur:
.Bl -tag -width Ds
.It Dv NULL
There is no session available in
.Fa ssl .
.It Pointer to an Vt SSL
The return value points to the data of an
.Vt SSL
session.
.El
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_clear 3 ,
.Xr SSL_free 3 ,
.Xr SSL_SESSION_free 3