doc/apps/dhparam.pod

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