1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
.\"
.\" $OpenBSD: SSL_SESSION_free.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
.\"
.Dd $Mdocdate: November 5 2016 $
.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
|
