diff options
author | Jung-uk Kim <jkim@FreeBSD.org> | 2018-09-13 23:14:57 +0000 |
---|---|---|
committer | Jung-uk Kim <jkim@FreeBSD.org> | 2018-09-13 23:14:57 +0000 |
commit | 54967a4e950cb7b16a26428f9e3872aa8fe83d16 (patch) | |
tree | 8ebcd0ceb80e3719deabb8cbd455ab2685cf0c96 /secure/lib/libcrypto/man/DH_generate_parameters.3 | |
parent | 9b21da0ecb8941dc7c6bd721ccfe05cecd7d6432 (diff) | |
download | src-54967a4e950cb7b16a26428f9e3872aa8fe83d16.tar.gz src-54967a4e950cb7b16a26428f9e3872aa8fe83d16.zip |
Regen manual pages.
Note the manual pages are not automatically generated for now.
Notes
Notes:
svn path=/projects/openssl111/; revision=338671
Diffstat (limited to 'secure/lib/libcrypto/man/DH_generate_parameters.3')
-rw-r--r-- | secure/lib/libcrypto/man/DH_generate_parameters.3 | 120 |
1 files changed, 85 insertions, 35 deletions
diff --git a/secure/lib/libcrypto/man/DH_generate_parameters.3 b/secure/lib/libcrypto/man/DH_generate_parameters.3 index f8d2fc499e1f..e260c1915754 100644 --- a/secure/lib/libcrypto/man/DH_generate_parameters.3 +++ b/secure/lib/libcrypto/man/DH_generate_parameters.3 @@ -128,37 +128,45 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "DH_generate_parameters 3" -.TH DH_generate_parameters 3 "2018-08-14" "1.0.2p" "OpenSSL" +.IX Title "DH_GENERATE_PARAMETERS 3" +.TH DH_GENERATE_PARAMETERS 3 "2018-09-11" "1.1.1" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -DH_generate_parameters_ex, DH_generate_parameters, -DH_check \- generate and check Diffie\-Hellman parameters +DH_generate_parameters_ex, DH_generate_parameters, DH_check, DH_check_params, DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex \&\- generate and check Diffie\-Hellman parameters .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/dh.h> \& -\& int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb); +\& int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb); \& \& int DH_check(DH *dh, int *codes); +\& int DH_check_params(DH *dh, int *codes); +\& +\& int DH_check_ex(const DH *dh); +\& int DH_check_params_ex(const DH *dh); +\& int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key); .Ve .PP Deprecated: .PP -.Vb 2 +.Vb 4 +\& #if OPENSSL_API_COMPAT < 0x00908000L \& DH *DH_generate_parameters(int prime_len, int generator, -\& void (*callback)(int, int, void *), void *cb_arg); +\& void (*callback)(int, int, void *), void *cb_arg); +\& #endif .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIDH_generate_parameters_ex()\fR generates Diffie-Hellman parameters that can be shared among a group of users, and stores them in the provided \fB\s-1DH\s0\fR structure. The pseudo-random number generator must be -seeded prior to calling \fIDH_generate_parameters()\fR. +seeded before calling it. +The parameters generated by \fIDH_generate_parameters_ex()\fR should not be used in +signature schemes. .PP \&\fBprime_len\fR is the length in bits of the safe prime to be generated. \&\fBgenerator\fR is a small number > 1, typically 2 or 5. @@ -167,43 +175,85 @@ A callback function may be used to provide feedback about the progress of the key generation. If \fBcb\fR is not \fB\s-1NULL\s0\fR, it will be called as described in \fIBN_generate_prime\fR\|(3) while a random prime number is generated, and when a prime has been found, \fBBN_GENCB_call(cb, 3, 0)\fR -is called. See \fIBN_generate_prime\fR\|(3) for information on +is called. See \fIBN_generate_prime_ex\fR\|(3) for information on the \fIBN_GENCB_call()\fR function. .PP -\&\fIDH_check()\fR validates Diffie-Hellman parameters. It checks that \fBp\fR is -a safe prime, and that \fBg\fR is a suitable generator. In the case of an -error, the bit flags \s-1DH_CHECK_P_NOT_SAFE_PRIME\s0 or -\&\s-1DH_NOT_SUITABLE_GENERATOR\s0 are set in \fB*codes\fR. -\&\s-1DH_UNABLE_TO_CHECK_GENERATOR\s0 is set if the generator cannot be -checked, i.e. it does not equal 2 or 5. +\&\fIDH_generate_parameters()\fR is similar to \fIDH_generate_prime_ex()\fR but +expects an old-style callback function; see +\&\fIBN_generate_prime\fR\|(3) for information on the old-style callback. +.PP +\&\fIDH_check_params()\fR confirms that the \fBp\fR and \fBg\fR are likely enough to +be valid. +This is a lightweight check, if a more thorough check is needed, use +\&\fIDH_check()\fR. +The value of \fB*codes\fR is updated with any problems found. +If \fB*codes\fR is zero then no problems were found, otherwise the +following bits may be set: +.IP "\s-1DH_CHECK_P_NOT_PRIME\s0" 4 +.IX Item "DH_CHECK_P_NOT_PRIME" +The parameter \fBp\fR has been determined to not being an odd prime. +Note that the lack of this bit doesn't guarantee that \fBp\fR is a +prime. +.IP "\s-1DH_NOT_SUITABLE_GENERATOR\s0" 4 +.IX Item "DH_NOT_SUITABLE_GENERATOR" +The generator \fBg\fR is not suitable. +Note that the lack of this bit doesn't guarantee that \fBg\fR is +suitable, unless \fBp\fR is known to be a strong prime. +.PP +\&\fIDH_check()\fR confirms that the Diffie-Hellman parameters \fBdh\fR are valid. The +value of \fB*codes\fR is updated with any problems found. If \fB*codes\fR is zero then +no problems were found, otherwise the following bits may be set: +.IP "\s-1DH_CHECK_P_NOT_PRIME\s0" 4 +.IX Item "DH_CHECK_P_NOT_PRIME" +The parameter \fBp\fR is not prime. +.IP "\s-1DH_CHECK_P_NOT_SAFE_PRIME\s0" 4 +.IX Item "DH_CHECK_P_NOT_SAFE_PRIME" +The parameter \fBp\fR is not a safe prime and no \fBq\fR value is present. +.IP "\s-1DH_UNABLE_TO_CHECK_GENERATOR\s0" 4 +.IX Item "DH_UNABLE_TO_CHECK_GENERATOR" +The generator \fBg\fR cannot be checked for suitability. +.IP "\s-1DH_NOT_SUITABLE_GENERATOR\s0" 4 +.IX Item "DH_NOT_SUITABLE_GENERATOR" +The generator \fBg\fR is not suitable. +.IP "\s-1DH_CHECK_Q_NOT_PRIME\s0" 4 +.IX Item "DH_CHECK_Q_NOT_PRIME" +The parameter \fBq\fR is not prime. +.IP "\s-1DH_CHECK_INVALID_Q_VALUE\s0" 4 +.IX Item "DH_CHECK_INVALID_Q_VALUE" +The parameter \fBq\fR is invalid. +.IP "\s-1DH_CHECK_INVALID_J_VALUE\s0" 4 +.IX Item "DH_CHECK_INVALID_J_VALUE" +The parameter \fBj\fR is invalid. +.PP +\&\fIDH_check_ex()\fR, \fIDH_check_params()\fR and \fIDH_check_pub_key_ex()\fR are similar to +\&\fIDH_check()\fR and \fIDH_check_params()\fR respectively, but the error reasons are added +to the thread's error queue instead of provided as return values from the +function. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fIDH_generate_parameters_ex()\fR and \fIDH_check()\fR return 1 if the check could be -performed, 0 otherwise. +\&\fIDH_generate_parameters_ex()\fR, \fIDH_check()\fR and \fIDH_check_params()\fR return 1 +if the check could be performed, 0 otherwise. .PP -\&\fIDH_generate_parameters()\fR (deprecated) returns a pointer to the \s-1DH\s0 structure, or -\&\s-1NULL\s0 if the parameter generation fails. +\&\fIDH_generate_parameters()\fR returns a pointer to the \s-1DH\s0 structure or \s-1NULL\s0 if +the parameter generation fails. .PP -The error codes can be obtained by \fIERR_get_error\fR\|(3). -.SH "NOTES" -.IX Header "NOTES" -\&\fIDH_generate_parameters_ex()\fR and \fIDH_generate_parameters()\fR may run for several -hours before finding a suitable prime. +\&\fIDH_check_ex()\fR, \fIDH_check_params()\fR and \fIDH_check_pub_key_ex()\fR return 1 if the +check is successful, 0 for failed. .PP -The parameters generated by \fIDH_generate_parameters_ex()\fR and \fIDH_generate_parameters()\fR -are not to be used in signature schemes. -.SH "BUGS" -.IX Header "BUGS" -If \fBgenerator\fR is not 2 or 5, \fBdh\->g\fR=\fBgenerator\fR is not -a usable generator. +The error codes can be obtained by \fIERR_get_error\fR\|(3). .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIdh\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3), +\&\fIDH_new\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3), \&\fIDH_free\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" -\&\fIDH_check()\fR is available in all versions of SSLeay and OpenSSL. -The \fBcb_arg\fR argument to \fIDH_generate_parameters()\fR was added in SSLeay 0.9.0. +\&\fIDH_generate_parameters()\fR was deprecated in OpenSSL 0.9.8; use +\&\fIDH_generate_parameters_ex()\fR instead. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. .PP -In versions before OpenSSL 0.9.5, \s-1DH_CHECK_P_NOT_STRONG_PRIME\s0 is used -instead of \s-1DH_CHECK_P_NOT_SAFE_PRIME.\s0 +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |