openssl: Adjust manual pages for 1.0.1m.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_tmp_rsa_callback.3
CommitLineData
5a44c043 1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
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-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
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' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
5a44c043
SW
41. ds C`
42. ds C'
984263bc 43'br\}
e056f0e0 44.\"
e257b235
PA
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
e056f0e0 49.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
5a44c043
SW
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
984263bc 56..
5a44c043
SW
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"
e257b235 63..
5a44c043
SW
64. if !\nF==2 \{
65. nr % 0
66. nr F 2
67. \}
68. \}
e257b235 69.\}
5a44c043 70.rr rF
aac4ff6f 71.\"
e056f0e0
JR
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
984263bc 75.if n \{\
e056f0e0
JR
76. ds #H 0
77. ds #V .8m
78. ds #F .3m
79. ds #[ \f1
80. ds #] \fP
984263bc
MD
81.\}
82.if t \{\
e056f0e0
JR
83. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84. ds #V .6m
85. ds #F 0
86. ds #[ \&
87. ds #] \&
984263bc 88.\}
e056f0e0 89. \" simple accents for nroff and troff
984263bc 90.if n \{\
e056f0e0
JR
91. ds ' \&
92. ds ` \&
93. ds ^ \&
94. ds , \&
95. ds ~ ~
96. ds /
984263bc
MD
97.\}
98.if t \{\
e056f0e0
JR
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'
984263bc 105.\}
e056f0e0 106. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
e056f0e0 116. \" corrections for vroff
984263bc
MD
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'
e056f0e0 119. \" for low resolution devices (crt and lpr)
984263bc
MD
120.if \n(.H>23 .if \n(.V>19 \
121\{\
e056f0e0
JR
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
984263bc
MD
131.\}
132.rm #[ #] #H #V #F C
e056f0e0
JR
133.\" ========================================================================
134.\"
135.IX Title "SSL_CTX_set_tmp_rsa_callback 3"
5a44c043 136.TH SSL_CTX_set_tmp_rsa_callback 3 "2015-03-19" "1.0.1m" "OpenSSL"
e257b235
PA
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
984263bc 141.SH "NAME"
a7d27d5a 142SSL_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 143.SH "SYNOPSIS"
e056f0e0 144.IX Header "SYNOPSIS"
984263bc
MD
145.Vb 1
146\& #include <openssl/ssl.h>
e257b235 147\&
984263bc
MD
148\& void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
149\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
150\& long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
151\& long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
e257b235 152\&
984263bc
MD
153\& void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
154\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
155\& long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
156\& long SSL_need_tmp_rsa(SSL *ssl)
e257b235 157\&
edae4a78 158\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength);
984263bc
MD
159.Ve
160.SH "DESCRIPTION"
e056f0e0
JR
161.IX Header "DESCRIPTION"
162\&\fISSL_CTX_set_tmp_rsa_callback()\fR sets the callback function for \fBctx\fR to be
163used when a temporary/ephemeral \s-1RSA\s0 key is required to \fBtmp_rsa_callback\fR.
164The callback is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR
165with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected.
984263bc 166.PP
e056f0e0
JR
167\&\fISSL_CTX_set_tmp_rsa()\fR sets the temporary/ephemeral \s-1RSA\s0 key to be used to be
168\&\fBrsa\fR. The key is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR
169with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected.
984263bc 170.PP
e056f0e0
JR
171\&\fISSL_CTX_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed
172for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key
984263bc
MD
173with a keysize larger than 512 bits is installed.
174.PP
e056f0e0 175\&\fISSL_set_tmp_rsa_callback()\fR sets the callback only for \fBssl\fR.
984263bc 176.PP
e056f0e0 177\&\fISSL_set_tmp_rsa()\fR sets the key only for \fBssl\fR.
984263bc 178.PP
e056f0e0
JR
179\&\fISSL_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed,
180for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key
984263bc
MD
181with a keysize larger than 512 bits is installed.
182.PP
e056f0e0 183These functions apply to \s-1SSL/TLS\s0 servers only.
984263bc 184.SH "NOTES"
e056f0e0
JR
185.IX Header "NOTES"
186When using a cipher with \s-1RSA\s0 authentication, an ephemeral \s-1RSA\s0 key exchange
984263bc 187can take place. In this case the session data are negotiated using the
e056f0e0 188ephemeral/temporary \s-1RSA\s0 key and the \s-1RSA\s0 key supplied and certified
984263bc
MD
189by the certificate chain is only used for signing.
190.PP
e056f0e0 191Under previous export restrictions, ciphers with \s-1RSA\s0 keys shorter (512 bits)
984263bc 192than the usual key length of 1024 bits were created. To use these ciphers
e056f0e0 193with \s-1RSA\s0 keys of usual length, an ephemeral key exchange must be performed,
984263bc
MD
194as the normal (certified) key cannot be directly used.
195.PP
e056f0e0
JR
196Using ephemeral \s-1RSA\s0 key exchange yields forward secrecy, as the connection
197can only be decrypted, when the \s-1RSA\s0 key is known. By generating a temporary
198\&\s-1RSA\s0 key inside the server application that is lost when the application
984263bc 199is left, it becomes impossible for an attacker to decrypt past sessions,
e056f0e0
JR
200even if he gets hold of the normal (certified) \s-1RSA\s0 key, as this key was
201used for signing only. The downside is that creating a \s-1RSA\s0 key is
984263bc
MD
202computationally expensive.
203.PP
e056f0e0
JR
204Additionally, the use of ephemeral \s-1RSA\s0 key exchange is only allowed in
205the \s-1TLS\s0 standard, when the \s-1RSA\s0 key can be used for signing only, that is
206for export ciphers. Using ephemeral \s-1RSA\s0 key exchange for other purposes
984263bc 207violates the standard and can break interoperability with clients.
e056f0e0 208It is therefore strongly recommended to not use ephemeral \s-1RSA\s0 key
5a44c043 209exchange and use \s-1EDH \s0(Ephemeral Diffie-Hellman) key exchange instead
984263bc 210in order to achieve forward secrecy (see
e056f0e0 211\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3)).
984263bc 212.PP
ca2244c8
SW
213An application may either directly specify the key or can supply the key via a
214callback function. The callback approach has the advantage, that the callback
215may generate the key only in case it is actually needed. As the generation of a
216\&\s-1RSA\s0 key is however costly, it will lead to a significant delay in the handshake
217procedure. Another advantage of the callback function is that it can supply
218keys of different size while the explicit setting of the key is only useful for
219key size of 512 bits to satisfy the export restricted ciphers and does give
220away key length if a longer key would be allowed.
984263bc
MD
221.PP
222The \fBtmp_rsa_callback\fR is called with the \fBkeylength\fR needed and
223the \fBis_export\fR information. The \fBis_export\fR flag is set, when the
e056f0e0 224ephemeral \s-1RSA\s0 key exchange is performed with an export cipher.
984263bc 225.SH "EXAMPLES"
e056f0e0
JR
226.IX Header "EXAMPLES"
227Generate temporary \s-1RSA\s0 keys to prepare ephemeral \s-1RSA\s0 key exchange. As the
228generation of a \s-1RSA\s0 key costs a lot of computer time, they saved for later
984263bc
MD
229reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
230respectively are generated.
231.PP
232.Vb 4
233\& ...
234\& /* Set up ephemeral RSA stuff */
235\& RSA *rsa_512 = NULL;
236\& RSA *rsa_1024 = NULL;
e257b235 237\&
984263bc
MD
238\& rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
239\& if (rsa_512 == NULL)
240\& evaluate_error_queue();
e257b235 241\&
984263bc
MD
242\& rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
243\& if (rsa_1024 == NULL)
244\& evaluate_error_queue();
e257b235 245\&
984263bc 246\& ...
e257b235 247\&
984263bc
MD
248\& RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
249\& {
250\& RSA *rsa_tmp=NULL;
e257b235 251\&
984263bc
MD
252\& switch (keylength) {
253\& case 512:
254\& if (rsa_512)
255\& rsa_tmp = rsa_512;
256\& else { /* generate on the fly, should not happen in this example */
257\& rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
258\& rsa_512 = rsa_tmp; /* Remember for later reuse */
259\& }
260\& break;
261\& case 1024:
262\& if (rsa_1024)
263\& rsa_tmp=rsa_1024;
264\& else
265\& should_not_happen_in_this_example();
266\& break;
267\& default:
268\& /* Generating a key on the fly is very costly, so use what is there */
269\& if (rsa_1024)
270\& rsa_tmp=rsa_1024;
271\& else
272\& rsa_tmp=rsa_512; /* Use at least a shorter key */
273\& }
274\& return(rsa_tmp);
275\& }
276.Ve
277.SH "RETURN VALUES"
e056f0e0
JR
278.IX Header "RETURN VALUES"
279\&\fISSL_CTX_set_tmp_rsa_callback()\fR and \fISSL_set_tmp_rsa_callback()\fR do not return
984263bc
MD
280diagnostic output.
281.PP
e056f0e0 282\&\fISSL_CTX_set_tmp_rsa()\fR and \fISSL_set_tmp_rsa()\fR do return 1 on success and 0
984263bc
MD
283on failure. Check the error queue to find out the reason of failure.
284.PP
e056f0e0
JR
285\&\fISSL_CTX_need_tmp_rsa()\fR and \fISSL_need_tmp_rsa()\fR return 1 if a temporary
286\&\s-1RSA\s0 key is needed and 0 otherwise.
984263bc 287.SH "SEE ALSO"
a7d27d5a 288.IX Header "SEE ALSO"
e056f0e0
JR
289\&\fIssl\fR\|(3), \fISSL_CTX_set_cipher_list\fR\|(3),
290\&\fISSL_CTX_set_options\fR\|(3),
291\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3),
292\&\fISSL_new\fR\|(3), \fIciphers\fR\|(1)