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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.\"
.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $
.\"
.Dd $Mdocdate: November 5 2016 $
.Dt SSL_CTX_SESS_SET_GET_CB 3
.Os
.Sh NAME
.Nm SSL_CTX_sess_set_new_cb ,
.Nm SSL_CTX_sess_set_remove_cb ,
.Nm SSL_CTX_sess_set_get_cb ,
.Nm SSL_CTX_sess_get_new_cb ,
.Nm SSL_CTX_sess_get_remove_cb ,
.Nm SSL_CTX_sess_get_get_cb
.Nd provide callback functions for server side external session caching
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft void
.Fo SSL_CTX_sess_set_new_cb
.Fa "SSL_CTX *ctx"
.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)"
.Fc
.Ft void
.Fo SSL_CTX_sess_set_remove_cb
.Fa "SSL_CTX *ctx"
.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)"
.Fc
.Ft void
.Fo SSL_CTX_sess_set_get_cb
.Fa "SSL_CTX *ctx"
.Fa "SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)"
.Fc
.Ft int
.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))"
.Fa "struct ssl_st *ssl"
.Fa "SSL_SESSION *sess"
.Fc
.Ft void
.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
.Fa "struct ssl_ctx_st *ctx"
.Fa "SSL_SESSION *sess"
.Fc
.Ft SSL_SESSION *
.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
.Fa "struct ssl_st *ssl"
.Fa "unsigned char *data"
.Fa "int len"
.Fa "int *copy"
.Fc
.Ft int
.Fo "(*new_session_cb)"
.Fa "struct ssl_st *ssl"
.Fa "SSL_SESSION *sess"
.Fc
.Ft void
.Fo "(*remove_session_cb)"
.Fa "struct ssl_ctx_st *ctx"
.Fa "SSL_SESSION *sess"
.Fc
.Ft SSL_SESSION *
.Fo "(*get_session_cb)"
.Fa "struct ssl_st *ssl"
.Fa "unsigned char *data"
.Fa "int len"
.Fa "int *copy"
.Fc
.Sh DESCRIPTION
.Fn SSL_CTX_sess_set_new_cb
sets the callback function which is automatically called whenever a new session
was negotiated.
.Pp
.Fn SSL_CTX_sess_set_remove_cb
sets the callback function which is automatically called whenever a session is
removed by the SSL engine (because it is considered faulty or the session has
become obsolete because of exceeding the timeout value).
.Pp
.Fn SSL_CTX_sess_set_get_cb
sets the callback function which is called whenever a SSL/TLS client proposes
to resume a session but the session cannot be found in the internal session
cache (see
.Xr SSL_CTX_set_session_cache_mode 3 ) .
(SSL/TLS server only.)
.Pp
.Fn SSL_CTX_sess_get_new_cb ,
.Fn SSL_CTX_sess_get_remove_cb ,
and
.Fn SSL_CTX_sess_get_get_cb
retrieve the function pointers of the provided callback functions.
If a callback function has not been set, the
.Dv NULL
pointer is returned.
.Sh NOTES
In order to allow external session caching, synchronization with the internal
session cache is realized via callback functions.
Inside these callback functions, session can be saved to disk or put into a
database using the
.Xr d2i_SSL_SESSION 3
interface.
.Pp
The
.Fn new_session_cb
function is called whenever a new session has been negotiated and session
caching is enabled (see
.Xr SSL_CTX_set_session_cache_mode 3 ) .
The
.Fn new_session_cb
is passed the
.Fa ssl
connection and the ssl session
.Fa sess .
If the callback returns 0, the session will be immediately removed again.
.Pp
The
.Fn remove_session_cb
is called whenever the SSL engine removes a session from the internal cache.
This happens when the session is removed because it is expired or when a
connection was not shut down cleanly.
It also happens for all sessions in the internal session cache when
.Xr SSL_CTX_free 3
is called.
The
.Fn remove_session_cb
function is passed the
.Fa ctx
and the
.Vt ssl
session
.Fa sess .
It does not provide any feedback.
.Pp
The
.Fn get_session_cb
function is only called on SSL/TLS servers with the session id proposed by the
client.
The
.Fn get_session_cb
function is always called, also when session caching was disabled.
The
.Fn get_session_cb
is passed the
.Fa ssl
connection, the session id of length
.Fa length
at the memory location
.Fa data .
With the parameter
.Fa copy
the callback can require the SSL engine to increment the reference count of the
.Vt SSL_SESSION
object,
Normally the reference count is not incremented and therefore the session must
not be explicitly freed with
.Xr SSL_SESSION_free 3 .
.Sh SEE ALSO
.Xr d2i_SSL_SESSION 3 ,
.Xr ssl 3 ,
.Xr SSL_CTX_flush_sessions 3 ,
.Xr SSL_CTX_free 3 ,
.Xr SSL_CTX_set_session_cache_mode 3 ,
.Xr SSL_SESSION_free 3
|
