summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3')
-rw-r--r--src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3159
1 files changed, 0 insertions, 159 deletions
diff --git a/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 b/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3
deleted file mode 100644
index 7a372138c1..0000000000
--- a/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3
+++ /dev/null
@@ -1,159 +0,0 @@
1.\"
2.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
3.\"
4.Dd $Mdocdate: December 2 2014 $
5.Dt SSL_CTX_SESS_SET_GET_CB 3
6.Os
7.Sh NAME
8.Nm SSL_CTX_sess_set_new_cb ,
9.Nm SSL_CTX_sess_set_remove_cb ,
10.Nm SSL_CTX_sess_set_get_cb ,
11.Nm SSL_CTX_sess_get_new_cb ,
12.Nm SSL_CTX_sess_get_remove_cb ,
13.Nm SSL_CTX_sess_get_get_cb
14.Nd provide callback functions for server side external session caching
15.Sh SYNOPSIS
16.In openssl/ssl.h
17.Ft void
18.Fo SSL_CTX_sess_set_new_cb
19.Fa "SSL_CTX *ctx"
20.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)"
21.Fc
22.Ft void
23.Fo SSL_CTX_sess_set_remove_cb
24.Fa "SSL_CTX *ctx"
25.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)"
26.Fc
27.Ft void
28.Fo SSL_CTX_sess_set_get_cb
29.Fa "SSL_CTX *ctx"
30.Fa "SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)"
31.Fc
32.Ft int
33.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))"
34.Fa "struct ssl_st *ssl"
35.Fa "SSL_SESSION *sess"
36.Fc
37.Ft void
38.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
39.Fa "struct ssl_ctx_st *ctx"
40.Fa "SSL_SESSION *sess"
41.Fc
42.Ft SSL_SESSION *
43.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
44.Fa "struct ssl_st *ssl"
45.Fa "unsigned char *data"
46.Fa "int len"
47.Fa "int *copy"
48.Fc
49.Ft int
50.Fo "(*new_session_cb)"
51.Fa "struct ssl_st *ssl"
52.Fa "SSL_SESSION *sess"
53.Fc
54.Ft void
55.Fo "(*remove_session_cb)"
56.Fa "struct ssl_ctx_st *ctx"
57.Fa "SSL_SESSION *sess"
58.Fc
59.Ft SSL_SESSION *
60.Fo "(*get_session_cb)"
61.Fa "struct ssl_st *ssl"
62.Fa "unsigned char *data"
63.Fa "int len"
64.Fa "int *copy"
65.Fc
66.Sh DESCRIPTION
67.Fn SSL_CTX_sess_set_new_cb
68sets the callback function which is automatically called whenever a new session
69was negotiated.
70.Pp
71.Fn SSL_CTX_sess_set_remove_cb
72sets the callback function which is automatically called whenever a session is
73removed by the SSL engine (because it is considered faulty or the session has
74become obsolete because of exceeding the timeout value).
75.Pp
76.Fn SSL_CTX_sess_set_get_cb
77sets the callback function which is called whenever a SSL/TLS client proposes
78to resume a session but the session cannot be found in the internal session
79cache (see
80.Xr SSL_CTX_set_session_cache_mode 3 ) .
81(SSL/TLS server only.)
82.Pp
83.Fn SSL_CTX_sess_get_new_cb ,
84.Fn SSL_CTX_sess_get_remove_cb ,
85and
86.Fn SSL_CTX_sess_get_get_cb
87retrieve the function pointers of the provided callback functions.
88If a callback function has not been set, the
89.Dv NULL
90pointer is returned.
91.Sh NOTES
92In order to allow external session caching, synchronization with the internal
93session cache is realized via callback functions.
94Inside these callback functions, session can be saved to disk or put into a
95database using the
96.Xr d2i_SSL_SESSION 3
97interface.
98.Pp
99The
100.Fn new_session_cb
101function is called whenever a new session has been negotiated and session
102caching is enabled (see
103.Xr SSL_CTX_set_session_cache_mode 3 ) .
104The
105.Fn new_session_cb
106is passed the
107.Fa ssl
108connection and the ssl session
109.Fa sess .
110If the callback returns 0, the session will be immediately removed again.
111.Pp
112The
113.Fn remove_session_cb
114is called whenever the SSL engine removes a session from the internal cache.
115This happens when the session is removed because it is expired or when a
116connection was not shut down cleanly.
117It also happens for all sessions in the internal session cache when
118.Xr SSL_CTX_free 3
119is called.
120The
121.Fn remove_session_cb
122function is passed the
123.Fa ctx
124and the
125.Vt ssl
126session
127.Fa sess .
128It does not provide any feedback.
129.Pp
130The
131.Fn get_session_cb
132function is only called on SSL/TLS servers with the session id proposed by the
133client.
134The
135.Fn get_session_cb
136function is always called, also when session caching was disabled.
137The
138.Fn get_session_cb
139is passed the
140.Fa ssl
141connection, the session id of length
142.Fa length
143at the memory location
144.Fa data .
145With the parameter
146.Fa copy
147the callback can require the SSL engine to increment the reference count of the
148.Vt SSL_SESSION
149object,
150Normally the reference count is not incremented and therefore the session must
151not be explicitly freed with
152.Xr SSL_SESSION_free 3 .
153.Sh SEE ALSO
154.Xr d2i_SSL_SESSION 3 ,
155.Xr ssl 3 ,
156.Xr SSL_CTX_flush_sessions 3 ,
157.Xr SSL_CTX_free 3 ,
158.Xr SSL_CTX_set_session_cache_mode 3 ,
159.Xr SSL_SESSION_free 3