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