1=pod 2 3=head1 NAME 4 5DH_generate_parameters_ex, DH_generate_parameters, 6DH_check, DH_check_params, 7DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex 8- generate and check Diffie-Hellman 9parameters 10 11=head1 SYNOPSIS 12 13 #include <openssl/dh.h> 14 15 int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb); 16 17 int DH_check(DH *dh, int *codes); 18 int DH_check_params(DH *dh, int *codes); 19 20 int DH_check_ex(const DH *dh); 21 int DH_check_params_ex(const DH *dh); 22 int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key); 23 24Deprecated: 25 26 #if OPENSSL_API_COMPAT < 0x00908000L 27 DH *DH_generate_parameters(int prime_len, int generator, 28 void (*callback)(int, int, void *), void *cb_arg); 29 #endif 30 31=head1 DESCRIPTION 32 33DH_generate_parameters_ex() generates Diffie-Hellman parameters that can 34be shared among a group of users, and stores them in the provided B<DH> 35structure. The pseudo-random number generator must be 36seeded before calling it. 37The parameters generated by DH_generate_parameters_ex() should not be used in 38signature schemes. 39 40B<prime_len> is the length in bits of the safe prime to be generated. 41B<generator> is a small number E<gt> 1, typically 2 or 5. 42 43A callback function may be used to provide feedback about the progress 44of the key generation. If B<cb> is not B<NULL>, it will be 45called as described in L<BN_generate_prime(3)> while a random prime 46number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)> 47is called. See L<BN_generate_prime_ex(3)> for information on 48the BN_GENCB_call() function. 49 50DH_generate_parameters() is similar to DH_generate_prime_ex() but 51expects an old-style callback function; see 52L<BN_generate_prime(3)> for information on the old-style callback. 53 54DH_check_params() confirms that the B<p> and B<g> are likely enough to 55be valid. 56This is a lightweight check, if a more thorough check is needed, use 57DH_check(). 58The value of B<*codes> is updated with any problems found. 59If B<*codes> is zero then no problems were found, otherwise the 60following bits may be set: 61 62=over 4 63 64=item DH_CHECK_P_NOT_PRIME 65 66The parameter B<p> has been determined to not being an odd prime. 67Note that the lack of this bit doesn't guarantee that B<p> is a 68prime. 69 70=item DH_NOT_SUITABLE_GENERATOR 71 72The generator B<g> is not suitable. 73Note that the lack of this bit doesn't guarantee that B<g> is 74suitable, unless B<p> is known to be a strong prime. 75 76=back 77 78DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The 79value of B<*codes> is updated with any problems found. If B<*codes> is zero then 80no problems were found, otherwise the following bits may be set: 81 82=over 4 83 84=item DH_CHECK_P_NOT_PRIME 85 86The parameter B<p> is not prime. 87 88=item DH_CHECK_P_NOT_SAFE_PRIME 89 90The parameter B<p> is not a safe prime and no B<q> value is present. 91 92=item DH_UNABLE_TO_CHECK_GENERATOR 93 94The generator B<g> cannot be checked for suitability. 95 96=item DH_NOT_SUITABLE_GENERATOR 97 98The generator B<g> is not suitable. 99 100=item DH_CHECK_Q_NOT_PRIME 101 102The parameter B<q> is not prime. 103 104=item DH_CHECK_INVALID_Q_VALUE 105 106The parameter B<q> is invalid. 107 108=item DH_CHECK_INVALID_J_VALUE 109 110The parameter B<j> is invalid. 111 112=back 113 114DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similar to 115DH_check() and DH_check_params() respectively, but the error reasons are added 116to the thread's error queue instead of provided as return values from the 117function. 118 119=head1 RETURN VALUES 120 121DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 122if the check could be performed, 0 otherwise. 123 124DH_generate_parameters() returns a pointer to the DH structure or NULL if 125the parameter generation fails. 126 127DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() return 1 if the 128check is successful, 0 for failed. 129 130The error codes can be obtained by L<ERR_get_error(3)>. 131 132=head1 SEE ALSO 133 134L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, 135L<DH_free(3)> 136 137=head1 HISTORY 138 139DH_generate_parameters() was deprecated in OpenSSL 0.9.8; use 140DH_generate_parameters_ex() instead. 141 142=head1 COPYRIGHT 143 144Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 145 146Licensed under the OpenSSL license (the "License"). You may not use 147this file except in compliance with the License. You can obtain a copy 148in the file LICENSE in the source distribution or at 149L<https://www.openssl.org/source/license.html>. 150 151=cut 152