6a6d142d74c3cc5bda46a3500fc8daeee4fde82b
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_tlsext_ticket_key_cb.3
1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 .    ds C`
42 .    ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el       .ds Aq '
48 .\"
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
60 .    if \nF \{
61 .        de IX
62 .        tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 .        if !\nF==2 \{
65 .            nr % 0
66 .            nr F 2
67 .        \}
68 .    \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
74 .    \" fudge factors for nroff and troff
75 .if n \{\
76 .    ds #H 0
77 .    ds #V .8m
78 .    ds #F .3m
79 .    ds #[ \f1
80 .    ds #] \fP
81 .\}
82 .if t \{\
83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 .    ds #V .6m
85 .    ds #F 0
86 .    ds #[ \&
87 .    ds #] \&
88 .\}
89 .    \" simple accents for nroff and troff
90 .if n \{\
91 .    ds ' \&
92 .    ds ` \&
93 .    ds ^ \&
94 .    ds , \&
95 .    ds ~ ~
96 .    ds /
97 .\}
98 .if t \{\
99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 .    \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 .    \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 .    \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 .    ds : e
123 .    ds 8 ss
124 .    ds o a
125 .    ds d- d\h'-1'\(ga
126 .    ds D- D\h'-1'\(hy
127 .    ds th \o'bp'
128 .    ds Th \o'LP'
129 .    ds ae ae
130 .    ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "SSL_CTX_set_tlsext_ticket_key_cb 3"
136 .TH SSL_CTX_set_tlsext_ticket_key_cb 3 "2015-06-11" "1.0.1n" "OpenSSL"
137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 SSL_CTX_set_tlsext_ticket_key_cb \- set a callback for session ticket processing
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 .Vb 1
146 \& #include <openssl/tls1.h>
147 \&
148 \& long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
149 \&        int (*cb)(SSL *s, unsigned char key_name[16],
150 \&                  unsigned char iv[EVP_MAX_IV_LENGTH],
151 \&                  EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
152 .Ve
153 .SH "DESCRIPTION"
154 .IX Header "DESCRIPTION"
155 \&\fISSL_CTX_set_tlsext_ticket_key_cb()\fR sets a callback fuction \fIcb\fR for handling 
156 session tickets for the ssl context \fIsslctx\fR. Session tickets, defined in 
157 \&\s-1RFC5077\s0 provide an enhanced session resumption capability where the server
158 implementation is not required to maintain per session state. It only applies
159 to \s-1TLS\s0 and there is no SSLv3 implementation.
160 .PP
161 The callback is available when the OpenSSL library was built without 
162 \&\fI\s-1OPENSSL_NO_TLSEXT\s0\fR being defined.
163 .PP
164 The callback function \fIcb\fR will be called for every client instigated \s-1TLS\s0
165 session when session ticket extension is presented in the \s-1TLS\s0 hello
166 message. It is the responsibility of this function to create or retrieve the
167 cryptographic parameters and to maintain their state.
168 .PP
169 The OpenSSL library uses your callback function to help implement a common \s-1TLS \s0
170 ticket construction state according to \s-1RFC5077\s0 Section 4 such that per session
171 state is unnecessary and a small set of cryptographic variables needs to be 
172 maintained by the callback function implementation.
173 .PP
174 In order to reuse a session, a \s-1TLS\s0 client must send the a session ticket
175 extension to the server. The client can only send exactly one session ticket.
176 The server, through the callback function, either agrees to reuse the session
177 ticket information or it starts a full \s-1TLS\s0 handshake to create a new session
178 ticket.
179 .PP
180 Before the callback function is started \fIctx\fR and \fIhctx\fR have been 
181 initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
182 .PP
183 For new sessions tickets, when the client doesn't present a session ticket, or
184 an attempted retreival of the ticket failed, or a renew option was indicated,
185 the callback function will be called with \fIenc\fR equal to 1. The OpenSSL
186 library expects that the function will set an arbitary \fIname\fR, initialize
187 \&\fIiv\fR, and set the cipher context \fIctx\fR and the hash context \fIhctx\fR.
188 .PP
189 The \fIname\fR is 16 characters long and is used as a key identifier.
190 .PP
191 The \fIiv\fR length is the length of the \s-1IV\s0 of the corresponding cipher. The
192 maximum \s-1IV\s0 length is \s-1EVP_MAX_IV_LENGTH\s0 bytes defined in \fBevp.h\fR.
193 .PP
194 The initialization vector \fIiv\fR should be a random value. The cipher context 
195 \&\fIctx\fR should use the initialisation vector \fIiv\fR. The cipher context can be 
196 set using EVP_EncryptInit_ex. The hmac context can be set using HMAC_Init_ex.
197 .PP
198 When the client presents a session ticket, the callback function with be called 
199 with \fIenc\fR set to 0 indicating that the \fIcb\fR function should retreive a set
200 of parameters. In this case \fIname\fR and \fIiv\fR have already been parsed out of
201 the session ticket. The OpenSSL library expects that the \fIname\fR will be used
202 to retrieve a cryptographic parameters and that the cryptographic context
203 \&\fIctx\fR will be set with the retreived parameters and the initialization vector
204 \&\fIiv\fR. using a function like EVP_DecryptInit_ex. The \fIhctx\fR needs to be set
205 using HMAC_Init_ex.
206 .PP
207 If the \fIname\fR is still valid but a renewal of the ticket is required the
208 callback function should return 2. The library will call the callback again
209 with an arguement of enc equal to 1 to set the new ticket.
210 .PP
211 The return value of the \fIcb\fR function is used by OpenSSL to determine what
212 further processing will occur. The following return values have meaning:
213 .IP "2" 4
214 .IX Item "2"
215 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can 
216 continue on those parameters. Additionally it indicates that the session
217 ticket is in a renewal period and should be replaced. The OpenSSL library will
218 call \fIcb\fR again with an enc argument of 1 to set the new ticket (see \s-1RFC5077
219 3.3\s0 paragraph 2).
220 .IP "1" 4
221 .IX Item "1"
222 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can 
223 continue on those parameters.
224 .IP "0" 4
225 This indicates that it was not possible to set/retrieve a session ticket and 
226 the \s-1SSL/TLS\s0 session will continue by by negiotationing a set of cryptographic
227 parameters or using the alternate \s-1SSL/TLS\s0 resumption mechanism, session ids.
228 .Sp
229 If called with enc equal to 0 the library will call the \fIcb\fR again to get
230 a new set of parameters.
231 .IP "less than 0" 4
232 .IX Item "less than 0"
233 This indicates an error.
234 .SH "NOTES"
235 .IX Header "NOTES"
236 Session resumption shortcuts the \s-1TLS\s0 so that the client certificate
237 negiotation don't occur. It makes up for this by storing client certificate
238 an all other negotiated state information encrypted within the ticket. In a
239 resumed session the applications will have all this state information available
240 exactly as if a full negiotation had occured.
241 .PP
242 If an attacker can obtain the key used to encrypt a session ticket, they can
243 obtain the master secret for any ticket using that key and decrypt any traffic
244 using that session: even if the ciphersuite supports forward secrecy. As
245 a result applications may wish to use multiple keys and avoid using long term
246 keys stored in files.
247 .PP
248 Applications can use longer keys to maintain a consistent level of security.
249 For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key
250 the overall security is only 128 bits because breaking the ticket key will
251 enable an attacker to obtain the session keys.
252 .SH "EXAMPLES"
253 .IX Header "EXAMPLES"
254 Reference Implemention:
255   SSL_CTX_set_tlsext_ticket_key_cb(\s-1SSL\s0,ssl_tlsext_ticket_key_cb);
256   ....
257 .PP
258 .Vb 6
259 \&  static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
260 \&  {
261 \&      if (enc) { /* create new session */
262 \&          if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
263 \&              return \-1; /* insufficient random */
264 \&          }
265 \&  
266 \&          key = currentkey(); /* something that you need to implement */
267 \&          if ( !key ) {
268 \&              /* current key doesn\*(Aqt exist or isn\*(Aqt valid */
269 \&              key = createkey(); /* something that you need to implement.
270 \&                                   * createkey needs to initialise, a name,
271 \&                                   * an aes_key, a hmac_key and optionally
272 \&                                   * an expire time. */
273 \&              if ( !key ) { /* key couldn\*(Aqt be created */
274 \&                  return 0;
275 \&              }
276 \&          }
277 \&          memcpy(key_name, key\->name, 16);
278 \&  
279 \&          EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key\->aes_key, iv);
280 \&          HMAC_Init_ex(&hctx, key\->hmac_key, 16, EVP_sha256(), NULL);
281 \&  
282 \&          return 1;
283 \&  
284 \&      } else { /* retrieve session */
285 \&          key = findkey(name);
286 \&  
287 \&          if  (!key || key\->expire < now() ) {
288 \&              return 0;
289 \&          }
290 \&  
291 \&          HMAC_Init_ex(&hctx, key\->hmac_key, 16, EVP_sha256(), NULL);
292 \&          EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key\->aes_key, iv );
293 \&
294 \&          if (key\->expire < ( now() \- RENEW_TIME ) ) {
295 \&              /* return 2 \- this session will get a new ticket even though the current is still valid */
296 \&              return 2;
297 \&          }
298 \&          return 1;
299 \&  
300 \&      }
301 \&  }
302 .Ve
303 .SH "RETURN VALUES"
304 .IX Header "RETURN VALUES"
305 returns 0 to indicate the callback function was set.
306 .SH "SEE ALSO"
307 .IX Header "SEE ALSO"
308 \&\fIssl\fR\|(3), \fISSL_set_session\fR\|(3),
309 \&\fISSL_session_reused\fR\|(3),
310 \&\fISSL_CTX_add_session\fR\|(3),
311 \&\fISSL_CTX_sess_number\fR\|(3),
312 \&\fISSL_CTX_sess_set_get_cb\fR\|(3),
313 \&\fISSL_CTX_set_session_id_context\fR\|(3),
314 .SH "HISTORY"
315 .IX Header "HISTORY"
316 This function was introduced in OpenSSL 0.9.8h