diff options
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.3 | 159 |
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 | ||
68 | sets the callback function which is automatically called whenever a new session | ||
69 | was negotiated. | ||
70 | .Pp | ||
71 | .Fn SSL_CTX_sess_set_remove_cb | ||
72 | sets the callback function which is automatically called whenever a session is | ||
73 | removed by the SSL engine (because it is considered faulty or the session has | ||
74 | become obsolete because of exceeding the timeout value). | ||
75 | .Pp | ||
76 | .Fn SSL_CTX_sess_set_get_cb | ||
77 | sets the callback function which is called whenever a SSL/TLS client proposes | ||
78 | to resume a session but the session cannot be found in the internal session | ||
79 | cache (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 , | ||
85 | and | ||
86 | .Fn SSL_CTX_sess_get_get_cb | ||
87 | retrieve the function pointers of the provided callback functions. | ||
88 | If a callback function has not been set, the | ||
89 | .Dv NULL | ||
90 | pointer is returned. | ||
91 | .Sh NOTES | ||
92 | In order to allow external session caching, synchronization with the internal | ||
93 | session cache is realized via callback functions. | ||
94 | Inside these callback functions, session can be saved to disk or put into a | ||
95 | database using the | ||
96 | .Xr d2i_SSL_SESSION 3 | ||
97 | interface. | ||
98 | .Pp | ||
99 | The | ||
100 | .Fn new_session_cb | ||
101 | function is called whenever a new session has been negotiated and session | ||
102 | caching is enabled (see | ||
103 | .Xr SSL_CTX_set_session_cache_mode 3 ) . | ||
104 | The | ||
105 | .Fn new_session_cb | ||
106 | is passed the | ||
107 | .Fa ssl | ||
108 | connection and the ssl session | ||
109 | .Fa sess . | ||
110 | If the callback returns 0, the session will be immediately removed again. | ||
111 | .Pp | ||
112 | The | ||
113 | .Fn remove_session_cb | ||
114 | is called whenever the SSL engine removes a session from the internal cache. | ||
115 | This happens when the session is removed because it is expired or when a | ||
116 | connection was not shut down cleanly. | ||
117 | It also happens for all sessions in the internal session cache when | ||
118 | .Xr SSL_CTX_free 3 | ||
119 | is called. | ||
120 | The | ||
121 | .Fn remove_session_cb | ||
122 | function is passed the | ||
123 | .Fa ctx | ||
124 | and the | ||
125 | .Vt ssl | ||
126 | session | ||
127 | .Fa sess . | ||
128 | It does not provide any feedback. | ||
129 | .Pp | ||
130 | The | ||
131 | .Fn get_session_cb | ||
132 | function is only called on SSL/TLS servers with the session id proposed by the | ||
133 | client. | ||
134 | The | ||
135 | .Fn get_session_cb | ||
136 | function is always called, also when session caching was disabled. | ||
137 | The | ||
138 | .Fn get_session_cb | ||
139 | is passed the | ||
140 | .Fa ssl | ||
141 | connection, the session id of length | ||
142 | .Fa length | ||
143 | at the memory location | ||
144 | .Fa data . | ||
145 | With the parameter | ||
146 | .Fa copy | ||
147 | the callback can require the SSL engine to increment the reference count of the | ||
148 | .Vt SSL_SESSION | ||
149 | object, | ||
150 | Normally the reference count is not incremented and therefore the session must | ||
151 | not 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 | ||