.\"
.\"	$OpenBSD: SSL_SESSION_free.3,v 1.3 2015/12/30 18:45:02 millert Exp $
.\"
.Dd $Mdocdate: December 30 2015 $
.Dt SSL_SESSION_FREE 3
.Os
.Sh NAME
.Nm SSL_SESSION_free
.Nd free an allocated SSL_SESSION structure
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft void
.Fn SSL_SESSION_free "SSL_SESSION *session"
.Sh DESCRIPTION
.Fn SSL_SESSION_free
decrements the reference count of
.Fa session
and removes the
.Vt SSL_SESSION
structure pointed to by
.Fa session
and frees up the allocated memory, if the reference count has reached 0.
If
.Fa session
is a
.Dv NULL
pointer, no action occurs.
.Sh NOTES
.Vt SSL_SESSION
objects are allocated when a TLS/SSL handshake operation is successfully
completed.
Depending on the settings, see
.Xr SSL_CTX_set_session_cache_mode 3 ,
the
.Vt SSL_SESSION
objects are internally referenced by the
.Vt SSL_CTX
and linked into its session cache.
.Vt SSL
objects may be using the
.Vt SSL_SESSION
object; as a session may be reused, several
.Vt SSL
objects may be using one
.Vt SSL_SESSION
object at the same time.
It is therefore crucial to keep the reference count (usage information) correct
and not delete a
.Vt SSL_SESSION
object that is still used, as this may lead to program failures due to dangling
pointers.
These failures may also appear delayed, e.g., when an
.Vt SSL_SESSION
object is completely freed as the reference count incorrectly becomes 0, but it
is still referenced in the internal session cache and the cache list is
processed during a
.Xr SSL_CTX_flush_sessions 3
operation.
.Pp
.Fn SSL_SESSION_free
must only be called for
.Vt SSL_SESSION
objects, for which the reference count was explicitly incremented (e.g., by
calling
.Xr SSL_get1_session 3 ;
see
.Xr SSL_get_session 3 )
or when the
.Vt SSL_SESSION
object was generated outside a TLS handshake operation, e.g., by using
.Xr d2i_SSL_SESSION 3 .
It must not be called on other
.Vt SSL_SESSION
objects, as this would cause incorrect reference counts and therefore program
failures.
.Sh RETURN VALUES
.Fn SSL_SESSION_free
does not provide diagnostic information.
.Sh SEE ALSO
.Xr d2i_SSL_SESSION 3 ,
.Xr ssl 3 ,
.Xr SSL_CTX_flush_sessions 3 ,
.Xr SSL_CTX_set_session_cache_mode 3 ,
.Xr SSL_get_session 3