RSA key generation mode descriptor. More...

Topics
	MCUXCLRSA_KEYGEN_MODE_SIZE
	Definitions of RSA key generation mode descriptor sizes for the mcuxClRsa_KeyGeneration_ModeConstructor function.

Functions
void	mcuxClRsa_KeyGeneration_ModeConstructor (mcuxClKey_GenerationDescriptor_t pKeyGenMode, const uint8_t pE, uint32_t eLength)
	Mode constructor for RSA key generation algorithm.

Detailed Description

RSA key generation mode descriptor.

RSA key generation related defines used construct the mode descriptor used by mcuxClKey_generate_keypair function.

Function Documentation

void mcuxClRsa_KeyGeneration_ModeConstructor	(	mcuxClKey_GenerationDescriptor_t *	pKeyGenMode,
		const uint8_t *	pE,
		uint32_t	eLength )

Mode constructor for RSA key generation algorithm.

This function can be used to create mode descriptor used by mcuxClKey_generate_keypair function. This mode shall be used to realize RSA key generation operation according to FIPS 186-5 (https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), in particular:

method provided in Appendix A.1.3 used for the generation of the random primes p and q that are probably prime;
public exponent e, primes p and q and private exponent d meet the criteria specified in Appendix A.1.1. According to the criteria the exponent e is restricted to odd values in the range \((2^{16}<e<2^{256})\).
primes p and q are generated using probabilistic primality test with the error probability lower than \(2^{-125}\). The number of Miller-Rabin test iterations is consistent with the SOGIS Agreed Cryptographic Mechanisms version 1.2. (https://www.sogis.eu/documents/cc/crypto/SOGIS-Agreed-Cryptographic-Mechanisms-1.2.pdf)

To be able to perform an key generation using mcuxClKey_generate_keypair and this mode:

Session must be initialized with workareas for CPU and PKC operations that considers the workareas required by this mode for the given key type and size (see MCUXCLRSA_KEYGENERATION_PLAIN_WA and MCUXCLRSA_KEYGENERATION_CRT_WA).
RNG context must be initialized using mode mcuxClRandomModes_Constants which will ensure the entropy level (security strength) in accordance with the generated key size, as specified in SP 800-57, Part 1.
Handle of private key must be properly initialized with mcuxClKey_init function using:
- appropriate RSA private Key Type Descriptors;
- pointer to key data buffer where the generated private key will be stored. The buffer shall be allocated using pre-define sizes MCUXCLRSA_KEYGENERATION_KEY_DATA_SIZE for the given key type and key size.
Handle of public key must be properly initialized with mcuxClKey_init function using:
- appropriate RSA public Key Type Descriptors;
- pointer to key data buffer where the generated public key will be stored. The buffer shall be allocated using pre-define sizes MCUXCLRSA_KEYGENERATION_KEY_DATA_SIZE for the given key type and key size.
pointers to key data buffers and key handle must be aligned to CPU word size

Note

There are the following deviations were applied from the algorithm specified in Appendix A.1.3 of FIPS 186-5:

Primes p and q are chosen to be congruent \(3\mod4\).
Rationale: With this additional restriction on p and q a generated key is still compatible with FIPS 186-5. Such primes and their products have properties that simplify algorithms, for example step 4.5 in Miller-Rabin test described in Appendix B.3.1 can be skipped (due to fact that a=1). This restriction has positive impact on the security, performance, and code size. This approach was also accepted in other products.

Checks performed in steps 4.4 and 5.4 are done using only 64 most significant bits of the value specified by the expression \((\sqrt{2})(2^{(nlen/2)–1})\) and rounded up, it is 0xb504f333f9de6485.
Rationale: This deviation is acceptable as it is a stronger condition.

Check performed in step 5.5 (check if \(|p–q| <= 2^{nlen/2–100}\)) is performed after q is generated, it is after testing that q it probably prime. If p and q does not meet this FIPS requirements, a new prime q number will be generated.

The pre-check against products of small primes is applied before the steps 4.5 and 5.6 respectively.

If an event occurs that \(d <= 2^{nlen/2}\) then only a new q will be generated.

Attention: To support all required key lengths, this implementation does not verify that key length meets the FIPS 186-5 criteria (i.e., no check whether the key size is less than 2048 bits). User shall ensure that if FIPS 186-5 compliance is claimed, this mode is used to generate keys of length not less than 2048 bits.; If the key generation operation returns Error or Fault (through session), the user shall ensure that the generated key is cleared and not used.

Parameters

[out]	pKeyGenMode	Pointer to a mode descriptor to be initialized for RSA key pair generation with public exponent input.
[in]	pE	Pointer to the input public exponent e. It must be odd values in the range \(2^{16}<e<2^{256}\).
[in]	eLength	Length of the public exponent e.

Precondition: Before calling this function, sufficient space should be allocated for the key mode descriptor and RSA-specific content, using the macro MCUXCLRSA_KEYGEN_MODE_SIZE.