Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_tmp_rsa_callback.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_set_tmp_rsa_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
a7d27d5a 191SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa \- handle RSA keys for ephemeral key exchange
984263bc 192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 4
198\& void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
199\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
200\& long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
201\& long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
202.Ve
203.Vb 4
204\& void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
205\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
206\& long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
207\& long SSL_need_tmp_rsa(SSL *ssl)
208.Ve
209.Vb 1
210\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
211.Ve
212.SH "DESCRIPTION"
a7d27d5a
JR
213\fISSL_CTX_set_tmp_rsa_callback()\fR sets the callback function for \fBctx\fR to be
214used when a temporary/ephemeral RSA key is required to \fBtmp_rsa_callback\fR.
215The callback is inherited by all SSL objects newly created from \fBctx\fR
216with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created SSL objects are not affected.
984263bc 217.PP
a7d27d5a
JR
218\fISSL_CTX_set_tmp_rsa()\fR sets the temporary/ephemeral RSA key to be used to be
219\fBrsa\fR. The key is inherited by all SSL objects newly created from \fBctx\fR
220with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created SSL objects are not affected.
984263bc 221.PP
a7d27d5a
JR
222\fISSL_CTX_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral RSA key is needed
223for RSA\-based strength-limited \*(L'exportable\*(R' ciphersuites because a RSA key
984263bc
MD
224with a keysize larger than 512 bits is installed.
225.PP
a7d27d5a 226\fISSL_set_tmp_rsa_callback()\fR sets the callback only for \fBssl\fR.
984263bc 227.PP
a7d27d5a 228\fISSL_set_tmp_rsa()\fR sets the key only for \fBssl\fR.
984263bc 229.PP
a7d27d5a
JR
230\fISSL_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral RSA key is needed,
231for RSA\-based strength-limited \*(L'exportable\*(R' ciphersuites because a RSA key
984263bc
MD
232with a keysize larger than 512 bits is installed.
233.PP
a7d27d5a 234These functions apply to SSL/TLS servers only.
984263bc 235.SH "NOTES"
a7d27d5a 236When using a cipher with RSA authentication, an ephemeral RSA key exchange
984263bc 237can take place. In this case the session data are negotiated using the
a7d27d5a 238ephemeral/temporary RSA key and the RSA key supplied and certified
984263bc
MD
239by the certificate chain is only used for signing.
240.PP
a7d27d5a 241Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
984263bc 242than the usual key length of 1024 bits were created. To use these ciphers
a7d27d5a 243with RSA keys of usual length, an ephemeral key exchange must be performed,
984263bc
MD
244as the normal (certified) key cannot be directly used.
245.PP
a7d27d5a
JR
246Using ephemeral RSA key exchange yields forward secrecy, as the connection
247can only be decrypted, when the RSA key is known. By generating a temporary
248RSA key inside the server application that is lost when the application
984263bc 249is left, it becomes impossible for an attacker to decrypt past sessions,
a7d27d5a
JR
250even if he gets hold of the normal (certified) RSA key, as this key was
251used for signing only. The downside is that creating a RSA key is
984263bc
MD
252computationally expensive.
253.PP
a7d27d5a
JR
254Additionally, the use of ephemeral RSA key exchange is only allowed in
255the TLS standard, when the RSA key can be used for signing only, that is
256for export ciphers. Using ephemeral RSA key exchange for other purposes
984263bc 257violates the standard and can break interoperability with clients.
a7d27d5a
JR
258It is therefore strongly recommended to not use ephemeral RSA key
259exchange and use EDH (Ephemeral Diffie-Hellman) key exchange instead
984263bc
MD
260in order to achieve forward secrecy (see
261SSL_CTX_set_tmp_dh_callback(3)).
262.PP
a7d27d5a
JR
263On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default
264and must be explicitly enabled using the SSL_OP_EPHEMERAL_RSA option of
265SSL_CTX_set_options(3), violating the TLS/SSL
266standard. When ephemeral RSA key exchange is required for export ciphers,
984263bc
MD
267it will automatically be used without this option!
268.PP
269An application may either directly specify the key or can supply the key via
270a callback function. The callback approach has the advantage, that the
271callback may generate the key only in case it is actually needed. As the
a7d27d5a 272generation of a RSA key is however costly, it will lead to a significant
984263bc 273delay in the handshake procedure. Another advantage of the callback function
a7d27d5a 274is that it can supply keys of different size (e.g. for SSL_OP_EPHEMERAL_RSA
984263bc
MD
275usage) while the explicit setting of the key is only useful for key size of
276512 bits to satisfy the export restricted ciphers and does give away key length
277if a longer key would be allowed.
278.PP
279The \fBtmp_rsa_callback\fR is called with the \fBkeylength\fR needed and
280the \fBis_export\fR information. The \fBis_export\fR flag is set, when the
a7d27d5a 281ephemeral RSA key exchange is performed with an export cipher.
984263bc 282.SH "EXAMPLES"
a7d27d5a
JR
283Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the
284generation of a RSA key costs a lot of computer time, they saved for later
984263bc
MD
285reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
286respectively are generated.
287.PP
288.Vb 4
289\& ...
290\& /* Set up ephemeral RSA stuff */
291\& RSA *rsa_512 = NULL;
292\& RSA *rsa_1024 = NULL;
293.Ve
294.Vb 3
295\& rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
296\& if (rsa_512 == NULL)
297\& evaluate_error_queue();
298.Ve
299.Vb 3
300\& rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
301\& if (rsa_1024 == NULL)
302\& evaluate_error_queue();
303.Ve
304.Vb 1
305\& ...
306.Ve
307.Vb 3
308\& RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
309\& {
310\& RSA *rsa_tmp=NULL;
311.Ve
312.Vb 24
313\& switch (keylength) {
314\& case 512:
315\& if (rsa_512)
316\& rsa_tmp = rsa_512;
317\& else { /* generate on the fly, should not happen in this example */
318\& rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
319\& rsa_512 = rsa_tmp; /* Remember for later reuse */
320\& }
321\& break;
322\& case 1024:
323\& if (rsa_1024)
324\& rsa_tmp=rsa_1024;
325\& else
326\& should_not_happen_in_this_example();
327\& break;
328\& default:
329\& /* Generating a key on the fly is very costly, so use what is there */
330\& if (rsa_1024)
331\& rsa_tmp=rsa_1024;
332\& else
333\& rsa_tmp=rsa_512; /* Use at least a shorter key */
334\& }
335\& return(rsa_tmp);
336\& }
337.Ve
338.SH "RETURN VALUES"
a7d27d5a 339\fISSL_CTX_set_tmp_rsa_callback()\fR and \fISSL_set_tmp_rsa_callback()\fR do not return
984263bc
MD
340diagnostic output.
341.PP
a7d27d5a 342\fISSL_CTX_set_tmp_rsa()\fR and \fISSL_set_tmp_rsa()\fR do return 1 on success and 0
984263bc
MD
343on failure. Check the error queue to find out the reason of failure.
344.PP
a7d27d5a
JR
345\fISSL_CTX_need_tmp_rsa()\fR and \fISSL_need_tmp_rsa()\fR return 1 if a temporary
346RSA key is needed and 0 otherwise.
984263bc 347.SH "SEE ALSO"
984263bc
MD
348ssl(3), SSL_CTX_set_cipher_list(3),
349SSL_CTX_set_options(3),
350SSL_CTX_set_tmp_dh_callback(3),
351SSL_new(3), ciphers(1)
a7d27d5a
JR
352
353.rn }` ''
354.IX Title "SSL_CTX_set_tmp_rsa_callback 3"
355.IX Name "SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange"
356
357.IX Header "NAME"
358
359.IX Header "SYNOPSIS"
360
361.IX Header "DESCRIPTION"
362
363.IX Header "NOTES"
364
365.IX Header "EXAMPLES"
366
367.IX Header "RETURN VALUES"
368
369.IX Header "SEE ALSO"
370