.Dd $Mdocdate: November 2 2016 $
.Dt DH_GENERATE_PARAMETERS 3
.Os
.Sh NAME
.Nm DH_generate_parameters_ex ,
.Nm DH_generate_parameters ,
.Nm DH_check
.Nd generate and check Diffie-Hellman parameters
.Sh SYNOPSIS
.In openssl/dh.h
.Ft int
.Fo DH_generate_parameters_ex
.Fa "DH *dh"
.Fa "int prime_len"
.Fa "int generator"
.Fa "BN_GENCB *cb"
.Fc
.Ft int
.Fo DH_check
.Fa "DH *dh"
.Fa "int *codes"
.Fc
.Pp
Deprecated:
.Pp
.Ft DH *
.Fo DH_generate_parameters
.Fa "int prime_len"
.Fa "int generator"
.Fa "void (*callback)(int"
.Fa int
.Fa "void *)"
.Fa "void *cb_arg"
.Fc
.Sh DESCRIPTION
.Fn DH_generate_parameters_ex
generates Diffie-Hellman parameters that can be shared among a group of
users, and stores them in the provided
.Vt DH
structure.
.Pp
.Fa prime_len
is the length in bits of the safe prime to be generated.
.Fa generator
is a small number > 1, typically 2 or 5.
.Pp
A callback function may be used to provide feedback about the progress
of the key generation.
If
.Fa cb
is not
.Dv NULL ,
it will be called as described in
.Xr BN_generate_prime 3
while a random prime number is generated, and when a prime has been
found,
.Fn BN_GENCB_call cb 3 0
is called; see
.Xr BN_GENCB_call 3 .
.Pp
.Fn DH_check
validates Diffie-Hellman parameters.
It checks that
.Fa dh->p
is a safe prime, and that
.Fa dh->g
is a suitable generator.
In the case of an error, the bit flags
.Dv DH_CHECK_P_NOT_SAFE_PRIME
or
.Dv DH_NOT_SUITABLE_GENERATOR
are set in
.Pf * Fa codes .
.Dv DH_UNABLE_TO_CHECK_GENERATOR
is set if the generator cannot be checked, i.e. if it does not equal 2 or 5.
.Sh RETURN VALUES
.Fn DH_generate_parameters_ex
and
.Fn DH_check
return 1 if the check could be performed, 0 otherwise.
.Pp
.Fn DH_generate_parameters
(deprecated) returns a pointer to the
.Vt DH
structure, or
.Dv NULL
if the parameter generation fails.
.Pp
The error codes can be obtained by
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr dh 3 ,
.Xr DH_free 3 ,
.Xr ERR_get_error 3 ,
.Xr rand 3
.Sh HISTORY
.Fn DH_check
is available in all versions of SSLeay and OpenSSL.
The
.Fa cb_arg
argument to
.Fn DH_generate_parameters
was added in SSLeay 0.9.0.
.Pp
In versions before OpenSSL 0.9.5,
.Dv DH_CHECK_P_NOT_STRONG_PRIME
is used instead of
.Dv DH_CHECK_P_NOT_SAFE_PRIME .
.Sh CAVEATS
.Fn DH_generate_parameters_ex
and
.Fn DH_generate_parameters
may run for several hours before finding a suitable prime.
.Pp
The parameters generated by
.Fn DH_generate_parameters_ex
and
.Fn DH_generate_parameters
are not to be used in signature schemes.
.Sh BUGS
If
.Fa generator
is not 2 or 5,
.Fa dh->g Ns = Ns Fa generator
is not a usable generator.