Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_sess_set_get_cb.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SESS_SET_GET_CB 3SSL"
58 .TH SSL_CTX_SESS_SET_GET_CB 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_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
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
71 \& int (*new_session_cb)(SSL *, SSL_SESSION *));
72 \& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
73 \& void (*remove_session_cb)(SSL_CTX *ctx,
74 \& SSL_SESSION *));
75 \& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
76 \& SSL_SESSION (*get_session_cb)(SSL *,
77 \& const unsigned char *,
78 \& int, int *));
79 \&
80 \& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
81 \& SSL_SESSION *sess);
82 \& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx,
83 \& SSL_SESSION *sess);
84 \& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
85 \& const unsigned char *data,
86 \& int len, int *copy);
87 .Ve
88 .SH DESCRIPTION
89 .IX Header "DESCRIPTION"
90 \&\fBSSL_CTX_sess_set_new_cb()\fR sets the callback function that is
91 called whenever a new session was negotiated.
92 .PP
93 \&\fBSSL_CTX_sess_set_remove_cb()\fR sets the callback function that is
94 called whenever a session is removed by the SSL engine. For example,
95 this can occur because a session is considered faulty or has become obsolete
96 because of exceeding the timeout value.
97 .PP
98 \&\fBSSL_CTX_sess_set_get_cb()\fR sets the callback function that is called
99 whenever a TLS client proposed to resume a session but the session
100 could not be found in the internal session cache (see
101 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3)).
102 (TLS server only.)
103 .PP
104 \&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR, and
105 \&\fBSSL_CTX_sess_get_get_cb()\fR retrieve the function pointers set by the
106 corresponding set callback functions. If a callback function has not been
107 set, the NULL pointer is returned.
108 .SH NOTES
109 .IX Header "NOTES"
110 In order to allow external session caching, synchronization with the internal
111 session cache is realized via callback functions. Inside these callback
112 functions, session can be saved to disk or put into a database using the
113 \&\fBd2i_SSL_SESSION\fR\|(3) interface.
114 .PP
115 The \fBnew_session_cb()\fR is called whenever a new session has been negotiated and
116 session caching is enabled (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). The
117 \&\fBnew_session_cb()\fR is passed the \fBssl\fR connection and the nascent
118 ssl session \fBsess\fR.
119 Since sessions are reference-counted objects, the reference count on the
120 session is incremented before the callback, on behalf of the application. If
121 the callback returns \fB0\fR, the session will be immediately removed from the
122 internal cache and the reference count released. If the callback returns \fB1\fR,
123 the application retains the reference (for an entry in the
124 application-maintained "external session cache"), and is responsible for
125 calling \fBSSL_SESSION_free()\fR when the session reference is no longer in use.
126 .PP
127 Note that in TLSv1.3, sessions are established after the main
128 handshake has completed. The server decides when to send the client the session
129 information and this may occur some time after the end of the handshake (or not
130 at all). This means that applications should expect the \fBnew_session_cb()\fR
131 function to be invoked during the handshake (for <= TLSv1.2) or after the
132 handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to
133 be established with a single connection. In these case the \fBnew_session_cb()\fR
134 function will be invoked multiple times.
135 .PP
136 In TLSv1.3 it is recommended that each SSL_SESSION object is only used for
137 resumption once. One way of enforcing that is for applications to call
138 \&\fBSSL_CTX_remove_session\fR\|(3) after a session has been used.
139 .PP
140 The \fBremove_session_cb()\fR is called whenever the SSL engine removes a session
141 from the internal cache. This can happen when the session is removed because
142 it is expired or when a connection was not shutdown cleanly. It also happens
143 for all sessions in the internal session cache when
144 \&\fBSSL_CTX_free\fR\|(3) is called. The \fBremove_session_cb()\fR is passed
145 the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
146 .PP
147 The \fBget_session_cb()\fR is only called on SSL/TLS servers, and is given
148 the session id
149 proposed by the client. The \fBget_session_cb()\fR is always called, even when
150 session caching was disabled. The \fBget_session_cb()\fR is passed the
151 \&\fBssl\fR connection and the session id of length \fBlength\fR at the memory location
152 \&\fBdata\fR. By setting the parameter \fBcopy\fR to \fB1\fR, the callback can require the
153 SSL engine to increment the reference count of the SSL_SESSION object;
154 setting \fBcopy\fR to \fB0\fR causes the reference count to remain unchanged.
155 If the \fBget_session_cb()\fR does not write to \fBcopy\fR, the reference count
156 is incremented and the session must be explicitly freed with
157 \&\fBSSL_SESSION_free\fR\|(3).
158 .SH "RETURN VALUES"
159 .IX Header "RETURN VALUES"
160 \&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR and \fBSSL_CTX_sess_get_get_cb()\fR
161 return different callback function pointers respectively.
162 .SH "SEE ALSO"
163 .IX Header "SEE ALSO"
164 \&\fBssl\fR\|(7), \fBd2i_SSL_SESSION\fR\|(3),
165 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
166 \&\fBSSL_CTX_flush_sessions\fR\|(3),
167 \&\fBSSL_SESSION_free\fR\|(3),
168 \&\fBSSL_CTX_free\fR\|(3)
169 .SH COPYRIGHT
170 .IX Header "COPYRIGHT"
171 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
172 .PP
173 Licensed under the Apache License 2.0 (the "License"). You may not use
174 this file except in compliance with the License. You can obtain a copy
175 in the file LICENSE in the source distribution or at
176 <https://www.openssl.org/source/license.html>.