DOC: Extend EVP_PKEY-DSA(7) / EVP_PKEY_DH(7) with FFC information
Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/11546)master
Shane Lontis
Pauli
parent
33df1cfdd5
commit
9e537cd2ad
|
|
@ -37,10 +37,20 @@ creating a key from user data.
|
|||
|
||||
EVP_PKEY_fromdata() creates the structure to store key parameters or a
|
||||
key, given data from I<params> and a context that's been initialized with
|
||||
EVP_PKEY_param_fromdata_init() or EVP_PKEY_key_fromdata_init(). The result
|
||||
is written to I<*ppkey>. The parameters that can be used are specific to
|
||||
the L<provider-keymgmt(7)> implementations, please see
|
||||
L<EVP_PKEY_CTX_new_from_name(3)> for further information.
|
||||
EVP_PKEY_param_fromdata_init() or EVP_PKEY_key_fromdata_init(). The result is
|
||||
written to I<*ppkey>. The parameters that can be used for various types of key
|
||||
are as described by the diverse "Common parameters" sections of the
|
||||
L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
|
||||
L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
|
||||
L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
|
||||
L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
|
||||
L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
|
||||
|
||||
=for comment the awful list of links above is made this way so we get nice
|
||||
rendering as a man-page while still getting proper links in HTML
|
||||
|
||||
EVP_PKEY_param_fromdata_settable() and EVP_PKEY_key_fromdata_settable()
|
||||
get a constant B<OSSL_PARAM> array that describes the settable parameters
|
||||
|
|
@ -210,7 +220,10 @@ example with L<OSSL_PARAM_allocate_from_text(3)>.
|
|||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
|
||||
L<OSSL_PARAM(3)>
|
||||
L<OSSL_PARAM(3)>,
|
||||
L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
@ -218,7 +231,7 @@ These functions were added in OpenSSL 3.0.
|
|||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
||||
Copyright 2019-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
|
||||
|
|
|
|||
|
|
@ -10,10 +10,61 @@ EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
|
|||
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 domain parameters
|
||||
and private keys I<pub> and I<priv> as well as the three main domain parameters
|
||||
I<p>, I<q> and I<g>.
|
||||
|
||||
=head2 Common DSA / DH parameters
|
||||
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.
|
||||
|
||||
For B<DH> FFC key agreement, two classes of domain parameters can be used:
|
||||
"safe" domain parameters that are associated with approved named safe-prime
|
||||
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
|
||||
parameters should only be used for backward compatibility with existing
|
||||
applications that cannot be upgraded to use the approved safe-prime groups.
|
||||
|
||||
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 Common DH parameters
|
||||
|
||||
=over 4
|
||||
|
||||
=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
|
||||
|
||||
A string that associates a B<DH> named safe prime group with known values for
|
||||
I<p>, I<q> and I<g>.
|
||||
|
||||
The following values can be used by the default and OpenSSL's FIPS providers:
|
||||
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
|
||||
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
|
||||
|
||||
The following additional values can also be used by the default provider:
|
||||
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
|
||||
|
||||
DH named groups can be easily validated since the parameters are well known.
|
||||
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
|
||||
retrieved.
|
||||
|
||||
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
|
||||
|
||||
Used for DH generation of safe primes using the old generator code.
|
||||
It is recommended to use a named safe prime group instead, if domain parameter
|
||||
validation is required. The default value is 2.
|
||||
|
||||
These are not named safe prime groups so setting this value for the OpenSSL FIPS
|
||||
provider will instead choose a named safe prime group based on the size of I<p>.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Common DSA & DH 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
|
||||
|
|
@ -31,21 +82,171 @@ The private key value.
|
|||
|
||||
=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
|
||||
|
||||
A DSA or Diffie-Hellman "p" value.
|
||||
A DSA or Diffie-Hellman prime "p" value.
|
||||
|
||||
=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
|
||||
|
||||
A DSA or Diffie-Hellman "q" value.
|
||||
A DSA or Diffie-Hellman prime "q" value.
|
||||
|
||||
=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
|
||||
|
||||
A DSA or Diffie-Hellman "g" value.
|
||||
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 (p - 1) / q.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head2 DSA / DH key generation (FFC) parameters
|
||||
|
||||
The following Key Generation types are available for the built-in FFC algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
|
||||
|
||||
Sets the type of parameter generation. For DH Valid values are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "fips186_4"
|
||||
|
||||
The current standard. This is the default value.
|
||||
|
||||
=item "default"
|
||||
|
||||
This is an alias to use the latest implemented standard.
|
||||
It is currently set to "fips186_4".
|
||||
|
||||
=item "group"
|
||||
|
||||
This specifies that a named safe prime name will be chosen using the "pbits"
|
||||
type.
|
||||
|
||||
=item "fips186_2"
|
||||
|
||||
The old standard that should only be used for legacy purposes.
|
||||
|
||||
=item "generator"
|
||||
|
||||
A safe prime generator. See the "safeprime-generator" type.
|
||||
|
||||
=back
|
||||
|
||||
For DSA valid values are one of "default", "fips186_4" or "fips186_2" as
|
||||
described above.
|
||||
|
||||
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
|
||||
|
||||
Sets the size (in bits) of the prime 'p'.
|
||||
|
||||
For "fips186_4" this must be 2048 for DH, and either of 2048 or 3072 for DSA.
|
||||
For "fips186_2" this must be 1024.
|
||||
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
|
||||
|
||||
=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 "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
|
||||
|
||||
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
|
||||
|
||||
=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
|
||||
|
||||
[TBA]
|
||||
=over 4
|
||||
|
||||
=item RFC 7919 (TLS ffdhe named safe prime groups)
|
||||
|
||||
=item RFC 3526 (IKE modp named safe prime groups)
|
||||
|
||||
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
|
||||
and "dh_2048_256").
|
||||
|
||||
=back
|
||||
|
||||
The following sections of SP800-56Ar3:
|
||||
|
||||
=over 4
|
||||
|
||||
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
|
||||
|
||||
=item Appendix D: FFC Safe-prime Groups
|
||||
|
||||
=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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue