doc/crypto/DH_generate_parameters.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/dh.h>
  10
  11  DH *DH_generate_parameters(int prime_len, int generator,
  12      void (*callback)(int, int, void *), void *cb_arg);
  13
  14  int DH_check(DH *dh, int *codes);
  15
  16 =head1 DESCRIPTION
  17
  18 DH_generate_parameters() generates Diffie-Hellman parameters that can
  19 be shared among a group of users, and returns them in a newly
  20 allocated B<DH> structure. The pseudo-random number generator must be
  21 seeded prior to calling DH_generate_parameters().
  22
  23 B<prime_len> is the length in bits of the safe prime to be generated.
  24 B<generator> is a small number E<gt> 1, typically 2 or 5.
  25
  26 A callback function may be used to provide feedback about the progress
  27 of the key generation. If B<callback> is not B<NULL>, it will be
  28 called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
  29 number is generated, and when a prime has been found, B<callback(3,
  30 0, cb_arg)> is called.
  31
  32 DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
  33 a safe prime, and that B<g> is a suitable generator. In the case of an
  34 error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
  35 DH_NOT_SUITABLE_GENERATOR are set in B<*codes>.
  36 DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
  37 checked, i.e. it does not equal 2 or 5.
  38
  39 =head1 RETURN VALUES
  40
  41 DH_generate_parameters() returns a pointer to the DH structure, or
  42 NULL if the parameter generation fails. The error codes can be
  43 obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
  44
  45 DH_check() returns 1 if the check could be performed, 0 otherwise.
  46
  47 =head1 NOTES
  48
  49 DH_generate_parameters() may run for several hours before finding a
  50 suitable prime.
  51
  52 The parameters generated by DH_generate_parameters() are not to be
  53 used in signature schemes.
  54
  55 =head1 BUGS
  56
  57 If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
  58 a usable generator.
  59
  60 =head1 SEE ALSO
  61
  62 L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
  63 L<DH_free(3)|DH_free(3)>
  64
  65 =head1 HISTORY
  66
  67 DH_check() is available in all versions of SSLeay and OpenSSL.
  68 The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0.
  69
  70 In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
  71 instead of DH_CHECK_P_NOT_SAFE_PRIME.
  72
  73 =cut