mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
4f2271d58a
For FIPS validation purposes - Automated Cryptographic Validation Protocol (ACVP) tests need to be performed. (See https://github.com/usnistgov/ACVP). These tests are very similiar to the old CAVS tests. This PR uses a hardwired subset of these test vectors to perform similiar operations, to show the usage and prove that the API's are able to perform the required operations. It may also help with communication with the lab (i.e- The lab could add a test here to show a unworking use case - which we can then address). The EVP layer performs these tests instead of calling lower level API's as was done in the old FOM. Some of these tests require access to internals that are not normally allowed/required. The config option 'acvp_tests' (enabled by default) has been added so that this access may be removed. The mechanism has been implemented as additional OSSL_PARAM values that can be set and get. A callback mechanism did not seem to add any additional benefit. These params will not be added to the gettables lists. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11572)
248 lines
7.6 KiB
Plaintext
248 lines
7.6 KiB
Plaintext
=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.
|
|
Some providers may only support a value of 2.
|
|
|
|
=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
|
|
|
|
The RSA "e" value. The value may be any odd number greater than or equal to
|
|
65537. The default value is 65537.
|
|
For legacy reasons a value of 3 is currently accepted but is deprecated.
|
|
|
|
=back
|
|
|
|
=head2 RSA key generation parameters for FIPS module testing
|
|
|
|
When generating RSA keys, the following additional key generation parameters may
|
|
be used for algorithm testing purposes only. Do not use these to generate
|
|
RSA keys for a production environment.
|
|
|
|
=over 4
|
|
|
|
=item "xp" (B<OSSL_PKEY_PARAM_RSA_TEST_XP>) <unsigned integer>
|
|
|
|
=item "xq" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ>) <unsigned integer>
|
|
|
|
These 2 fields are normally randomly generated and are used to generate "p" and
|
|
"q".
|
|
|
|
=item "xp1" (B<OSSL_PKEY_PARAM_RSA_TEST_XP1>) <unsigned integer>
|
|
|
|
=item "xp2" (B<OSSL_PKEY_PARAM_RSA_TEST_XP2>) <unsigned integer>
|
|
|
|
=item "xq1" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ1>) <unsigned integer>
|
|
|
|
=item "xq2" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ2>) <unsigned integer>
|
|
|
|
These 4 fields are normally randomly generated. The prime factors "p1", "p2",
|
|
"q1" and "q2" are determined from these values.
|
|
|
|
=back
|
|
|
|
=head2 RSA key parameters for FIPS module testing
|
|
|
|
The following intermediate values can be retrieved only if the values
|
|
specified in L</"RSA key generation parameters for FIPS module testing"> are set.
|
|
These should not be accessed in a production environment.
|
|
|
|
=over 4
|
|
|
|
=item "p1" (B<OSSL_PKEY_PARAM_RSA_TEST_P1>) <unsigned integer>
|
|
|
|
=item "p2" (B<OSSL_PKEY_PARAM_RSA_TEST_P2>) <unsigned integer>
|
|
|
|
=item "q1" (B<OSSL_PKEY_PARAM_RSA_TEST_Q1>) <unsigned integer>
|
|
|
|
=item "q2" (B<OSSL_PKEY_PARAM_RSA_TEST_Q2>) <unsigned integer>
|
|
|
|
The auxiliary probable primes.
|
|
|
|
=back
|
|
|
|
=head1 CONFORMING TO
|
|
|
|
=over 4
|
|
|
|
=item FIPS186-4
|
|
|
|
Section B.3.6 Generation of Probable Primes with Conditions Based on
|
|
Auxiliary Probable Primes
|
|
|
|
=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);
|
|
|
|
EVP_PKEY_keygen_init(pctx);
|
|
|
|
params[0] = OSSL_PARAM_construct_uint("bits", &bits);
|
|
params[1] = OSSL_PARAM_construct_uint("primes", &primes);
|
|
params[2] = OSSL_PARAM_construct_end();
|
|
EVP_PKEY_CTX_set_params(pctx, params);
|
|
|
|
EVP_PKEY_gen(pctx, &pkey);
|
|
EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
|
|
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
|