MCUX CLNS MCUX Crypto Library Normal Secure |

Functions
mcuxClRsa_Functions
mcuxClRsa

Defines all functions of mcuxClRsa. More...

## Functions

mcuxClRsa_Status_Protected_t | mcuxClRsa_sign (mcuxClSession_Handle_t pSession, const mcuxClRsa_Key *const pKey, const uint8_t *const pMessageOrDigest, const uint32_t messageLength, const mcuxClRsa_SignVerifyMode pPaddingMode, const uint32_t saltLength, const uint32_t options, uint8_t *const pSignature)
| RSA sign operation. More...
mcuxClRsa_Status_Protected_t | mcuxClRsa_verify (mcuxClSession_Handle_t pSession, const mcuxClRsa_Key *const pKey, const uint8_t *const pMessageOrDigest, const uint32_t messageLength, uint8_t *const pSignature, const mcuxClRsa_SignVerifyMode pVerifyMode, const uint32_t saltLength, const uint32_t options, uint8_t *const pOutput)
| RSA verify operation. More...

## Detailed Description

Defines all functions of mcuxClRsa.

## Function Documentation

## ◆ mcuxClRsa_sign()

mcuxClRsa_Status_Protected_t mcuxClRsa_sign | ( | mcuxClSession_Handle_t | pSession,
|  | const mcuxClRsa_Key *const | pKey,
|  | const uint8_t *const | pMessageOrDigest,
|  | const uint32_t | messageLength,
|  | const mcuxClRsa_SignVerifyMode | pPaddingMode,
|  | const uint32_t | saltLength,
|  | const uint32_t | options,
|  | uint8_t *const | 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 mcuxClRsa_Status_Protected_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.

Examples
  mcuxClRsa_sign_NoEncode_example.c, and mcuxClRsa_sign_pss_sha2_256_example.c.

## ◆ mcuxClRsa_verify()

mcuxClRsa_Status_Protected_t mcuxClRsa_verify | ( | mcuxClSession_Handle_t | pSession,
|  | const mcuxClRsa_Key *const | pKey,
|  | const uint8_t *const | pMessageOrDigest,
|  | const uint32_t | messageLength,
|  | uint8_t *const | pSignature,
|  | const mcuxClRsa_SignVerifyMode | pVerifyMode,
|  | const uint32_t | saltLength,
|  | const uint32_t | options,
|  | uint8_t *const | 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 mcuxClRsa_Status_Protected_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.

Examples
  mcuxClRsa_verify_NoVerify_example.c, and mcuxClRsa_verify_pssverify_sha2_256_example.c.