mcuxClRsa_Functions

Defines all functions of mcuxClRsa. More...

Functions
mcuxClRsa_Status_t	mcuxClRsa_sign (mcuxClSession_Handle_t pSession, const mcuxClRsa_Key *const pKey, mcuxCl_InputBuffer_t pMessageOrDigest, const uint32_t messageLength, const mcuxClRsa_SignVerifyMode pPaddingMode, const uint32_t saltLength, const uint32_t options, mcuxCl_Buffer_t pSignature)
	RSA sign operation.
mcuxClRsa_Status_t	mcuxClRsa_verify (mcuxClSession_Handle_t pSession, const mcuxClRsa_Key *const pKey, mcuxCl_InputBuffer_t pMessageOrDigest, const uint32_t messageLength, mcuxCl_Buffer_t pSignature, const mcuxClRsa_SignVerifyMode pVerifyMode, const uint32_t saltLength, const uint32_t options, mcuxCl_Buffer_t pOutput)
	RSA verify operation.
mcuxClRsa_Status_t	mcuxClRsa_KeyGeneration_Crt (mcuxClSession_Handle_t pSession, mcuxClKey_Type_t type, mcuxClKey_Protection_t protection, mcuxClKey_Handle_t privKey, uint8_t *pPrivData, uint32_t *const pPrivDataLength, mcuxClKey_Handle_t pubKey, uint8_t *pPubData, uint32_t *const pPubDataLength)
	Generates an RSA key in CRT format.
mcuxClRsa_Status_t	mcuxClRsa_KeyGeneration_Plain (mcuxClSession_Handle_t pSession, mcuxClKey_Type_t type, mcuxClKey_Protection_t protection, mcuxClKey_Handle_t privKey, uint8_t *pPrivData, uint32_t *const pPrivDataLength, mcuxClKey_Handle_t pubKey, uint8_t *pPubData, uint32_t *const pPubDataLength)
	RSA key generation of private plain key operation.
mcuxClRsa_Status_t	mcuxClRsa_KeyGeneration_Init (mcuxClSession_Handle_t pSession, mcuxClKey_Type_t type, uint32_t *byteLenE)
	RSA key generation initialization.
mcuxClRsa_Status_t	mcuxClRsa_KeyGeneration_StorePrivateCRT (mcuxClSession_Handle_t pSession, uint8_t *pPrivData, uint32_t *const pPrivDataLength, uint32_t byteLenPrime)
	Store RSA Private CRT key.
mcuxClRsa_Status_t	mcuxClRsa_KeyGeneration_StorePrivatePlain (mcuxClSession_Handle_t pSession, uint8_t *pPrivData, uint32_t *const pPrivDataLength, uint8_t *pPubData, uint32_t dLen)
	Store RSA Prviate Plain key.

Detailed Description

Defines all functions of mcuxClRsa.

Function Documentation

mcuxClRsa_sign()

mcuxClRsa_Status_t mcuxClRsa_sign	(	mcuxClSession_Handle_t	pSession,
		const mcuxClRsa_Key *const	pKey,
		mcuxCl_InputBuffer_t	pMessageOrDigest,
		const uint32_t	messageLength,
		const mcuxClRsa_SignVerifyMode	pPaddingMode,
		const uint32_t	saltLength,
		const uint32_t	options,
		mcuxCl_Buffer_t	pSignature
	)

RSA sign operation.

This function performs an RSA signature generation according to RSASP1, RSASSA-PSS-SIGN or RSASSA-PKCS1-v1_5-SIGN of PKCS #1 v2.2. Based on the passed key type, it is selected, whether to perform this operation using a private plain, a private CRT key, or whether to use a private CRT key and protect the operation against perturbation attacks. Based on the selection of the padding mode, it is determined, whether to perform no padding, or whether to perform one of the supported paddings based on one of the supported hash functions. The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8. The private exponent is limited to d < n.

Parameters

[in]	pSession	Pointer to mcuxClSession_Descriptor
[in]	pKey	Pointer to key structure of type mcuxClRsa_Key
[in]	pMessageOrDigest	Pointer to buffer, which contains the input to the sign operation
[in]	messageLength	Byte-length of MessageOrDigest
[in]	pPaddingMode	Pointer to signing mode of type mcuxClRsa_SignVerifyMode_t
[in]	saltLength	Byte-length of salt
[in]	options	Options field
[out]	pSignature	Pointer to buffer, which contains the result (signature)

Parameter properties

pSession:

The session pointed to by pSession has to be initialized prior to a call to this function.

pKey:

The key entries must meet the following conditions:

• Entry keytype can be set to MCUXCLRSA_KEY_PRIVATEPLAIN to perform the secure exponentiation with a private plain key, MCUXCLRSA_KEY_PRIVATECRT to perform the secure exponentiation with a private CRT key, or MCUXCLRSA_KEY_PRIVATECRT_DFA to perform the secure exponentiation with a private CRT key, protecting the operation against perturbation attacks. In case of specifying another key type, the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
• The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8;
• In case of type MCUXCLRSA_KEY_PRIVATEPLAIN, the exponent d must be smaller than modulus n; in case of type MCUXCLRSA_KEY_PRIVATECRT or MCUXCLRSA_KEY_PRIVATECRT_DFA, the d from which dp and dq are derived must be smaller than (p * q);
• In case of type MCUXCLRSA_KEY_PRIVATECRT or MCUXCLRSA_KEY_PRIVATECRT_DFA it is required that: bitlength(p) == bitlength(q) == 1/2 * bitlength(n).

pMessageOrDigest:

The input must meet the following conditions:

• It must be given in big-endian byte order;
• In case of key type MCUXCLRSA_KEY_PRIVATEPLAIN and mode mcuxClRsa_Mode_Sign_NoEncode, the input must be smaller than n, otherwise the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
• In case of type MCUXCLRSA_KEY_PRIVATECRT or MCUXCLRSA_KEY_PRIVATECRT_DFA and mode mcuxClRsa_Mode_Sign_NoEncode, the input must be smaller than (p * q), otherwise the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
• In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST the length of pMessageOrDigest is determined by the selected hash algorithm;
• In case of mode mcuxClRsa_Mode_Sign_NoEncode the length of pMessageOrDigest is determined by the length of n;
• The signature length is determined by the modulus length (bytelength(n)).

messageLength:

This value is only regarded in case of option MCUXCLRSA_OPTION_MESSAGE_PLAIN. In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST, or mode RSASP1, please set to zero.

pPaddingMode:

The mode specifies the targeted padding and hashing algorithms. Please set to one of mcuxClRsa_Sign_Modes.

saltLength:

This value is only regarded in case of performing a RSASSA-PSS-SIGN operation. Otherwise, please set to zero.

options:

This field is used to select options of the sign operation:

• bits 31-8: RFU; please set to zero
• bits 7-0: Specify, whether pMessageOrDigest points to a plain message (MCUXCLRSA_OPTION_MESSAGE_PLAIN) to be hashed internally by the sign function, or to a message digest (MCUXCLRSA_OPTION_MESSAGE_DIGEST). In case of mode RSASP1, please set to zero.

pSignature:

The output is returned in in big-endian byte order.

Returns

Status of the mcuxClRsa_sign operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))

Return values

MCUXCLRSA_STATUS_SIGN_OK	Sign operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUT	The input parameters are not valid.
MCUXCLRSA_STATUS_ERROR	An error occurred during the execution. In that case, expectations for the flow protection are not balanced.

Attention

This function uses PRNG which has to be initialized prior to calling the function.

Examples

mcuxClRsa_sign_NoEncode_example.c, and mcuxClRsa_sign_pss_sha2_256_example.c.

mcuxClRsa_verify()

mcuxClRsa_Status_t mcuxClRsa_verify	(	mcuxClSession_Handle_t	pSession,
		const mcuxClRsa_Key *const	pKey,
		mcuxCl_InputBuffer_t	pMessageOrDigest,
		const uint32_t	messageLength,
		mcuxCl_Buffer_t	pSignature,
		const mcuxClRsa_SignVerifyMode	pVerifyMode,
		const uint32_t	saltLength,
		const uint32_t	options,
		mcuxCl_Buffer_t	pOutput
	)

RSA verify operation.

This function performs an RSA signature verification according to RSAVP1, RSASSA-PSS-VERIFY or RSASSA-PKCS1-v1_5-VERIFY of PKCS #1 v2.2. Based on the selection of the padding mode, it is determined, whether to perform no padding verification, or whether to perform one of the supported padding verifications based on one of the supported hash functions. The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8. The public exponent is limited to 2 <= e < N.

Parameters

[in]	pSession	Pointer to mcuxClSession_Descriptor
[in]	pKey	Pointer to key structure of type mcuxClRsa_Key
[in]	pMessageOrDigest	Pointer to buffer, which contains the input to the verify operation
[in]	messageLength	Byte-length of MessageOrDigest
[in]	pSignature	Pointer to buffer, which contains the signature
[in]	pVerifyMode	Pointer to verification mode of type mcuxClRsa_SignVerifyMode_t
[in]	saltLength	Byte-length of salt
[in]	options	Options field
[out]	pOutput	Pointer to output buffer

Parameter properties

pSession:

The session pointed to by pSession has to be initialized prior to a call to this function.

pKey:

The key entries must meet the following conditions:

• Entry keytype must be set to MCUXCLRSA_KEY_PUBLIC. In case of passing another key type, the function returns MCUXCLRSA_STATUS_INVALID_INPUT. The functions checks, internally, whether the required key entries are not set to NULL. If so, the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
• The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8;
• It is required that e is greater or equal to 2 and smaller than n.

pMessageOrDigest:

The input must meet the following conditions:

• It must be provided in big-endian byte order;
• In case of mode RSAVP1, please set to NULL.

messageLength:

This value is only regarded in case of option MCUXCLRSA_OPTION_MESSAGE_PLAIN. In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST, or mode RSAVP1, please set to zero.

pSignature:

The signature must meet the following conditions:

• It must be given in big-endian byte order;
• The signature length is determined by the modulus length (bytelength(n));
• The signature value must be smaller than n. If it is bigger the function returns MCUXCLRSA_STATUS_INVALID_INPUT.

pVerifyMode:

The mode specifies the targeted padding verification and hashing algorithms. Please set to one of mcuxClRsa_Verify_Modes.

saltLength:

This value is only regarded in case of performing a RSASSA-PSS-VERIFY operation. Otherwise, please set to zero.

options:

This field is used to select options of the sign operation:

• bits 31-8: RFU; please set to zero
• bits 7-0: Specify, whether pMessageOrDigest points to a plain message (MCUXCLRSA_OPTION_MESSAGE_PLAIN) to be hashed internally by the verify function, or to a message digest (MCUXCLRSA_OPTION_MESSAGE_DIGEST). In case of mode RSAVP1, please set to zero.

pOutput:

In case of mode RSAVP1 this pointer points to the buffer, where the result will be stored in big-endian byte order. This buffer must have the same byte-length as the modulus. In case of modes RSASSA-PSS-VERIFY and RSASSA-PKCS1-v1_5-VERIFY please set to NULL.

Returns

Status of the mcuxClRsa_verify operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))

Return values

MCUXCLRSA_STATUS_VERIFY_OK	Verify operation executed successfully.
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OK	Verification primitive operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUT	The input parameters are not valid.
MCUXCLRSA_STATUS_VERIFY_FAILED	The signature verification failed.
MCUXCLRSA_STATUS_ERROR	An error occurred during the execution. In that case, expectations for the flow protection are not balanced.

Attention

This function uses PRNG which has to be initialized prior to calling the function.

Examples

mcuxClRsa_verify_NoVerify_example.c, and mcuxClRsa_verify_pssverify_sha2_256_example.c.

mcuxClRsa_KeyGeneration_Crt()

mcuxClRsa_Status_t mcuxClRsa_KeyGeneration_Crt	(	mcuxClSession_Handle_t	pSession,
		mcuxClKey_Type_t	type,
		mcuxClKey_Protection_t	protection,
		mcuxClKey_Handle_t	privKey,
		uint8_t *	pPrivData,
		uint32_t *const	pPrivDataLength,
		mcuxClKey_Handle_t	pubKey,
		uint8_t *	pPubData,
		uint32_t *const	pPubDataLength
	)

Generates an RSA key in CRT format.

This function for given public exponent and key size generates an RSA private key in CRT representation (p, q, dp, dq, qInv) and computes the modulus n.

Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

The two key handles are linked with each other using mcuxClKey_linkKeyPair.

Parameters

[in]	pSession	Pointer to mcuxClSession_Descriptor
[in]	type	Type of the key
[in]	protection	Protection and flush mechanism that must be applied to the generated key.
[out]	privKey	Key handle for the generated private key
[out]	pPrivData	Pointer to the buffer where the generated private CRT key data needs to be written
[out]	pPrivDataLength	Will be set by the number of bytes of data that have been written to the pPrivData buffer
[out]	pubKey	Key handle for the generated public key
[out]	pPubData	Pointer to the buffer where the generated public key data needs to be written
[out]	pPubDataLength	Will be set by the number of bytes of data that have been written to the pPubData buffer

Parameter properties

pSession:

The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.

type:

Type of the key. It contains information about the input parameters:

• type.size - length of the generated key
• type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t* (i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).

protection :

Protection and flush mechanism that must be applied to the generated key.

privKey:

Key handle for the generated private key.

pPrivData:

Pointer to the buffer where the generated private CRT key (p, q, qInv, dp, dq) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: p, q, qInv, dp, dq. Buffer is allocated by the caller.

pPrivDataLength:

Number of bytes of data that have been written to the pPrivData buffer.

pubKey:

Key handle for the generated public key.

pPubData:

Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.

pPubDataLength:

Number of bytes of data that have been written to the pPubData buffer.

Returns

Status of the mcuxClRsa_KeyGeneration_Crt operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))

Return values

MCUXCLRSA_STATUS_KEYGENERATION_OK	RSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUT	The input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED	RSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERROR	An error occurred during the execution. In that case, expectations for the flow protection are not balanced.

Attention

This function uses DRBG and PRNG which have to be initialized prior to calling the function.

mcuxClRsa_KeyGeneration_Plain()

mcuxClRsa_Status_t mcuxClRsa_KeyGeneration_Plain	(	mcuxClSession_Handle_t	pSession,
		mcuxClKey_Type_t	type,
		mcuxClKey_Protection_t	protection,
		mcuxClKey_Handle_t	privKey,
		uint8_t *	pPrivData,
		uint32_t *const	pPrivDataLength,
		mcuxClKey_Handle_t	pubKey,
		uint8_t *	pPubData,
		uint32_t *const	pPubDataLength
	)

RSA key generation of private plain key operation.

This function for given public exponent and key size generates RSA private key in in plain from (d, n).

Private exponent d is computed with the requirements specified in the FIPS 186-4, Appendix B.3.1. Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

The two key handles are linked with each other using mcuxClKey_linkKeyPair.

Parameters

[in]	pSession	Pointer to mcuxClSession_Descriptor
[in]	type	Type of the key
[in]	protection	Protection and flush mechanism that must be applied to the generated key
[out]	privKey	Key handle for the generated private key
[out]	pPrivData	Pointer to the buffer where the generated private plain key data needs to be written
[out]	pPrivDataLength	Will be set by the number of bytes of data that have been written to the pPrivData buffer
[out]	pubKey	Key handle for the generated public key
[out]	pPubData	Pointer to the buffer where the generated public key data needs to be written
[out]	pPubDataLength	Will be set by the number of bytes of data that have been written to the pPubData buffer

Parameter properties

pSession:

The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.

type:

Type of the key. It contains information about the input parameters:

• type.size - length of the generated key
• type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t*(i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).

protection :

Protection and flush mechanism that must be applied to the generated key.

privKey:

Key handle for the generated private key.

pPrivData:

Pointer to the buffer where the generated private plain key (n, d) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, d. Buffer is allocated by the caller.

pPrivDataLength:

Number of bytes of data that have been written to the pPrivData buffer.

pubKey:

Key handle for the generated public key.

pPubData:

Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.

pPubDataLength:

Number of bytes of data that have been written to the pPubData buffer.

Returns

Status of the mcuxClRsa_KeyGeneration_Plain operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))

Return values

MCUXCLRSA_STATUS_KEYGENERATION_OK	RSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUT	The input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED	RSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERROR	An error occurred during the execution. In that case, expectations for the flow protection are not balanced.

Attention

This function uses DRBG and PRNG which have to be initialized prior to calling the function.

mcuxClRsa_KeyGeneration_Init()

mcuxClRsa_Status_t mcuxClRsa_KeyGeneration_Init	(	mcuxClSession_Handle_t	pSession,
		mcuxClKey_Type_t	type,
		uint32_t *	byteLenE
	)

RSA key generation initialization.

This function checks key type, checks entropy provided by RNG and check if E is FIPS compliant.

Parameters

[in]	pSession	Handle for the current CL session.
[in]	type	Type of the key
[out]	byteLenE	Pointer to variable where length of E shall be stored

Returns

Status of the mcuxClRsa_KeyGeneration_Init operation.

Return values

MCUXCLKEY_STATUS_OK	Initialization operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUT	E is not valid

mcuxClRsa_KeyGeneration_StorePrivateCRT()

mcuxClRsa_Status_t mcuxClRsa_KeyGeneration_StorePrivateCRT	(	mcuxClSession_Handle_t	pSession,
		uint8_t *	pPrivData,
		uint32_t *const	pPrivDataLength,
		uint32_t	byteLenPrime
	)

Store RSA Private CRT key.

Store RSA private CRT key (p, q, qInv, dp, dq) to the buffer pointed by pPrivData. pPrivData buffer for storing RSA key (mcuxClRsa_Key data type, i.e.: key type and key entries) followed by the key data, i.e.: p, q, qInv, dp, dq. Key entries stored in big-endian byte order (copy with reverse order).

Parameters

[in]	pSession	Handle for the current CL session.
[in]	pPrivData	Pointer to buffer where RSA CRT key will be stored
[out]	pPrivDataLength	Pointer to variable where length of pPrivData shall be stored
[in]	byteLenPrime	Length of prime

Returns

Status of the mcuxClRsa_KeyGeneration_Init operation.

Return values

MCUXCLKEY_STATUS_OK	Initialization operation executed successfully.
MCUXCLRSA_STATUS_ERROR	Error occured during export

mcuxClRsa_KeyGeneration_StorePrivatePlain()

mcuxClRsa_Status_t mcuxClRsa_KeyGeneration_StorePrivatePlain	(	mcuxClSession_Handle_t	pSession,
		uint8_t *	pPrivData,
		uint32_t *const	pPrivDataLength,
		uint8_t *	pPubData,
		uint32_t	dLen
	)

Store RSA Prviate Plain key.

Store RSA private plain key (d, n) to the buffer pointed by pPrivData. pPrivData buffer for storing RSA key (mcuxClRsa_Key data type, i.e.: key type and key entries) followed by the key data, i.e.: n, d. Key entries stored in big-endian byte order (copy with reverse order).

Parameters

[in]	pSession	Handle for the current CL session.
[out]	pPrivData	Pointer to the buffer where the generated private plain key data needs to be stored
[out]	pPrivDataLength	Pointer to variable where length of pPrivData shall be stored
[in]	pPubData	Pointer to buffer where RSA public key is stored
[in]	dLen	Length of private exponent

Returns

Status of the mcuxClRsa_KeyGeneration_Init operation.

Return values

MCUXCLKEY_STATUS_OK	Initialization operation executed successfully.
MCUXCLRSA_STATUS_ERROR	Error occured during export