Merge from vendor branch OPENSSL:
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_tmp_rsa_callback.3
CommitLineData
d3fa4948 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
e056f0e0
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_CTX_set_tmp_rsa_callback 3"
d3fa4948 132.TH SSL_CTX_set_tmp_rsa_callback 3 "2006-11-19" "0.9.8d" "OpenSSL"
984263bc 133.SH "NAME"
a7d27d5a 134SSL_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 135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
139.Ve
e056f0e0 140.PP
984263bc
MD
141.Vb 4
142\& void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
143\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
144\& long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
145\& long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
146.Ve
e056f0e0 147.PP
984263bc
MD
148.Vb 4
149\& void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
150\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
151\& long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
152\& long SSL_need_tmp_rsa(SSL *ssl)
153.Ve
e056f0e0 154.PP
984263bc
MD
155.Vb 1
156\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
157.Ve
158.SH "DESCRIPTION"
e056f0e0
JR
159.IX Header "DESCRIPTION"
160\&\fISSL_CTX_set_tmp_rsa_callback()\fR sets the callback function for \fBctx\fR to be
161used when a temporary/ephemeral \s-1RSA\s0 key is required to \fBtmp_rsa_callback\fR.
162The callback is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR
163with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected.
984263bc 164.PP
e056f0e0
JR
165\&\fISSL_CTX_set_tmp_rsa()\fR sets the temporary/ephemeral \s-1RSA\s0 key to be used to be
166\&\fBrsa\fR. The key is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR
167with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected.
984263bc 168.PP
e056f0e0
JR
169\&\fISSL_CTX_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed
170for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key
984263bc
MD
171with a keysize larger than 512 bits is installed.
172.PP
e056f0e0 173\&\fISSL_set_tmp_rsa_callback()\fR sets the callback only for \fBssl\fR.
984263bc 174.PP
e056f0e0 175\&\fISSL_set_tmp_rsa()\fR sets the key only for \fBssl\fR.
984263bc 176.PP
e056f0e0
JR
177\&\fISSL_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed,
178for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key
984263bc
MD
179with a keysize larger than 512 bits is installed.
180.PP
e056f0e0 181These functions apply to \s-1SSL/TLS\s0 servers only.
984263bc 182.SH "NOTES"
e056f0e0
JR
183.IX Header "NOTES"
184When using a cipher with \s-1RSA\s0 authentication, an ephemeral \s-1RSA\s0 key exchange
984263bc 185can take place. In this case the session data are negotiated using the
e056f0e0 186ephemeral/temporary \s-1RSA\s0 key and the \s-1RSA\s0 key supplied and certified
984263bc
MD
187by the certificate chain is only used for signing.
188.PP
e056f0e0 189Under previous export restrictions, ciphers with \s-1RSA\s0 keys shorter (512 bits)
984263bc 190than the usual key length of 1024 bits were created. To use these ciphers
e056f0e0 191with \s-1RSA\s0 keys of usual length, an ephemeral key exchange must be performed,
984263bc
MD
192as the normal (certified) key cannot be directly used.
193.PP
e056f0e0
JR
194Using ephemeral \s-1RSA\s0 key exchange yields forward secrecy, as the connection
195can only be decrypted, when the \s-1RSA\s0 key is known. By generating a temporary
196\&\s-1RSA\s0 key inside the server application that is lost when the application
984263bc 197is left, it becomes impossible for an attacker to decrypt past sessions,
e056f0e0
JR
198even if he gets hold of the normal (certified) \s-1RSA\s0 key, as this key was
199used for signing only. The downside is that creating a \s-1RSA\s0 key is
984263bc
MD
200computationally expensive.
201.PP
e056f0e0
JR
202Additionally, the use of ephemeral \s-1RSA\s0 key exchange is only allowed in
203the \s-1TLS\s0 standard, when the \s-1RSA\s0 key can be used for signing only, that is
204for export ciphers. Using ephemeral \s-1RSA\s0 key exchange for other purposes
984263bc 205violates the standard and can break interoperability with clients.
e056f0e0
JR
206It is therefore strongly recommended to not use ephemeral \s-1RSA\s0 key
207exchange and use \s-1EDH\s0 (Ephemeral Diffie\-Hellman) key exchange instead
984263bc 208in order to achieve forward secrecy (see
e056f0e0 209\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3)).
984263bc 210.PP
e056f0e0
JR
211On OpenSSL servers ephemeral \s-1RSA\s0 key exchange is therefore disabled by default
212and must be explicitly enabled using the \s-1SSL_OP_EPHEMERAL_RSA\s0 option of
213\&\fISSL_CTX_set_options\fR\|(3), violating the \s-1TLS/SSL\s0
214standard. When ephemeral \s-1RSA\s0 key exchange is required for export ciphers,
984263bc
MD
215it will automatically be used without this option!
216.PP
217An application may either directly specify the key or can supply the key via
218a callback function. The callback approach has the advantage, that the
219callback may generate the key only in case it is actually needed. As the
e056f0e0 220generation of a \s-1RSA\s0 key is however costly, it will lead to a significant
984263bc 221delay in the handshake procedure. Another advantage of the callback function
e056f0e0 222is that it can supply keys of different size (e.g. for \s-1SSL_OP_EPHEMERAL_RSA\s0
984263bc
MD
223usage) while the explicit setting of the key is only useful for key size of
224512 bits to satisfy the export restricted ciphers and does give away key length
225if a longer key would be allowed.
226.PP
227The \fBtmp_rsa_callback\fR is called with the \fBkeylength\fR needed and
228the \fBis_export\fR information. The \fBis_export\fR flag is set, when the
e056f0e0 229ephemeral \s-1RSA\s0 key exchange is performed with an export cipher.
984263bc 230.SH "EXAMPLES"
e056f0e0
JR
231.IX Header "EXAMPLES"
232Generate temporary \s-1RSA\s0 keys to prepare ephemeral \s-1RSA\s0 key exchange. As the
233generation of a \s-1RSA\s0 key costs a lot of computer time, they saved for later
984263bc
MD
234reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
235respectively are generated.
236.PP
237.Vb 4
238\& ...
239\& /* Set up ephemeral RSA stuff */
240\& RSA *rsa_512 = NULL;
241\& RSA *rsa_1024 = NULL;
242.Ve
e056f0e0 243.PP
984263bc
MD
244.Vb 3
245\& rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
246\& if (rsa_512 == NULL)
247\& evaluate_error_queue();
248.Ve
e056f0e0 249.PP
984263bc
MD
250.Vb 3
251\& rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
252\& if (rsa_1024 == NULL)
253\& evaluate_error_queue();
254.Ve
e056f0e0 255.PP
984263bc
MD
256.Vb 1
257\& ...
258.Ve
e056f0e0 259.PP
984263bc
MD
260.Vb 3
261\& RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
262\& {
263\& RSA *rsa_tmp=NULL;
264.Ve
e056f0e0 265.PP
984263bc
MD
266.Vb 24
267\& switch (keylength) {
268\& case 512:
269\& if (rsa_512)
270\& rsa_tmp = rsa_512;
271\& else { /* generate on the fly, should not happen in this example */
272\& rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
273\& rsa_512 = rsa_tmp; /* Remember for later reuse */
274\& }
275\& break;
276\& case 1024:
277\& if (rsa_1024)
278\& rsa_tmp=rsa_1024;
279\& else
280\& should_not_happen_in_this_example();
281\& break;
282\& default:
283\& /* Generating a key on the fly is very costly, so use what is there */
284\& if (rsa_1024)
285\& rsa_tmp=rsa_1024;
286\& else
287\& rsa_tmp=rsa_512; /* Use at least a shorter key */
288\& }
289\& return(rsa_tmp);
290\& }
291.Ve
292.SH "RETURN VALUES"
e056f0e0
JR
293.IX Header "RETURN VALUES"
294\&\fISSL_CTX_set_tmp_rsa_callback()\fR and \fISSL_set_tmp_rsa_callback()\fR do not return
984263bc
MD
295diagnostic output.
296.PP
e056f0e0 297\&\fISSL_CTX_set_tmp_rsa()\fR and \fISSL_set_tmp_rsa()\fR do return 1 on success and 0
984263bc
MD
298on failure. Check the error queue to find out the reason of failure.
299.PP
e056f0e0
JR
300\&\fISSL_CTX_need_tmp_rsa()\fR and \fISSL_need_tmp_rsa()\fR return 1 if a temporary
301\&\s-1RSA\s0 key is needed and 0 otherwise.
984263bc 302.SH "SEE ALSO"
a7d27d5a 303.IX Header "SEE ALSO"
e056f0e0
JR
304\&\fIssl\fR\|(3), \fISSL_CTX_set_cipher_list\fR\|(3),
305\&\fISSL_CTX_set_options\fR\|(3),
306\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3),
307\&\fISSL_new\fR\|(3), \fIciphers\fR\|(1)