Skip to main content
Revision a520723f29aac6598ff0d69e34f5e9b88213e511 authored by Matt Caswell on 14 October 2016, 12:07:00 UTC, committed by Matt Caswell on 28 October 2016, 08:43:41 UTC
Ensure we have length checks for all extensions
The previous commit inspired a review of all the length checks for the
extension adding code. This adds more robust checks and adds checks where
some were missing previously. The real solution for this is to use WPACKET
which is currently in master - but that cannot be applied to release
branches.

Reviewed-by: Rich Salz <rsalz@openssl.org>
1 parent 83a1d4b
Raw File
DH_generate_parameters.pod
=pod

=head1 NAME


DH_generate_parameters_ex, DH_generate_parameters,
DH_check - generate and check Diffie-Hellman parameters

=head1 SYNOPSIS

 #include <openssl/dh.h>

 int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb);

 int DH_check(DH *dh, int *codes);

Deprecated:

 DH *DH_generate_parameters(int prime_len, int generator,
     void (*callback)(int, int, void *), void *cb_arg);

=head1 DESCRIPTION

DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided B<DH>
structure. The pseudo-random number generator must be
seeded prior to calling DH_generate_parameters().

B<prime_len> is the length in bits of the safe prime to be generated.
B<generator> is a small number E<gt> 1, typically 2 or 5. 

A callback function may be used to provide feedback about the progress
of the key generation. If B<cb> is not B<NULL>, it will be
called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
is called. See L<BN_generate_prime(3)|BN_generate_prime(3)> for information on
the BN_GENCB_call() function.

DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
a safe prime, and that B<g> is a suitable generator. In the case of an
error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
DH_NOT_SUITABLE_GENERATOR are set in B<*codes>.
DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
checked, i.e. it does not equal 2 or 5.

=head1 RETURN VALUES

DH_generate_parameters_ex() and DH_check() return 1 if the check could be
performed, 0 otherwise.

DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
NULL if the parameter generation fails.

The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

=head1 NOTES

DH_generate_parameters_ex() and DH_generate_parameters() may run for several
hours before finding a suitable prime.

The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
are not to be used in signature schemes.

=head1 BUGS

If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
a usable generator.

=head1 SEE ALSO

L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DH_free(3)|DH_free(3)>

=head1 HISTORY

DH_check() is available in all versions of SSLeay and OpenSSL.
The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0.

In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
instead of DH_CHECK_P_NOT_SAFE_PRIME.

=cut
back to top