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