From 33df1cfdd54cb8dd35734e6d655cfc4c8b692589 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 14 Apr 2020 19:06:12 +0200 Subject: [PATCH] DOC: Refactor provider-keymgmt(7) to give the keytypes their own pages Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/11546) --- doc/man7/EVP_PKEY-DSA.pod | 65 +++++++++ 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 + 6 files changed, 417 insertions(+), 236 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/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod new file mode 100644 index 0000000000..307a46e019 --- /dev/null +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -0,0 +1,65 @@ +=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 and B 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 and I as well as the three domain parameters +I

, I and I. + +=head2 Common DSA / DH parameters + +In addition to the common parameters that all keytypes should support (see +L), the B and B keytype +implementations support the following. + +=over 4 + +=item "pub" (B) + +The public key value. + +=item "priv" (B) + +The private key value. + +=item "p" (B) + +A DSA or Diffie-Hellman "p" value. + +=item "q" (B) + +A DSA or Diffie-Hellman "q" value. + +=item "g" (B) + +A DSA or Diffie-Hellman "g" value. + +=back + +=head1 CONFORMING TO + +[TBA] + +=head1 SEE ALSO + +L, L, L, +L, L, +L, L + +=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. + +=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 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) + +The EC curve name. + +=item "use-cofactor-flag" (B) + +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 + +See also L for the related +B parameter that can be set on a +per-operation basis. + +=item "pub" (B) + +The public key value in EC point format. + +=item "priv" (B) + +The private key value. + +=back + +=head1 EXAMPLES + +An B context can be obtained by calling: + + EVP_PKEY_CTX *pctx = + EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); + +=head1 SEE ALSO + +L, L, L, +L, L + +=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. + +=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 keytype is implemented in OpenSSL's default and FIPS providers. +That implementation supports the basic RSA keys, containing the modulus I, +the public exponent I, the private exponent I, and a collection of prime +factors, exponents and coefficient for CRT calculations, of which the first +few are known as I

and I, I and I, and I. + +=head2 Common RSA parameters + +In addition to the common parameters that all keytypes should support (see +L), the B keytype implementation +supports the following. + +=over 4 + +=item "n" (B) + +The RSA "n" value. + +=item "e" (B) + +The RSA "e" value. + +=item "d" (B) + +The RSA "d" value. + +=item "rsa-factor1" (B) + +=item "rsa-factor2" (B) + +=item "rsa-factor3" (B) + +=item "rsa-factor4" (B) + +=item "rsa-factor5" (B) + +=item "rsa-factor6" (B) + +=item "rsa-factor7" (B) + +=item "rsa-factor8" (B) + +=item "rsa-factor9" (B) + +=item "rsa-factor10" (B) + +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) + +=item "rsa-exponent2" (B) + +=item "rsa-exponent3" (B) + +=item "rsa-exponent4" (B) + +=item "rsa-exponent5" (B) + +=item "rsa-exponent6" (B) + +=item "rsa-exponent7" (B) + +=item "rsa-exponent8" (B) + +=item "rsa-exponent9" (B) + +=item "rsa-exponent10" (B) + +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) + +=item "rsa-coefficient2" (B) + +=item "rsa-coefficient3" (B) + +=item "rsa-coefficient4" (B) + +=item "rsa-coefficient5" (B) + +=item "rsa-coefficient6" (B) + +=item "rsa-coefficient7" (B) + +=item "rsa-coefficient8" (B) + +=item "rsa-coefficient9" (B) + +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) + +The value should be the cryptographic length for the B cryptosystem, in +bits. + +=item "primes" (B) + +The value should be the number of primes for the generated B 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 context can be obtained by calling: + + EVP_PKEY_CTX *pctx = + EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); + +An B 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 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, L, L + +=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. + +=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, B, B and B 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) + +The public key value. + +=item "priv" (B) + +The private key value. + +=back + +=head1 CONFORMING TO + +=over 4 + +=item RFC 8032 + +=back + +=head1 EXAMPLES + +An B 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 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 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, L, L, +L, L, +L, L + +=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. + +=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, see L. +with the given I, see L. OP_keymgmt_gettable_params() should return a constant array of descriptor B, 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, see L. +with the given I, see L. OP_keymgmt_settable_params() should return a constant array of descriptor B, for parameters that OP_keymgmt_set_params() @@ -328,227 +328,12 @@ from I to I. It is assumed that the caller has ensured that I and I 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) - -Sets the DSA size (in bits) of the prime 'p'. -The value should be 2048 or 3072. - -=item "qbits" (B) - -Sets the DSA size (in bits) of the prime 'q'. -The value should be 224 or 256. - -=item "type" (B) - -Sets the type of parameter generation. -Use 0 for FIPS186-4, or 1 for legacy FIPS186-2. -The default is 0. - -=item "digest" (B) - -Sets the Digest algorithm to be used as part of the Key Generation Function -associated with the given Key Generation I. - -=item "properties" (B) - -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. - -=item "gindex" (B) - -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 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) - -Sets the I 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) - -The RSA "n" value. - -=item "e" (B) - -The RSA "e" value. - -=item "d" (B) - -The RSA "d" value. - -=item "rsa-factor1" (B) - -=item "rsa-factor2" (B) - -=item "rsa-factor3" (B) - -=item "rsa-factor4" (B) - -=item "rsa-factor5" (B) - -=item "rsa-factor6" (B) - -=item "rsa-factor7" (B) - -=item "rsa-factor8" (B) - -=item "rsa-factor9" (B) - -=item "rsa-factor10" (B) - -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) - -=item "rsa-exponent2" (B) - -=item "rsa-exponent3" (B) - -=item "rsa-exponent4" (B) - -=item "rsa-exponent5" (B) - -=item "rsa-exponent6" (B) - -=item "rsa-exponent7" (B) - -=item "rsa-exponent8" (B) - -=item "rsa-exponent9" (B) - -=item "rsa-exponent10" (B) - -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) - -=item "rsa-coefficient2" (B) - -=item "rsa-coefficient3" (B) - -=item "rsa-coefficient4" (B) - -=item "rsa-coefficient5" (B) - -=item "rsa-coefficient6" (B) - -=item "rsa-coefficient7" (B) - -=item "rsa-coefficient8" (B) - -=item "rsa-coefficient9" (B) - -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) - -The public key value. - -=item "priv" (B) - -The private key value. - -=item "p" (B) - -A DSA or Diffie-Hellman "p" value. - -=item "q" (B) - -A DSA or Diffie-Hellman "q" value. - -=item "g" (B) - -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) - -The public key value. - -=item "priv" (B) - -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) - -The EC curve name. - -=item "use-cofactor-flag" (B) - -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) - -The public key value in EC point format. - -=item "priv" (B) - -The private key value. - -=back - -=head2 Information Parameters +=head2 Common Information Parameters See L 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, -B) - -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 for the related -B parameter that can be set on a -per-operation basis. - =back =head1 RETURN VALUES @@ -618,7 +388,10 @@ always return a constant B array. =head1 SEE ALSO -L +L, +L, L, L, +L, L, L, +L, L =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) -- 2.39.2