diff options
author | Shane Lontis <shane.lontis@oracle.com> | 2020-05-26 13:53:07 +1000 |
---|---|---|
committer | Shane Lontis <shane.lontis@oracle.com> | 2020-05-26 13:53:07 +1000 |
commit | b8086652650c0782bc8d63b620663e04a3c6a3a7 (patch) | |
tree | 831362a2004a3b79808f04eb4e387b7e649177ab /doc/man7/EVP_PKEY-FFC.pod | |
parent | f32af93c924dca25728d8e7b85b8e4b660154e12 (diff) |
Update core_names.h fields and document most fields.
Renamed some values in core_names i.e Some DH specific names were changed to use DH instead of FFC.
Added some strings values related to RSA keys.
Moved set_params related docs out of EVP_PKEY_CTX_ctrl.pod into its own file.
Updated Keyexchange and signature code and docs.
Moved some common DSA/DH docs into a shared EVP_PKEY-FFC.pod.
Moved Ed25519.pod into EVP_SIGNATURE-ED25519.pod and reworked it.
Added some usage examples. As a result of the usage examples the following change was also made:
ec allows OSSL_PKEY_PARAM_USE_COFACTOR_ECDH as a settable gen parameter.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11610)
Diffstat (limited to 'doc/man7/EVP_PKEY-FFC.pod')
-rw-r--r-- | doc/man7/EVP_PKEY-FFC.pod | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/doc/man7/EVP_PKEY-FFC.pod b/doc/man7/EVP_PKEY-FFC.pod new file mode 100644 index 0000000000..e97a1c6bc4 --- /dev/null +++ b/doc/man7/EVP_PKEY-FFC.pod @@ -0,0 +1,199 @@ +=pod + +=head1 NAME + +EVP_PKEY-FFC - EVP_PKEY DSA and DH shared FFC parameters. + +=head1 DESCRIPTION + +Finite field cryptography (FFC) is a method of implementing discrete logarithm +cryptography using finite field mathematics. DSA is an example of FFC and +Diffie-Hellman key establishment algorithms specified in SP800-56A can also be +implemented as FFC. + +The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS +providers. +The implementations support the basic DSA and DH keys, containing the public +and private keys I<pub> and I<priv> as well as the three main domain parameters +I<p>, I<q> and I<g>. + +For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard +specifies that the values used for FFC parameter generation are also required +for parameter validation. +This means that optional FFC domain parameter values for I<seed>, I<pcounter> +and I<gindex> may need to be stored for validation purposes. +For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data +(but the I<gindex> is not). For B<DSA> however, these fields are not stored in +the ASN1 data so they need to be stored externally if validation is required. + +=head2 FFC parameters + +In addition to the common parameters that all keytypes should support (see +L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype +implementations support the following. + +=over 4 + +=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer> + +The public key value. + +=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> + +The private key value. + +=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer> + +A DSA or Diffie-Hellman prime "p" value. + +=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer> + +A DSA or Diffie-Hellman prime "q" value. + +=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer> + +A DSA or Diffie-Hellman generator "g" value. + +=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string> + +An optional domain parameter I<seed> value used during generation and validation +of I<p>, I<q> and canonical I<g>. +For validation this needs to set the I<seed> that was produced during generation. + +=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer> + +Sets the index to use for canonical generation and verification of the generator +I<g>. +Set this to a positive value from 0..FF to use this mode. This I<gindex> can +then be reused during key validation to verify the value of I<g>. If this value +is not set or is -1 then unverifiable generation of the generator I<g> will be +used. + +=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer> + +An optional domain parameter I<counter> value that is output during generation +of I<p>. This value must be saved if domain parameter validation is required. + +=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer> + +For unverifiable generation of the generator I<g> this value is output during +generation of I<g>. Its value is the first integer larger than one that +satisfies g = h^j mod p (where g != 1 and "j" is the cofactor). + +=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer> + +An optional informational cofactor parameter that should equal to (p - 1) / q. + +=back + +=head2 FFC key generation parameters + +The following key generation types are available for DSA and DH algorithms: + +=over 4 + +=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string> + +Sets the type of parameter generation. The shared valid values are: + +=over 4 + +=item "fips186_4" + +The current standard. This is the default value. + +=item "fips186_2" + +The old standard that should only be used for legacy purposes. + +=item "default" + +This is an alias to use the latest implemented standard. +It is currently set to "fips186_4". + +=back + +=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> + +Sets the size (in bits) of the prime 'p'. + +=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer> + +Sets the size (in bits) of the prime 'q'. + +For "fips186_4" this can be either 224 or 256. +For "fips186_2" this has a size of 160. + +=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string> + +Sets the Digest algorithm to be used as part of the Key Generation Function +associated with the given Key Generation I<ctx>. +This must also be set for key validation. + +=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string> + +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Generation Function associated with the given key +generation I<ctx>. This may also be set for key validation. + +=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string> + +For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use +instead of generating a random seed internally. This should be used for +testing purposes only. This will either produce fixed values for the generated +parameters OR it will fail if the seed did not generate valid primes. + +=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer> + +=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer> + +=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer> + +These types are described above. + +=back + +=head1 CONFORMING TO + +The following sections of SP800-56Ar3: + +=over 4 + +=item 5.5.1.1 FFC Domain Parameter Selection/Generation + +=back + +The following sections of FIPS 186-4: + +=over 4 + +=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. + +=item A.2.3 Generation of canonical generator g. + +=item A.2.1 Unverifiable Generation of the Generator g. + +=back + +=head1 SEE ALSO + +L<EVP_PKEY-DSA(7)>, +L<EVP_PKEY-DH(7)>, +L<EVP_SIGNATURE-DSA(7)>, +L<EVP_KEYEXCH-DH(7)> +L<EVP_KEYMGMT(3)>, +L<EVP_PKEY(3)>, +L<provider-keymgmt(7)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)>, + +=head1 COPYRIGHT + +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |