[openssl] master update
Dr. Paul Dale
pauli at openssl.org
Sun Apr 19 22:56:42 UTC 2020
The branch master has been updated
via 9e537cd2ad01b172f2700a670e9269075078a426 (commit)
via 33df1cfdd54cb8dd35734e6d655cfc4c8b692589 (commit)
from 4114964865435edc475c9ba49a7fa2b78956ab76 (commit)
- Log -----------------------------------------------------------------
commit 9e537cd2ad01b172f2700a670e9269075078a426
Author: Shane Lontis <shane.lontis at oracle.com>
Date: Thu Apr 16 12:07:26 2020 +1000
DOC: Extend EVP_PKEY-DSA(7) / EVP_PKEY_DH(7) with FFC information
Reviewed-by: Paul Dale <paul.dale at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11546)
commit 33df1cfdd54cb8dd35734e6d655cfc4c8b692589
Author: Richard Levitte <levitte at openssl.org>
Date: Tue Apr 14 19:06:12 2020 +0200
DOC: Refactor provider-keymgmt(7) to give the keytypes their own pages
Reviewed-by: Paul Dale <paul.dale at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11546)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/EVP_PKEY_fromdata.pod | 25 +++-
doc/man7/EVP_PKEY-DSA.pod | 266 +++++++++++++++++++++++++++++++++++++++++
doc/man7/EVP_PKEY-EC.pod | 64 ++++++++++
doc/man7/EVP_PKEY-RSA.pod | 185 ++++++++++++++++++++++++++++
doc/man7/EVP_PKEY-X25519.pod | 90 ++++++++++++++
doc/man7/provider-keymgmt.pod | 245 ++-----------------------------------
util/missingcrypto.txt | 4 +
7 files changed, 637 insertions(+), 242 deletions(-)
create mode 100644 doc/man7/EVP_PKEY-DSA.pod
create mode 100644 doc/man7/EVP_PKEY-EC.pod
create mode 100644 doc/man7/EVP_PKEY-RSA.pod
create mode 100644 doc/man7/EVP_PKEY-X25519.pod
diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index 0d85e80b95..a1c1ed3772 100644
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -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
diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod
new file mode 100644
index 0000000000..ccb34a9f93
--- /dev/null
+++ b/doc/man7/EVP_PKEY-DSA.pod
@@ -0,0 +1,266 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
+- EVP_PKEY DSA and DH keytype and algorithm support
+
+=head1 DESCRIPTION
+
+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>.
+
+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
+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 (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
+
+=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
+
+L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
+L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
+L<EVP_SIGNATURE-DSA(7)>, L<EVP_KEYEXCH-DH(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
diff --git a/doc/man7/EVP_PKEY-EC.pod b/doc/man7/EVP_PKEY-EC.pod
new file mode 100644
index 0000000000..88d0ebdd36
--- /dev/null
+++ b/doc/man7/EVP_PKEY-EC.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-EC - EVP_PKEY EC keytype and algorithm support
+
+=head1 DESCRIPTION
+
+The B<EC> keytype is implemented in OpenSSL's default provider.
+
+=head2 Common EC parameters
+
+The following Import/Export types are available for the built-in EC algorithm:
+
+=over 4
+
+=item "curve-name" (B<OSSL_PKEY_PARAM_EC_NAME>) <utf8 string>
+
+The EC curve name.
+
+=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
+
+Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
+if the value is zero. The cofactor variant multiplies the shared secret by the
+EC curve's cofactor (note for some curves the cofactor is 1).
+
+=for comment The following link should become L<EVP_KEYEXCH-ECDH(7)>
+
+See also L<provider-keyexch(7)> for the related
+B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
+per-operation basis.
+
+=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
+
+The public key value in EC point format.
+
+=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
+
+The private key value.
+
+=back
+
+=head1 EXAMPLES
+
+An B<EVP_PKEY> context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
+
+=head1 SEE ALSO
+
+L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
+L<EVP_SIGNATURE-ECDSA(7)>, L<EVP_KEYEXCH-ECDH(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
diff --git a/doc/man7/EVP_PKEY-RSA.pod b/doc/man7/EVP_PKEY-RSA.pod
new file mode 100644
index 0000000000..c6533f2ffc
--- /dev/null
+++ b/doc/man7/EVP_PKEY-RSA.pod
@@ -0,0 +1,185 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA
+- EVP_PKEY RSA keytype and algorithm support
+
+=head1 DESCRIPTION
+
+The B<RSA> keytype is implemented in OpenSSL's default and FIPS providers.
+That implementation supports the basic RSA keys, containing the modulus I<n>,
+the public exponent I<e>, the private exponent I<d>, and a collection of prime
+factors, exponents and coefficient for CRT calculations, of which the first
+few are known as I<p> and I<q>, I<dP> and I<dQ>, and I<qInv>.
+
+=head2 Common RSA parameters
+
+In addition to the common parameters that all keytypes should support (see
+L<provider-keymgmt(7)/Common parameters>), the B<RSA> keytype implementation
+supports the following.
+
+=over 4
+
+=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer>
+
+The RSA "n" value.
+
+=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
+
+The RSA "e" value.
+
+=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
+
+The RSA "d" value.
+
+=item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer>
+
+=item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer>
+
+=item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer>
+
+=item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer>
+
+=item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer>
+
+=item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer>
+
+=item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer>
+
+=item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer>
+
+=item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer>
+
+=item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer>
+
+RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
+Up to eight additional "r_i" prime factors are supported.
+
+=item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer>
+
+=item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer>
+
+=item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer>
+
+=item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer>
+
+=item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer>
+
+=item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer>
+
+=item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer>
+
+=item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer>
+
+=item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer>
+
+=item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer>
+
+RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
+as "dP", "dQ" and "d_i in RFC8017".
+Up to eight additional "d_i" exponents are supported.
+
+=item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer>
+
+=item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer>
+
+=item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer>
+
+=item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer>
+
+=item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer>
+
+=item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer>
+
+=item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer>
+
+=item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer>
+
+=item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer>
+
+RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
+"qInv" and "t_i".
+Up to eight additional "t_i" exponents are supported.
+
+=back
+
+=head2 RSA key generation parameters
+
+When generating RSA keys, the following key generation parameters may be used.
+
+=over 4
+
+=item "bits" (B<OSSL_PKEY_PARAM_RSA_BITS>) <unsigned integer>
+
+The value should be the cryptographic length for the B<RSA> cryptosystem, in
+bits.
+
+=item "primes" (B<OSSL_PKEY_PARAM_RSA_PRIMES>) <unsigned integer>
+
+The value should be the number of primes for the generated B<RSA> key. The
+default is 2. It isn't permitted to specify a larger number of primes than
+10. Additionally, the number of primes is limited by the length of the key
+being generated so the maximum number could be less.
+
+=back
+
+=head1 CONFORMING TO
+
+=over 4
+
+=item RFC 8017, excluding RSA-PSS and RSA-OAEP
+
+=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
+and will be described in separate pages for those RSA keytypes.
+
+=back
+
+=head1 EXAMPLES
+
+An B<EVP_PKEY> context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
+
+An B<RSA> key can be generated like this:
+
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
+
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_gen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+
+An B<RSA> key can be generated with key generation parameters:
+
+ unsigned int primes = 3;
+ unsigned int bits = 4096;
+ OSSL_PARAM params[3];
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
+
+ params[0] = OSSL_PARAM_construct_uint("bits", bits);
+ params[1] = OSSL_PARAM_construct_uint("primes", primes);
+ params[2] = OSSL_PARAM_END;
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_CTX_set_params(pctx, params);
+ EVP_PKEY_gen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+
+=head1 SEE ALSO
+
+L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(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
diff --git a/doc/man7/EVP_PKEY-X25519.pod b/doc/man7/EVP_PKEY-X25519.pod
new file mode 100644
index 0000000000..1afa52d041
--- /dev/null
+++ b/doc/man7/EVP_PKEY-X25519.pod
@@ -0,0 +1,90 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-X25519, EVP_PKEY-X448, EVP_PKEY-ED25519, EVP_PKEY-ED448,
+EVP_KEYMGMT-X25519, EVP_KEYMGMT-X448, EVP_KEYMGMT-ED25519, EVP_KEYMGMT-ED448
+- EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support
+
+=head1 DESCRIPTION
+
+The B<X25519>, B<X448>, B<ED25519> and B<ED448> keytypes are
+implemented in OpenSSL's default provider.
+
+=head2 Common X25519, X448, ED25519 and ED448 parameters
+
+The following Import/Export types are available for the built-in X25519, X448,
+ED25519 and X448 algorithms:
+
+=over 4
+
+=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
+
+The public key value.
+
+=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
+
+The private key value.
+
+=back
+
+=head1 CONFORMING TO
+
+=over 4
+
+=item RFC 8032
+
+=back
+
+=head1 EXAMPLES
+
+An B<EVP_PKEY> context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL);
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL);
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL);
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL);
+
+An B<ED25519> key can be generated like this:
+
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL);
+
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_gen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+
+An B<X25519> key can be generated in a similar way:
+
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL);
+
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_gen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+
+=head1 SEE ALSO
+
+L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
+L<EVP_KEYEXCH-X25519(7)>, L<EVP_KEYEXCH-X448(7)>,
+L<EVP_SIGNATURE-ED25519(7)>, L<EVP_SIGNATURE-ED448(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
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index c93abba8eb..0669585b1a 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -258,7 +258,7 @@ present as well.
=head2 Key Object Information Functions
OP_keymgmt_get_params() should extract information data associated
-with the given I<keydata>, see L</Information Parameters>.
+with the given I<keydata>, see L</Common Information Parameters>.
OP_keymgmt_gettable_params() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
@@ -268,7 +268,7 @@ If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
must also be present, and vice versa.
OP_keymgmt_set_params() should update information data associated
-with the given I<keydata>, see L</Information Parameters>.
+with the given I<keydata>, see L</Common Information Parameters>.
OP_keymgmt_settable_params() should return a constant array of
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
@@ -328,227 +328,12 @@ from I<keydata_from> to I<keydata_to>. It is assumed that the caller
has ensured that I<keydata_to> and I<keydata_from> are both owned by
the implementation of this function.
-=head2 Built-in DSA Key Generation Types
-
-The following Key Generation types are available for the built-in DSA algorithm:
-
-=over 4
-
-=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
-
-Sets the DSA size (in bits) of the prime 'p'.
-The value should be 2048 or 3072.
-
-=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
-
-Sets the DSA size (in bits) of the prime 'q'.
-The value should be 224 or 256.
-
-=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <integer>
-
-Sets the type of parameter generation.
-Use 0 for FIPS186-4, or 1 for legacy FIPS186-2.
-The default is 0.
-
-=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>.
-
-=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>.
-
-=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
-
-Sets the index to use for canonical generation and verification of the generator g.
-Set this to a positive value to use this mode. This I<index> can then be reused
-during key validation to verify the value of g. If this value is not set then
-g is not verifiable. The default value is -1.
-
-=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet_string>
-
-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 produced fixed
-values for the generated parameters OR it will fail if the seed did not
-generate valid primes.
-
-=back
-
-
-=head2 Built-in RSA Import/Export Types
-
-The following Import/Export types are available for the built-in RSA algorithm:
-
-=over 4
-
-=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer>
-
-The RSA "n" value.
-
-=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
-
-The RSA "e" value.
-
-=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
-
-The RSA "d" value.
-
-=item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer>
-
-=item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer>
-
-=item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer>
-
-=item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer>
-
-=item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer>
-
-=item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer>
-
-=item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer>
-
-=item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer>
-
-=item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer>
-
-=item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer>
-
-RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
-Up to eight additional "r_i" prime factors are supported.
-
-=item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer>
-
-=item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer>
-
-=item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer>
-
-=item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer>
-
-=item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer>
-
-=item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer>
-
-=item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer>
-
-=item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer>
-
-=item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer>
-
-=item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer>
-
-RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
-as "dP", "dQ" and "d_i in RFC8017".
-Up to eight additional "d_i" exponents are supported.
-
-=item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer>
-
-=item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer>
-
-=item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer>
-
-=item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer>
-
-=item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer>
-
-=item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer>
-
-=item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer>
-
-=item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer>
-
-=item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer>
-
-RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
-"qInv" and "t_i".
-Up to eight additional "t_i" exponents are supported.
-
-=back
-
-=head2 Built-in DSA and Diffie-Hellman Import/Export Types
-
-The following Import/Export types are available for the built-in DSA and
-Diffie-Hellman algorithms:
-
-=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 "p" value.
-
-=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
-
-A DSA or Diffie-Hellman "q" value.
-
-=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
-
-A DSA or Diffie-Hellman "g" value.
-
-=back
-
-=head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
-
-The following Import/Export types are available for the built-in X25519, X448,
-ED25519 and X448 algorithms:
-
-=over 4
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
-
-The public key value.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
-
-The private key value.
-
-=back
-
-=head2 Built-in EC Import/Export Types
-
-The following Import/Export types are available for the built-in EC algorithm:
-
-=over 4
-
-=item "curve-name" (B<OSSL_PKEY_PARAM_EC_NAME>) <utf8 string>
-
-The EC curve name.
-
-=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
-
-Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
-if the value is zero. The cofactor variant multiplies the shared secret by the
-EC curve's cofactor (note for some curves the cofactor is 1).
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
-
-The public key value in EC point format.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
-
-The private key value.
-
-=back
-
-=head2 Information Parameters
+=head2 Common Information Parameters
See L<OSSL_PARAM(3)> for further details on the parameters structure.
-The Built-in Import/Export Types listed above are also Information Parameters.
-Not all parameters are relevant to, or are understood by all keymgmt
-algorithms:
-
-Parameters currently recognised by built-in keymgmt algorithms
-also include the following.
+Common information parameters currently recognised by all built-in
+keymgmt algorithms are as follows:
=over 4
@@ -576,21 +361,6 @@ dimensions handled in the rest of the same provider.
The value should be the number of security bits of the given key.
Bits of security is defined in SP800-57.
-=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
-B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
-
-The value should be either 1 or 0, to respectively enable or disable
-use of the cofactor in operations using this key.
-
-In the context of a key that can be used to perform an Elliptic Curve
-Diffie-Hellman key exchange, this parameter can be used to mark a requirement
-for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
-algorithm.
-
-See also L<provider-keyexch(7)> for the related
-B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
-per-operation basis.
-
=back
=head1 RETURN VALUES
@@ -618,7 +388,10 @@ always return a constant B<OSSL_PARAM> array.
=head1 SEE ALSO
-L<provider(7)>
+L<provider(7)>,
+L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
+L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
+L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
=head1 HISTORY
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index cb8049b832..a84428d733 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -588,6 +588,7 @@ EVP_CIPHER-RC4(7)
EVP_CIPHER-RC5(7)
EVP_CIPHER-SEED(7)
EVP_CIPHER-SM4(7)
+EVP_PKEY(3)
EVP_KDF-KBKDF(7)
EVP_KDF-SSKDF(7)
EVP_KDF-TLS1-PRF(7)
@@ -604,6 +605,9 @@ EVP_KEYMGMT-RSA(7)
EVP_KEYMGMT-X25519(7)
EVP_KEYMGMT-X448(7)
EVP_SIGNATURE-DSA(7)
+EVP_SIGNATURE-ECDSA(7)
+EVP_SIGNATURE-ED25519(7)
+EVP_SIGNATURE-ED448(7)
EVP_SIGNATURE-RSA(7)
ERR_clear_last_mark(3)
ERR_get_state(3)
More information about the openssl-commits
mailing list