5cf4d4f73f2c56d1a82af1d6f61f11ca7f20f591
[openssl.git] / doc / apps / dhparam.pod
1 =pod
2
3 =head1 NAME
4
5 dhparam - DH parameter manipulation and generation
6
7 =head1 SYNOPSIS
8
9 B<openssl dhparam>
10 [B<-help>]
11 [B<-inform DER|PEM>]
12 [B<-outform DER|PEM>]
13 [B<-in> I<filename>]
14 [B<-out> I<filename>]
15 [B<-dsaparam>]
16 [B<-check>]
17 [B<-noout>]
18 [B<-text>]
19 [B<-C>]
20 [B<-2>]
21 [B<-5>]
22 [B<-rand> I<file(s)>]
23 [B<-engine id>]
24 [I<numbits>]
25
26 =head1 DESCRIPTION
27
28 This command is used to manipulate DH parameter files.
29
30 =head1 OPTIONS
31
32 =over 4
33
34 =item B<-help>
35
36 Print out a usage message.
37
38 =item B<-inform DER|PEM>
39
40 This specifies the input format. The B<DER> option uses an ASN1 DER encoded
41 form compatible with the PKCS#3 DHparameter structure. The PEM form is the
42 default format: it consists of the B<DER> format base64 encoded with
43 additional header and footer lines.
44
45 =item B<-outform DER|PEM>
46
47 This specifies the output format, the options have the same meaning as the 
48 B<-inform> option.
49
50 =item B<-in> I<filename>
51
52 This specifies the input filename to read parameters from or standard input if
53 this option is not specified.
54
55 =item B<-out> I<filename>
56
57 This specifies the output filename parameters to. Standard output is used
58 if this option is not present. The output filename should B<not> be the same
59 as the input filename.
60
61 =item B<-dsaparam>
62
63 If this option is used, DSA rather than DH parameters are read or created;
64 they are converted to DH format.  Otherwise, "strong" primes (such
65 that (p-1)/2 is also prime) will be used for DH parameter generation.
66
67 DH parameter generation with the B<-dsaparam> option is much faster,
68 and the recommended exponent length is shorter, which makes DH key
69 exchange more efficient.  Beware that with such DSA-style DH
70 parameters, a fresh DH key should be created for each use to
71 avoid small-subgroup attacks that may be possible otherwise.
72
73 =item B<-check>
74
75 check if the parameters are valid primes and generator.
76
77 =item B<-2>, B<-5>
78
79 The generator to use, either 2 or 5. If present then the
80 input file is ignored and parameters are generated instead. If not
81 present but B<numbits> is present, parameters are generated with the
82 default generator 2.
83
84 =item B<-rand> I<file(s)>
85
86 a file or files containing random data used to seed the random number
87 generator, or an EGD socket (see L<RAND_egd(3)>).
88 Multiple files can be specified separated by a OS-dependent character.
89 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
90 all others.
91
92 =item I<numbits>
93
94 this option specifies that a parameter set should be generated of size
95 I<numbits>. It must be the last option. If this option is present then
96 the input file is ignored and parameters are generated instead. If
97 this option is not present but a generator (B<-2> or B<-5>) is
98 present, parameters are generated with a default length of 2048 bits.
99
100 =item B<-noout>
101
102 this option inhibits the output of the encoded version of the parameters.
103
104 =item B<-text>
105
106 this option prints out the DH parameters in human readable form.
107
108 =item B<-C>
109
110 this option converts the parameters into C code. The parameters can then
111 be loaded by calling the get_dhNNNN() function.
112
113 =item B<-engine id>
114
115 specifying an engine (by its unique B<id> string) will cause B<dhparam>
116 to attempt to obtain a functional reference to the specified engine,
117 thus initialising it if needed. The engine will then be set as the default
118 for all available algorithms.
119
120 =back
121
122 =head1 WARNINGS
123
124 The program B<dhparam> combines the functionality of the programs B<dh> and
125 B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
126 programs are retained for now but may have different purposes in future 
127 versions of OpenSSL.
128
129 =head1 NOTES
130
131 PEM format DH parameters use the header and footer lines:
132
133  -----BEGIN DH PARAMETERS-----
134  -----END DH PARAMETERS-----
135
136 OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
137 DH.
138
139 This program manipulates DH parameters not keys.
140
141 =head1 BUGS
142
143 There should be a way to generate and manipulate DH keys.
144
145 =head1 SEE ALSO
146
147 L<dsaparam(1)>
148
149 =cut