Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / DH_generate_parameters.3
CommitLineData
74dab6c2
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..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
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 \{\
74dab6c2
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\{\
74dab6c2
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\}
74dab6c2
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..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH DH_generate_parameters 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
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
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
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 \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
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 \{\
74dab6c2
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.\}
74dab6c2 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'
74dab6c2
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
74dab6c2
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'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
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
MD
190.SH "NAME"
191DH_generate_parameters, DH_check \- generate and check Diffie-Hellman parameters
192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/dh.h>
196.Ve
197.Vb 2
198\& DH *DH_generate_parameters(int prime_len, int generator,
199\& void (*callback)(int, int, void *), void *cb_arg);
200.Ve
201.Vb 1
202\& int DH_check(DH *dh, int *codes);
203.Ve
204.SH "DESCRIPTION"
74dab6c2 205\fIDH_generate_parameters()\fR generates Diffie-Hellman parameters that can
984263bc 206be shared among a group of users, and returns them in a newly
74dab6c2 207allocated \fBDH\fR structure. The pseudo-random number generator must be
984263bc
MD
208seeded prior to calling \fIDH_generate_parameters()\fR.
209.PP
74dab6c2
JR
210\fBprime_len\fR is the length in bits of the safe prime to be generated.
211\fBgenerator\fR is a small number > 1, typically 2 or 5.
984263bc
MD
212.PP
213A callback function may be used to provide feedback about the progress
74dab6c2 214of the key generation. If \fBcallback\fR is not \fBNULL\fR, it will be
984263bc
MD
215called as described in BN_generate_prime(3) while a random prime
216number is generated, and when a prime has been found, \fBcallback(3,
2170, cb_arg)\fR is called.
218.PP
74dab6c2 219\fIDH_check()\fR validates Diffie-Hellman parameters. It checks that \fBp\fR is
984263bc 220a safe prime, and that \fBg\fR is a suitable generator. In the case of an
74dab6c2
JR
221error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
222DH_NOT_SUITABLE_GENERATOR are set in \fB*codes\fR.
223DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
984263bc
MD
224checked, i.e. it does not equal 2 or 5.
225.SH "RETURN VALUES"
74dab6c2
JR
226\fIDH_generate_parameters()\fR returns a pointer to the DH structure, or
227NULL if the parameter generation fails. The error codes can be
984263bc
MD
228obtained by ERR_get_error(3).
229.PP
74dab6c2 230\fIDH_check()\fR returns 1 if the check could be performed, 0 otherwise.
984263bc 231.SH "NOTES"
74dab6c2 232\fIDH_generate_parameters()\fR may run for several hours before finding a
984263bc
MD
233suitable prime.
234.PP
235The parameters generated by \fIDH_generate_parameters()\fR are not to be
236used in signature schemes.
237.SH "BUGS"
984263bc
MD
238If \fBgenerator\fR is not 2 or 5, \fBdh->g\fR=\fBgenerator\fR is not
239a usable generator.
240.SH "SEE ALSO"
984263bc
MD
241dh(3), ERR_get_error(3), rand(3),
242DH_free(3)
243.SH "HISTORY"
74dab6c2 244\fIDH_check()\fR is available in all versions of SSLeay and OpenSSL.
984263bc
MD
245The \fBcb_arg\fR argument to \fIDH_generate_parameters()\fR was added in SSLeay 0.9.0.
246.PP
74dab6c2
JR
247In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
248instead of DH_CHECK_P_NOT_SAFE_PRIME.
249
250.rn }` ''
251.IX Title "DH_generate_parameters 3"
252.IX Name "DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters"
253
254.IX Header "NAME"
255
256.IX Header "SYNOPSIS"
257
258.IX Header "DESCRIPTION"
259
260.IX Header "RETURN VALUES"
261
262.IX Header "NOTES"
263
264.IX Header "BUGS"
265
266.IX Header "SEE ALSO"
267
268.IX Header "HISTORY"
269