3.\"
4.\" Standard preamble:
5.\" ======================================================================
6.de Sh \" Subsection heading
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
14.de Sp \" Vertical space (when we can't use .PP)
15.if t .sp .5v
16.if n .sp
17..
18.de Ip \" List item
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
24.de Vb \" Begin verbatim text
25.ft CW
26.nf
27.ne \\$1
28..
29.de Ve \" End verbatim text
30.ft R
31
32.fi
33..
34.\" Set up some character translations and predefined strings. \*(-- will
35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
36.\" double quote, and \*(R" will give a right double quote. | will give a
37.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
38.\" to do unbreakable dashes and therefore won't be available. \*(C` and
39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
40.tr \(*W-|\(bv\*(Tr
41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
42.ie n \{\
43. ds -- \(*W-
44. ds PI pi
45. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
46. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47. ds L" ""
48. ds R" ""
49. ds C` ""
50. ds C' ""
51'br\}
52.el\{\
53. ds -- \|\(em\|
54. ds PI \(*p
55. ds L" ``
56. ds R" ''
57'br\}
58.\"
59.\" If the F register is turned on, we'll generate index entries on stderr
60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
61.\" index entries marked with X<> in POD. Of course, you'll have to process
62.\" the output yourself in some meaningful fashion.
63.if \nF \{\
64. de IX
65. tm Index:\\$1\t\\n%\t"\\$2"
66..
67. nr % 0
68. rr F
69.\}
70.\"
71.\" For nroff, turn off justification. Always turn off hyphenation; it
72.\" makes way too many mistakes in technical documents.
73.hy 0
74.if n .na
75.\"
76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
77.\" Fear. Run. Save yourself. No user-serviceable parts.
78.bd B 3
79. \" fudge factors for nroff and troff
80.if n \{\
81. ds #H 0
82. ds #V .8m
83. ds #F .3m
84. ds #[ \f1
85. ds #] \fP
86.\}
87.if t \{\
88. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89. ds #V .6m
90. ds #F 0
91. ds #[ \&
92. ds #] \&
93.\}
94. \" simple accents for nroff and troff
95.if n \{\
96. ds ' \&
97. ds ` \&
98. ds ^ \&
99. ds , \&
100. ds ~ ~
101. ds /
102.\}
103.if t \{\
104. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
105. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
106. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
107. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
108. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
109. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
110.\}
111. \" troff and (daisy-wheel) nroff accents
112.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
113.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
114.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
115.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
116.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
117.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
118.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
119.ds ae a\h'-(\w'a'u*4/10)'e
120.ds Ae A\h'-(\w'A'u*4/10)'E
121. \" corrections for vroff
122.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
123.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
124. \" for low resolution devices (crt and lpr)
125.if \n(.H>23 .if \n(.V>19 \
126\{\
127. ds : e
128. ds 8 ss
129. ds o a
130. ds d- d\h'-1'\(ga
131. ds D- D\h'-1'\(hy
132. ds th \o'bp'
133. ds Th \o'LP'
134. ds ae ae
135. ds Ae AE
136.\}
137.rm #[ #] #H #V #F C
138.\" ======================================================================
139.\"
140.IX Title "SSL_CTX_sess_set_get_cb 3"
| 3.\"
4.\" Standard preamble:
5.\" ======================================================================
6.de Sh \" Subsection heading
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
14.de Sp \" Vertical space (when we can't use .PP)
15.if t .sp .5v
16.if n .sp
17..
18.de Ip \" List item
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
24.de Vb \" Begin verbatim text
25.ft CW
26.nf
27.ne \\$1
28..
29.de Ve \" End verbatim text
30.ft R
31
32.fi
33..
34.\" Set up some character translations and predefined strings. \*(-- will
35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
36.\" double quote, and \*(R" will give a right double quote. | will give a
37.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
38.\" to do unbreakable dashes and therefore won't be available. \*(C` and
39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
40.tr \(*W-|\(bv\*(Tr
41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
42.ie n \{\
43. ds -- \(*W-
44. ds PI pi
45. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
46. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47. ds L" ""
48. ds R" ""
49. ds C` ""
50. ds C' ""
51'br\}
52.el\{\
53. ds -- \|\(em\|
54. ds PI \(*p
55. ds L" ``
56. ds R" ''
57'br\}
58.\"
59.\" If the F register is turned on, we'll generate index entries on stderr
60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
61.\" index entries marked with X<> in POD. Of course, you'll have to process
62.\" the output yourself in some meaningful fashion.
63.if \nF \{\
64. de IX
65. tm Index:\\$1\t\\n%\t"\\$2"
66..
67. nr % 0
68. rr F
69.\}
70.\"
71.\" For nroff, turn off justification. Always turn off hyphenation; it
72.\" makes way too many mistakes in technical documents.
73.hy 0
74.if n .na
75.\"
76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
77.\" Fear. Run. Save yourself. No user-serviceable parts.
78.bd B 3
79. \" fudge factors for nroff and troff
80.if n \{\
81. ds #H 0
82. ds #V .8m
83. ds #F .3m
84. ds #[ \f1
85. ds #] \fP
86.\}
87.if t \{\
88. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89. ds #V .6m
90. ds #F 0
91. ds #[ \&
92. ds #] \&
93.\}
94. \" simple accents for nroff and troff
95.if n \{\
96. ds ' \&
97. ds ` \&
98. ds ^ \&
99. ds , \&
100. ds ~ ~
101. ds /
102.\}
103.if t \{\
104. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
105. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
106. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
107. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
108. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
109. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
110.\}
111. \" troff and (daisy-wheel) nroff accents
112.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
113.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
114.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
115.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
116.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
117.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
118.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
119.ds ae a\h'-(\w'a'u*4/10)'e
120.ds Ae A\h'-(\w'A'u*4/10)'E
121. \" corrections for vroff
122.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
123.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
124. \" for low resolution devices (crt and lpr)
125.if \n(.H>23 .if \n(.V>19 \
126\{\
127. ds : e
128. ds 8 ss
129. ds o a
130. ds d- d\h'-1'\(ga
131. ds D- D\h'-1'\(hy
132. ds th \o'bp'
133. ds Th \o'LP'
134. ds ae ae
135. ds Ae AE
136.\}
137.rm #[ #] #H #V #F C
138.\" ======================================================================
139.\"
140.IX Title "SSL_CTX_sess_set_get_cb 3"
|
142.UC
143.SH "NAME"
144SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb \- provide callback functions for server side external session caching
145.SH "SYNOPSIS"
146.IX Header "SYNOPSIS"
147.Vb 1
148\& #include <openssl/ssl.h>
149.Ve
150.Vb 6
151\& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
152\& int (*new_session_cb)(SSL *, SSL_SESSION *));
153\& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
154\& void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
155\& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
156\& SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
157.Ve
158.Vb 3
159\& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
160\& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
161\& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
162.Ve
163.Vb 4
164\& int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
165\& void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
166\& SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
167\& int len, int *copy);
168.Ve
169.SH "DESCRIPTION"
170.IX Header "DESCRIPTION"
171\&\fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
172called whenever a new session was negotiated.
173.PP
174\&\fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
175automatically called whenever a session is removed by the \s-1SSL\s0 engine,
176because it is considered faulty or the session has become obsolete because
177of exceeding the timeout value.
178.PP
179\&\fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
180whenever a \s-1SSL/TLS\s0 client proposed to resume a session but the session
181could not be found in the internal session cache (see
182SSL_CTX_set_session_cache_mode(3)).
183(\s-1SSL/TLS\s0 server only.)
184.PP
185\&\fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR, and
186\&\fISSL_CTX_sess_get_get_cb()\fR allow to retrieve the function pointers of the
187provided callback functions. If a callback function has not been set,
188the \s-1NULL\s0 pointer is returned.
189.SH "NOTES"
190.IX Header "NOTES"
191In order to allow external session caching, synchronization with the internal
192session cache is realized via callback functions. Inside these callback
193functions, session can be saved to disk or put into a database using the
194d2i_SSL_SESSION(3) interface.
195.PP
196The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
197and session caching is enabled (see
198SSL_CTX_set_session_cache_mode(3)).
199The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
200\&\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
201removed again.
202.PP
203The \fIremove_session_cb()\fR is called, whenever the \s-1SSL\s0 engine removes a session
204from the internal cache. This happens if the session is removed because
205it is expired or when a connection was not shutdown cleanly. The
206\&\fIremove_session_cb()\fR is passed the \fBctx\fR and the ssl session \fBsess\fR.
207It does not provide any feedback.
208.PP
209The \fIget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers with the session id
210proposed by the client. The \fIget_session_cb()\fR is always called, also when
211session caching was disabled. The \fIget_session_cb()\fR is passed the
212\&\fBssl\fR connection, the session id of length \fBlength\fR at the memory location
213\&\fBdata\fR. With the parameter \fBcopy\fR the callback can require the
214\&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object,
215Normally the reference count is not incremented and therefore the
216session must not be explicitly freed with
217SSL_SESSION_free(3).
218.SH "SEE ALSO"
219.IX Header "SEE ALSO"
220ssl(3), d2i_SSL_SESSION(3),
221SSL_CTX_set_session_cache_mode(3),
222SSL_CTX_flush_sessions(3),
223SSL_SESSION_free(3)
| 142.UC
143.SH "NAME"
144SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb \- provide callback functions for server side external session caching
145.SH "SYNOPSIS"
146.IX Header "SYNOPSIS"
147.Vb 1
148\& #include <openssl/ssl.h>
149.Ve
150.Vb 6
151\& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
152\& int (*new_session_cb)(SSL *, SSL_SESSION *));
153\& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
154\& void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
155\& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
156\& SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
157.Ve
158.Vb 3
159\& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
160\& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
161\& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
162.Ve
163.Vb 4
164\& int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
165\& void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
166\& SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
167\& int len, int *copy);
168.Ve
169.SH "DESCRIPTION"
170.IX Header "DESCRIPTION"
171\&\fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
172called whenever a new session was negotiated.
173.PP
174\&\fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
175automatically called whenever a session is removed by the \s-1SSL\s0 engine,
176because it is considered faulty or the session has become obsolete because
177of exceeding the timeout value.
178.PP
179\&\fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
180whenever a \s-1SSL/TLS\s0 client proposed to resume a session but the session
181could not be found in the internal session cache (see
182SSL_CTX_set_session_cache_mode(3)).
183(\s-1SSL/TLS\s0 server only.)
184.PP
185\&\fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR, and
186\&\fISSL_CTX_sess_get_get_cb()\fR allow to retrieve the function pointers of the
187provided callback functions. If a callback function has not been set,
188the \s-1NULL\s0 pointer is returned.
189.SH "NOTES"
190.IX Header "NOTES"
191In order to allow external session caching, synchronization with the internal
192session cache is realized via callback functions. Inside these callback
193functions, session can be saved to disk or put into a database using the
194d2i_SSL_SESSION(3) interface.
195.PP
196The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
197and session caching is enabled (see
198SSL_CTX_set_session_cache_mode(3)).
199The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
200\&\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
201removed again.
202.PP
203The \fIremove_session_cb()\fR is called, whenever the \s-1SSL\s0 engine removes a session
204from the internal cache. This happens if the session is removed because
205it is expired or when a connection was not shutdown cleanly. The
206\&\fIremove_session_cb()\fR is passed the \fBctx\fR and the ssl session \fBsess\fR.
207It does not provide any feedback.
208.PP
209The \fIget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers with the session id
210proposed by the client. The \fIget_session_cb()\fR is always called, also when
211session caching was disabled. The \fIget_session_cb()\fR is passed the
212\&\fBssl\fR connection, the session id of length \fBlength\fR at the memory location
213\&\fBdata\fR. With the parameter \fBcopy\fR the callback can require the
214\&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object,
215Normally the reference count is not incremented and therefore the
216session must not be explicitly freed with
217SSL_SESSION_free(3).
218.SH "SEE ALSO"
219.IX Header "SEE ALSO"
220ssl(3), d2i_SSL_SESSION(3),
221SSL_CTX_set_session_cache_mode(3),
222SSL_CTX_flush_sessions(3),
223SSL_SESSION_free(3)
|