Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_tmp_dh_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_dh_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_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh \- handle DH 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 3
198\& void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
199\& DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
200\& long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
201.Ve
202.Vb 3
203\& void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
204\& DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
205\& long SSL_set_tmp_dh(SSL *ssl, DH *dh)
206.Ve
207.Vb 1
208\& DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
209.Ve
210.SH "DESCRIPTION"
a7d27d5a
JR
211\fISSL_CTX_set_tmp_dh_callback()\fR sets the callback function for \fBctx\fR to be
212used when a DH parameters are required to \fBtmp_dh_callback\fR.
984263bc
MD
213The callback is inherited by all \fBssl\fR objects created from \fBctx\fR.
214.PP
a7d27d5a 215\fISSL_CTX_set_tmp_dh()\fR sets DH parameters to be used to be \fBdh\fR.
984263bc
MD
216The key is inherited by all \fBssl\fR objects created from \fBctx\fR.
217.PP
a7d27d5a 218\fISSL_set_tmp_dh_callback()\fR sets the callback only for \fBssl\fR.
984263bc 219.PP
a7d27d5a 220\fISSL_set_tmp_dh()\fR sets the parameters only for \fBssl\fR.
984263bc 221.PP
a7d27d5a 222These functions apply to SSL/TLS servers only.
984263bc 223.SH "NOTES"
a7d27d5a
JR
224When using a cipher with RSA authentication, an ephemeral DH key exchange
225can take place. Ciphers with DSA keys always use ephemeral DH keys as well.
984263bc 226In these cases, the session data are negotiated using the
a7d27d5a 227ephemeral/temporary DH key and the key supplied and certified
984263bc 228by the certificate chain is only used for signing.
a7d27d5a 229Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
984263bc 230.PP
a7d27d5a
JR
231Using ephemeral DH key exchange yields forward secrecy, as the connection
232can only be decrypted, when the DH key is known. By generating a temporary
233DH key inside the server application that is lost when the application
984263bc
MD
234is left, it becomes impossible for an attacker to decrypt past sessions,
235even if he gets hold of the normal (certified) key, as this key was
236only used for signing.
237.PP
a7d27d5a
JR
238In order to perform a DH key exchange the server must use a DH group
239(DH parameters) and generate a DH key. The server will always generate a new
240DH key during the negotiation, when the DH parameters are supplied via
241callback and/or when the SSL_OP_SINGLE_DH_USE option of
984263bc 242SSL_CTX_set_options(3) is set. It will
a7d27d5a
JR
243immediately create a DH key, when DH parameters are supplied via
244\fISSL_CTX_set_tmp_dh()\fR and SSL_OP_SINGLE_DH_USE is not set. In this case,
984263bc
MD
245it may happen that a key is generated on initialization without later
246being needed, while on the other hand the computer time during the
247negotiation is being saved.
248.PP
a7d27d5a 249If \*(L"strong\*(R" primes were used to generate the DH parameters, it is not strictly
984263bc
MD
250necessary to generate a new key for each handshake but it does improve forward
251secrecy. If it is not assured, that \*(L"strong\*(R" primes were used (see especially
a7d27d5a
JR
252the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used
253in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE
984263bc
MD
254has an impact on the computer time needed during negotiation, but it is not
255very large, so application authors/users should consider to always enable
256this option.
257.PP
a7d27d5a 258As generating DH parameters is extremely time consuming, an application
984263bc 259should not generate the parameters on the fly but supply the parameters.
a7d27d5a
JR
260DH parameters can be reused, as the actual key is newly generated during
261the negotiation. The risk in reusing DH parameters is that an attacker
262may specialize on a very often used DH group. Applications should therefore
263generate their own DH parameters during the installation process using the
984263bc 264openssl dhparam(1) application. In order to reduce the computer
a7d27d5a
JR
265time needed for this generation, it is possible to use DSA parameters
266instead (see dhparam(1)), but in this case SSL_OP_SINGLE_DH_USE
984263bc
MD
267is mandatory.
268.PP
a7d27d5a
JR
269Application authors may compile in DH parameters. Files dh512.pem,
270dh1024.pem, dh2048.pem, and dh4096 in the \*(L'apps\*(R' directory of current
271version of the OpenSSL distribution contain the \*(L'SKIP\*(R' DH parameters,
984263bc
MD
272which use safe primes and were generated verifiably pseudo-randomly.
273These files can be converted into C code using the \fB\-C\fR option of the
274dhparam(1) application.
275Authors may also generate their own set of parameters using
276dhparam(1), but a user may not be sure how the parameters were
a7d27d5a 277generated. The generation of DH parameters during installation is therefore
984263bc
MD
278recommended.
279.PP
a7d27d5a
JR
280An application may either directly specify the DH parameters or
281can supply the DH parameters via a callback function. The callback approach
282has the advantage, that the callback may supply DH parameters for different
984263bc
MD
283key lengths.
284.PP
285The \fBtmp_dh_callback\fR is called with the \fBkeylength\fR needed and
286the \fBis_export\fR information. The \fBis_export\fR flag is set, when the
a7d27d5a 287ephemeral DH key exchange is performed with an export cipher.
984263bc 288.SH "EXAMPLES"
a7d27d5a 289Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
984263bc
MD
290partly left out.)
291.PP
292.Vb 5
293\& ...
294\& /* Set up ephemeral DH stuff */
295\& DH *dh_512 = NULL;
296\& DH *dh_1024 = NULL;
297\& FILE *paramfile;
298.Ve
299.Vb 14
300\& ...
301\& /* "openssl dhparam -out dh_param_512.pem -2 512" */
302\& paramfile = fopen("dh_param_512.pem", "r");
303\& if (paramfile) {
304\& dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
305\& fclose(paramfile);
306\& }
307\& /* "openssl dhparam -out dh_param_1024.pem -2 1024" */
308\& paramfile = fopen("dh_param_1024.pem", "r");
309\& if (paramfile) {
310\& dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
311\& fclose(paramfile);
312\& }
313\& ...
314.Ve
315.Vb 3
316\& /* "openssl dhparam -C -2 512" etc... */
317\& DH *get_dh512() { ... }
318\& DH *get_dh1024() { ... }
319.Ve
320.Vb 3
321\& DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
322\& {
323\& DH *dh_tmp=NULL;
324.Ve
325.Vb 17
326\& switch (keylength) {
327\& case 512:
328\& if (!dh_512)
329\& dh_512 = get_dh512();
330\& dh_tmp = dh_512;
331\& break;
332\& case 1024:
333\& if (!dh_1024)
334\& dh_1024 = get_dh1024();
335\& dh_tmp = dh_1024;
336\& break;
337\& default:
338\& /* Generating a key on the fly is very costly, so use what is there */
339\& setup_dh_parameters_like_above();
340\& }
341\& return(dh_tmp);
342\& }
343.Ve
344.SH "RETURN VALUES"
a7d27d5a 345\fISSL_CTX_set_tmp_dh_callback()\fR and \fISSL_set_tmp_dh_callback()\fR do not return
984263bc
MD
346diagnostic output.
347.PP
a7d27d5a 348\fISSL_CTX_set_tmp_dh()\fR and \fISSL_set_tmp_dh()\fR do return 1 on success and 0
984263bc
MD
349on failure. Check the error queue to find out the reason of failure.
350.SH "SEE ALSO"
984263bc
MD
351ssl(3), SSL_CTX_set_cipher_list(3),
352SSL_CTX_set_tmp_rsa_callback(3),
353SSL_CTX_set_options(3),
354ciphers(1), dhparam(1)
a7d27d5a
JR
355
356.rn }` ''
357.IX Title "SSL_CTX_set_tmp_dh_callback 3"
358.IX Name "SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange"
359
360.IX Header "NAME"
361
362.IX Header "SYNOPSIS"
363
364.IX Header "DESCRIPTION"
365
366.IX Header "NOTES"
367
368.IX Header "EXAMPLES"
369
370.IX Header "RETURN VALUES"
371
372.IX Header "SEE ALSO"
373