MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClRsa_Functions

Defines all functions of mcuxClRsa. More...

Functions

 MCUX_CSSL_FP_PROTECTED_TYPE (mcuxClRsa_Status_t) mcuxClRsa_sign(mcuxClSession_Handle_t pSession
 RSA sign operation. More...
 

Variables

const mcuxClRsa_Key *const pKey
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t pMessageOrDigest
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t messageLength
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t const mcuxClRsa_SignVerifyMode pPaddingMode
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t const mcuxClRsa_SignVerifyMode const uint32_t saltLength
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t const mcuxClRsa_SignVerifyMode const uint32_t const uint32_t options
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t const mcuxClRsa_SignVerifyMode const uint32_t const uint32_t mcuxCl_Buffer_t pSignature
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t mcuxCl_Buffer_t const mcuxClRsa_SignVerifyMode pVerifyMode
 
const mcuxClRsa_Key *const mcuxCl_InputBuffer_t const uint32_t mcuxCl_Buffer_t const mcuxClRsa_SignVerifyMode const uint32_t const uint32_t mcuxCl_Buffer_t pOutput
 
mcuxClKey_Type_t type
 
mcuxClKey_Type_t mcuxClKey_Protection_t protection
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t privKey
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t uint8_t * pPrivData
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t uint8_t uint32_t *const pPrivDataLength
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t uint8_t uint32_t *const mcuxClKey_Handle_t pubKey
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t uint8_t uint32_t *const mcuxClKey_Handle_t uint8_t * pPubData
 
mcuxClKey_Type_t mcuxClKey_Protection_t mcuxClKey_Handle_t uint8_t uint32_t *const mcuxClKey_Handle_t uint8_t uint32_t *const pPubDataLength
 
mcuxClEcc_Weier_DomainParams_t mcuxClEcc_Weier_BasicDomainParams_t uint32_t options
 

Detailed Description

Defines all functions of mcuxClRsa.

Function Documentation

◆ MCUX_CSSL_FP_PROTECTED_TYPE()

MCUX_CSSL_FP_PROTECTED_TYPE ( mcuxClRsa_Status_t  )

RSA sign operation.

Deprecated type for mcuxClSession protected status codes.

Deprecated type for RSA protected status codes.

Deprecated type for error codes used by code-flow protected PKC component functions.

Deprecated type for error codes used by code-flow protected mcuxClMemory component functions.

Deprecated type for error codes used by code-flow protected Math component functions.

Deprecated type for Key component error codes, returned by functions with code-flow protection.

Deprecated type for ELS driver protected status codes.

Deprecated type for mcuxClEcc component return codes.

RSA key generation of private plain key operation.

Generates an RSA key in CRT format.

RSA verify 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]pSessionPointer to mcuxClSession_Descriptor
[in]pKeyPointer to key structure of type mcuxClRsa_Key
[in]pMessageOrDigestPointer to buffer, which contains the input to the sign operation
[in]messageLengthByte-length of MessageOrDigest
[in]pPaddingModePointer to signing mode of type mcuxClRsa_SignVerifyMode_t
[in]saltLengthByte-length of salt
[in]optionsOptions field
[out]pSignaturePointer 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:
pMessageOrDigest:
The input must meet the following conditions:
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:
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_OKSign operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_ERRORAn 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.

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]pSessionPointer to mcuxClSession_Descriptor
[in]pKeyPointer to key structure of type mcuxClRsa_Key
[in]pMessageOrDigestPointer to buffer, which contains the input to the verify operation
[in]messageLengthByte-length of MessageOrDigest
[in]pSignaturePointer to buffer, which contains the signature
[in]pVerifyModePointer to verification mode of type mcuxClRsa_SignVerifyMode_t
[in]saltLengthByte-length of salt
[in]optionsOptions field
[out]pOutputPointer 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:
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_OKVerify operation executed successfully.
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OKVerification primitive operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_VERIFY_FAILEDThe signature verification failed.
MCUXCLRSA_STATUS_ERRORAn 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.

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.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key.
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private CRT key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill 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_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn 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.

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.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private plain key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill 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_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn 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.