MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClMath_Functions

Defines all functions of mcuxClMath. More...

Macros

#define MCUXCLMATH_SHIFTMODULUS(iNShifted, iN)
 Helper macro for mcuxClMath_ShiftModulus. More...
 
#define MCUXCLMATH_FP_SHIFTMODULUS(iNShifted, iN)
 Helper macro for mcuxClMath_ShiftModulus with flow protection. More...
 
#define MCUXCLMATH_NDASH(iN, iT)
 Helper macro for mcuxClMath_NDash. More...
 
#define MCUXCLMATH_FP_NDASH(iN, iT)
 Helper macro for mcuxClMath_NDash with flow protection. More...
 
#define MCUXCLMATH_QDASH(iQDash, iNShifted, iN, iT, len)
 Helper macro for mcuxClMath_QDash. More...
 
#define MCUXCLMATH_FP_QDASH(iQDash, iNShifted, iN, iT, len)
 Helper macro for mcuxClMath_QDash with flow protection. More...
 
#define MCUXCLMATH_QSQUARED(iQSqr, iNShifted, iN, iT)
 Helper macro for mcuxClMath_QSquared. More...
 
#define MCUXCLMATH_FP_QSQUARED(iQSqr, iNShifted, iN, iT)
 Helper macro for mcuxClMath_QSquared with flow protection. More...
 
#define MCUXCLMATH_MODINV(iR, iX, iN, iT)
 Helper macro for mcuxClMath_ModInv. More...
 
#define MCUXCLMATH_FP_MODINV(iR, iX, iN, iT)
 Helper macro for mcuxClMath_ModInv with flow protection. More...
 
#define MCUXCLMATH_REDUCEMODEVEN(iR, iX, iN, iT0, iT1, iT2, iT3)
 Helper macro for mcuxClMath_ReduceModEven. More...
 
#define MCUXCLMATH_FP_REDUCEMODEVEN(iR, iX, iN, iT0, iT1, iT2, iT3)
 Helper macro for mcuxClMath_ReduceModEven with flow protection. More...
 
#define MCUXCLMATH_MODEXP_SQRMULTL2R(pExp, byteLenExp, iR, iX, iN, iT)
 Helper macro for mcuxClMath_ModExp_SqrMultL2R. More...
 
#define MCUXCLMATH_FP_MODEXP_SQRMULTL2R(pExp, byteLenExp, iR, iX, iN, iT)
 Helper macro for mcuxClMath_ModExp_SqrMultL2R with flow protection. More...
 
#define MCUXCLMATH_SECMODEXP(session, pExp, pExpTemp, byteLenExp, iR, iX, iN, iTE, iT0, iT1, iT2, iT3)
 Helper macro for mcuxClMath_SecModExp. More...
 
#define MCUXCLMATH_SECMODEXP_WITHOUT_RERANDOMIZATION(session, pExp, pExpTemp, byteLenExp, iR, iX, iN, iTE, iT0, iT1, iT2, iT3)
 Helper macro for mcuxClMath_SecModExp with disabled operand re-randomization. More...
 
#define MCUXCLMATH_EXACTDIVIDEODD(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
 Helper macro for mcuxClMath_ExactDivideOdd. More...
 
#define MCUXCLMATH_FP_EXACTDIVIDEODD(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
 Helper macro for mcuxClMath_ExactDivideOdd with flow protection. More...
 
#define MCUXCLMATH_EXACTDIVIDE(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
 Helper macro for mcuxClMath_ExactDivide. More...
 
#define MCUXCLMATH_FP_EXACTDIVIDE(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
 Helper macro for mcuxClMath_ExactDivide with flow protection. More...
 

Functions

void mcuxClMath_InitLocalUptrt (uint32_t i3_i2_i1_i0, uint32_t i7_i6_i5_i4, uint16_t *localPtrUptrt, uint8_t noOfIndices, const uint16_t **oldPtrUptrt)
 Initializes and uses the new UPTRT and returns the address of original UPTRT. More...
 
void mcuxClMath_LeadingZeros (uint8_t iX, uint32_t *pNumLeadingZeros)
 Counts number of leading zero bits of a PKC operand. More...
 
uint32_t mcuxClMath_TrailingZeros (uint8_t iX)
 Counts number of trailing zero bits of a PKC operand. More...
 
void mcuxClMath_ShiftModulus (uint16_t iNShifted_iN)
 Prepares shifted modulus. More...
 
void mcuxClMath_NDash (uint16_t iN_iT)
 Prepares modulus (calculates NDash) for PKC modular multiplication. More...
 
void mcuxClMath_QDash (uint32_t iQDash_iNShifted_iN_iT, uint16_t length)
 Calculates QDash = Q * Q' mod n, where Q = 256^(operandSize) mod n, and Q' = 256^length mod n. More...
 
void mcuxClMath_QSquared (uint32_t iQSqr_iNShifted_iN_iT)
 Calculates QSquared = Q^2 mod n, where Q = 256^(operandSize) mod n. More...
 
void mcuxClMath_ModInv (uint32_t iR_iX_iN_iT)
 Calculates modular inversion, with odd modulus. More...
 
void mcuxClMath_ReduceModEven (uint32_t iR_iX_iN_iT0, uint32_t iT1_iT2_iT3)
 Calculates modular reduction with even modulus. More...
 
void mcuxClMath_ModExp_SqrMultL2R (const uint8_t *pExp, uint32_t expByteLength, uint32_t iR_iX_iN_iT)
 Calculates modular exponentiation. More...
 
mcuxClMath_Status_t mcuxClMath_SecModExp (mcuxClSession_Handle_t session, const uint8_t *pExp, uint32_t *pExpTemp, uint32_t expByteLength, uint32_t iT3_iX_iT2_iT1, uint32_t iN_iTE_iT0_iR, uint32_t secOption)
 Securely calculates modular exponentiation. More...
 
void mcuxClMath_ExactDivideOdd (uint32_t iR_iX_iY_iT, uint32_t xPkcByteLength, uint32_t yPkcByteLength)
 Calculates exact division with odd divisor. More...
 
void mcuxClMath_ExactDivide (uint32_t iR_iX_iY_iT, uint32_t xPkcByteLength, uint32_t yPkcByteLength)
 Calculates exact division (supporting even divisor). More...
 

Detailed Description

Defines all functions of mcuxClMath.

Macro Definition Documentation

◆ MCUXCLMATH_SHIFTMODULUS

#define MCUXCLMATH_SHIFTMODULUS (   iNShifted,
  iN 
)

Helper macro for mcuxClMath_ShiftModulus.

◆ MCUXCLMATH_FP_SHIFTMODULUS

#define MCUXCLMATH_FP_SHIFTMODULUS (   iNShifted,
  iN 
)

Helper macro for mcuxClMath_ShiftModulus with flow protection.

◆ MCUXCLMATH_NDASH

#define MCUXCLMATH_NDASH (   iN,
  iT 
)

Helper macro for mcuxClMath_NDash.

◆ MCUXCLMATH_FP_NDASH

#define MCUXCLMATH_FP_NDASH (   iN,
  iT 
)

Helper macro for mcuxClMath_NDash with flow protection.

◆ MCUXCLMATH_QDASH

#define MCUXCLMATH_QDASH (   iQDash,
  iNShifted,
  iN,
  iT,
  len 
)

Helper macro for mcuxClMath_QDash.

◆ MCUXCLMATH_FP_QDASH

#define MCUXCLMATH_FP_QDASH (   iQDash,
  iNShifted,
  iN,
  iT,
  len 
)

Helper macro for mcuxClMath_QDash with flow protection.

◆ MCUXCLMATH_QSQUARED

#define MCUXCLMATH_QSQUARED (   iQSqr,
  iNShifted,
  iN,
  iT 
)

Helper macro for mcuxClMath_QSquared.

◆ MCUXCLMATH_FP_QSQUARED

#define MCUXCLMATH_FP_QSQUARED (   iQSqr,
  iNShifted,
  iN,
  iT 
)

Helper macro for mcuxClMath_QSquared with flow protection.

◆ MCUXCLMATH_MODINV

#define MCUXCLMATH_MODINV (   iR,
  iX,
  iN,
  iT 
)

Helper macro for mcuxClMath_ModInv.

◆ MCUXCLMATH_FP_MODINV

#define MCUXCLMATH_FP_MODINV (   iR,
  iX,
  iN,
  iT 
)

Helper macro for mcuxClMath_ModInv with flow protection.

◆ MCUXCLMATH_REDUCEMODEVEN

#define MCUXCLMATH_REDUCEMODEVEN (   iR,
  iX,
  iN,
  iT0,
  iT1,
  iT2,
  iT3 
)

Helper macro for mcuxClMath_ReduceModEven.

◆ MCUXCLMATH_FP_REDUCEMODEVEN

#define MCUXCLMATH_FP_REDUCEMODEVEN (   iR,
  iX,
  iN,
  iT0,
  iT1,
  iT2,
  iT3 
)

Helper macro for mcuxClMath_ReduceModEven with flow protection.

◆ MCUXCLMATH_MODEXP_SQRMULTL2R

#define MCUXCLMATH_MODEXP_SQRMULTL2R (   pExp,
  byteLenExp,
  iR,
  iX,
  iN,
  iT 
)

Helper macro for mcuxClMath_ModExp_SqrMultL2R.

◆ MCUXCLMATH_FP_MODEXP_SQRMULTL2R

#define MCUXCLMATH_FP_MODEXP_SQRMULTL2R (   pExp,
  byteLenExp,
  iR,
  iX,
  iN,
  iT 
)

Helper macro for mcuxClMath_ModExp_SqrMultL2R with flow protection.

◆ MCUXCLMATH_SECMODEXP

#define MCUXCLMATH_SECMODEXP (   session,
  pExp,
  pExpTemp,
  byteLenExp,
  iR,
  iX,
  iN,
  iTE,
  iT0,
  iT1,
  iT2,
  iT3 
)

Helper macro for mcuxClMath_SecModExp.

◆ MCUXCLMATH_SECMODEXP_WITHOUT_RERANDOMIZATION

#define MCUXCLMATH_SECMODEXP_WITHOUT_RERANDOMIZATION (   session,
  pExp,
  pExpTemp,
  byteLenExp,
  iR,
  iX,
  iN,
  iTE,
  iT0,
  iT1,
  iT2,
  iT3 
)

Helper macro for mcuxClMath_SecModExp with disabled operand re-randomization.

TODO CLNS-7824: analyze how to use the SecModExp in RsaKg MillerRabinTest, and remove secOption to always re-randomize

◆ MCUXCLMATH_EXACTDIVIDEODD

#define MCUXCLMATH_EXACTDIVIDEODD (   iR,
  iX,
  iN,
  iT,
  xPkcByteLen,
  yPkcByteLen 
)

Helper macro for mcuxClMath_ExactDivideOdd.

◆ MCUXCLMATH_FP_EXACTDIVIDEODD

#define MCUXCLMATH_FP_EXACTDIVIDEODD (   iR,
  iX,
  iN,
  iT,
  xPkcByteLen,
  yPkcByteLen 
)

Helper macro for mcuxClMath_ExactDivideOdd with flow protection.

◆ MCUXCLMATH_EXACTDIVIDE

#define MCUXCLMATH_EXACTDIVIDE (   iR,
  iX,
  iN,
  iT,
  xPkcByteLen,
  yPkcByteLen 
)

Helper macro for mcuxClMath_ExactDivide.

◆ MCUXCLMATH_FP_EXACTDIVIDE

#define MCUXCLMATH_FP_EXACTDIVIDE (   iR,
  iX,
  iN,
  iT,
  xPkcByteLen,
  yPkcByteLen 
)

Helper macro for mcuxClMath_ExactDivide with flow protection.

Function Documentation

◆ mcuxClMath_InitLocalUptrt()

void mcuxClMath_InitLocalUptrt ( uint32_t  i3_i2_i1_i0,
uint32_t  i7_i6_i5_i4,
uint16_t *  localPtrUptrt,
uint8_t  noOfIndices,
const uint16_t **  oldPtrUptrt 
)

Initializes and uses the new UPTRT and returns the address of original UPTRT.

This function copies up to 8 offsets of PKC operands from current UPTRT to the new UPTRT, sets PKC to use the new UPTRT, and returns the address of original UPTRT.

Parameters
[in]i3_i2_i1_i0the first 4 indices of offsets to be copied
[in]i7_i6_i5_i4the second 4 indices of offsets to be copied
[in,out]localPtrUptrtaddress of the new UPTRT to be filled
[in]noOfIndicesnumber of offsets to be copied from original UPTRT to new UPTRT
[out]oldPtrUptrtpointer to where receives the original UPTRT address
Parameter properties
i3_i2_i1_i0
i0 (bits 0~7): originalUptrt[i0] will be copied to localPtrUptrt[0], if noOfIndices >= 1.
i1 (bits 8~15): originalUptrt[i1] will be copied to localPtrUptrt[1], if noOfIndices >= 2.
i2 (bits 16~23): originalUptrt[i2] will be copied to localPtrUptrt[2], if noOfIndices >= 3.
i3 (bits 24~31): originalUptrt[i3] will be copied to localPtrUptrt[3], if noOfIndices >= 4.
i7_i6_i5_i4
i4 (bits 0~7): originalUptrt[i4] will be copied to localPtrUptrt[4], if noOfIndices >= 5.
i5 (bits 8~15): originalUptrt[i5] will be copied to localPtrUptrt[5], if noOfIndices >= 6.
i6 (bits 16~23): originalUptrt[i6] will be copied to localPtrUptrt[6], if noOfIndices >= 7.
i7 (bits 24~31): originalUptrt[i7] will be copied to localPtrUptrt[7], if noOfIndices >= 8.
localPtrUptrt
This address shall be 2-byte aligned.
Caller shall allocate at least noOfIndices 2-byte entries in this table.
PKC properties
UPTRT
This function will retrieve the original UPTRT address and return it to caller via oldPtrUptrt.
This function will overwrite this address by localPtrUptrt.
PS1 lengths
Unused.
PS2 lengths
Unused.
ACTIV/GOANY
This function shall not be called during a running FUP program (i.e., GOANY bit is set). Caller shall call mcuxClPkc_WaitForReady before calling this function, if a FUP program has been called.

◆ mcuxClMath_LeadingZeros()

void mcuxClMath_LeadingZeros ( uint8_t  iX,
uint32_t *  pNumLeadingZeros 
)

Counts number of leading zero bits of a PKC operand.

This function counts the number of leading zero bits of a PKC operand at offset UPTRT[iX] and of size PS1 OPLEN.

Parameters
[in]iXindex of PKC operand
[out]pNumLeadingZerospointer to where the number of leading zero bits will be stored
Parameter properties
iX
index of X (PKC operand), size = operandSize.
The offset (UPTRT[iX]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PKC properties
PS1 lengths
PS1 OPLEN defines operandSize and shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
Unused.
ACTIV/GOANY
This function will not use PKC, and assumes PKC will not modify the operand iX simultaneously.

◆ mcuxClMath_TrailingZeros()

uint32_t mcuxClMath_TrailingZeros ( uint8_t  iX)

Counts number of trailing zero bits of a PKC operand.

This function counts the number of trailing zero bits of a PKC operand at offset UPTRT[iX] and of size PS1 OPLEN.

Parameters
[in]iXindex of PKC operand
Parameter properties
iX
index of X (PKC operand), size = operandSize.
The offset (UPTRT[iX]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PKC properties
PS1 lengths
PS1 OPLEN defines operandSize and shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
Unused.
ACTIV/GOANY
This function will not use PKC, and assumes PKC will not modify the operand iX simultaneously.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
#numTrailingZeroesNumber of trailing zeroes

◆ mcuxClMath_ShiftModulus()

void mcuxClMath_ShiftModulus ( uint16_t  iNShifted_iN)

Prepares shifted modulus.

This function left shifts modulus (PKC operand iN) until there is no leading zero and stores the result in PKC operand iNShifted.

Parameters
[in]iNShifted_iNindices of PKC operands
Parameter properties
iNShifted_iN
iN (bits 0~7): index of modulus (PKC operand), size = operandSize.
The modulus shall be non-zero.
The offset (UPTRT[iN]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
iNShifted (bits 8~15): index of shifted modulus (PKC operand), size = operandSize.
This function supports in-place operation, i.e., iNShifted = iN.
PKC properties
PS1 lengths
PS1 OPLEN defines operandSize and shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_NDash()

void mcuxClMath_NDash ( uint16_t  iN_iT)

Prepares modulus (calculates NDash) for PKC modular multiplication.

This function calculates NDash = (-modulus)^(-1) mod 256^(MCUXCLPKC_WORDSIZE) and stores NDash in the PKC word in front of the PKC operand of modulus (iN).

Parameters
[in]iN_iTindices of PKC operands
Parameter properties
iN_iT
iT (bits 0~7): index of temp (PKC operand).
The size of temp shall be at least (2 * MCUXCLPKC_WORDSIZE).
iN (bits 8~15): index of modulus (PKC operand).
The modulus shall be an odd number.
The result NDash will be stored in the PKC word before modulus, i.e., at the offset, (UPTRT[iN] - MCUXCLPKC_WORDSIZE).
PKC properties
PS1 lengths
Unused.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_QDash()

void mcuxClMath_QDash ( uint32_t  iQDash_iNShifted_iN_iT,
uint16_t  length 
)

Calculates QDash = Q * Q' mod n, where Q = 256^(operandSize) mod n, and Q' = 256^length mod n.

This function computes QDash which can be used to convert a PKC operand (of the size length) to its Montgomery representation (of the size operandSize).

Parameters
[in]iQDash_iNShifted_iN_iTindices of PKC operands
[in]lengthspecify Q' = 256^length mod n
Parameter properties
iQDash_iNShifted_iN_iT
iT (bits 0~7): index of temp (PKC operand).
The size of temp shall be at least (operandSize + MCUXCLPKC_WORDSIZE).
iN (bits 8~15): index of modulus (PKC operand), size = operandSize.
NDash of modulus shall be stored in the PKC word before modulus.
iNShifted (bits 16~23): index of shifted modulus (PKC operand), size = operandSize.
If there is no leading zero in the PKC operand modulus, it can be iN.
iQDash (bits 24~31): index of result QDash (PKC operand), size = operandSize.
QDash might be greater than modulus.
length
It shall be nonzero. A zero length will cause undefined behavior.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize.
PS2 lengths
Unused.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_QSquared()

void mcuxClMath_QSquared ( uint32_t  iQSqr_iNShifted_iN_iT)

Calculates QSquared = Q^2 mod n, where Q = 256^(operandSize) mod n.

This function computes QSquared which can be used to convert a PKC operand to its Montgomery representation (both are of the size operandSize).

Parameters
[in]iQSqr_iNShifted_iN_iTindices of PKC operands
Parameter properties
iQSqr_iNShifted_iN_iT
iT (bits 0~7): index of temp (PKC operand).
The size of temp shall be at least (operandSize + MCUXCLPKC_WORDSIZE).
iN (bits 8~15): index of modulus (PKC operand), size = operandSize.
NDash of modulus shall be stored in the PKC word before modulus.
iNShifted (bits 16~23): index of shifted modulus (PKC operand), size = operandSize.
If there is no leading zero in the PKC operand modulus, it can be iN.
iQSqr (bits 24~31): index of result QSquared (PKC operand), size = operandSize.
QSquared might be greater than modulus.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize and shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
Unused.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_ModInv()

void mcuxClMath_ModInv ( uint32_t  iR_iX_iN_iT)

Calculates modular inversion, with odd modulus.

This function calculates modular inversion, result = X^(-1) mod n.

Parameters
[in]iR_iX_iN_iTindices of PKC operands
Parameter properties
iR_iX_iN_iT
iT (bits 0~7): index of temp (PKC operand).
Its size shall be at least (operandSize + MCUXCLPKC_WORDSIZE).
The offset (UPTRT[iT]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
iN (bits 8~15): index of modulus (PKC operand), size = operandSize.
NDash of modulus shall be stored in the PKC word before modulus.
iX (bits 16~23): index of X (PKC operand), size = operandSize.
X will be destroyed by this function.
X and the modulus shall be coprime, otherwise the result will be incorrect.
iR (bits 24~31): index of result (PKC operand).
Its size shall be at least (operandSize + MCUXCLPKC_WORDSIZE).
The offset (UPTRT[iR]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
The result fits in operandSize, but might be greater than modulus.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_ReduceModEven()

void mcuxClMath_ReduceModEven ( uint32_t  iR_iX_iN_iT0,
uint32_t  iT1_iT2_iT3 
)

Calculates modular reduction with even modulus.

This function calculates modular reduction result = X mod n, where the modulus n is even.

Parameters
[in]iR_iX_iN_iT0indices of PKC operands
[in]iT1_iT2_iT3indices of PKC operands
Parameter properties
iR_iX_iN_iT0
iT0 (bits 0~7): index of temp0 (PKC operand).
Its size shall be at least (lenN + MCUXCLPKC_WORDSIZE).
The operand of modulus can be used as temp0 (i.e., iT0 = iN), but the modulus will be destroyed.
iN (bits 8~15): index of modulus (PKC operand), size = lenN.
The offset (UPTRT[iN]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
iX (bits 16~23): index of X (PKC operand).
Its size shall be at least (lenX + MCUXCLPKC_WORDSIZE).
iR (bits 24~31): index of result (PKC operand).
Its size shall be at least (lenN + MCUXCLPKC_WORDSIZE).
iT1_iT2_iT3
iT3 (bits 0~7): index of temp3 (PKC operand).
Its size shall be at least (lenN + MCUXCLPKC_WORDSIZE).
iT2 (bits 8~15): index of temp2 (PKC operand).
Its size shall be at least lenN.
iT1 (bits 16~23): index of temp1 (PKC operand).
Its size shall be at least lenN.
The operand of result can be used as temp1 (i.e., iT1 = iR). TODO: always use R (any reason not using R?)
PKC properties
PS1 lengths
PS1 OPLEN defines lenN (length of modulus n), and MCLEN defines lenX (length of X).
Both OPLEN and MCLEN shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_ModExp_SqrMultL2R()

void mcuxClMath_ModExp_SqrMultL2R ( const uint8_t *  pExp,
uint32_t  expByteLength,
uint32_t  iR_iX_iN_iT 
)

Calculates modular exponentiation.

This function calculates modular exponentiation with left-to-right binary square-and-multiply algorithm.

Parameters
[in]pExppointer to exponent
[in]expByteLengthbyte length of exponent
[in]iR_iX_iN_iTindices of PKC operands
Parameter properties
pExp
the exponent is a big-endian octet string and shall be non-zero.
iR_iX_iN_iT
iT (bits 0~7): index of temp operand (PKC operand).
Its size shall be at least (lenN + MCUXCLPKC_WORDSIZE).
iN (bits 8~15): index of modulus (PKC operand), size = operandSize.
NDash of modulus shall be stored in the PKC word before modulus.
iX (bits 16~23): index of base number (PKC operand), size = operandSize. iR (bits 24~31): index of result (PKC operand).
Its size shall be at least (lenN + MCUXCLPKC_WORDSIZE).
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize.
PS2 lengths
Unused.
ACTIV/GOANY
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_SecModExp()

mcuxClMath_Status_t mcuxClMath_SecModExp ( mcuxClSession_Handle_t  session,
const uint8_t *  pExp,
uint32_t *  pExpTemp,
uint32_t  expByteLength,
uint32_t  iT3_iX_iT2_iT1,
uint32_t  iN_iTE_iT0_iR,
uint32_t  secOption 
)

Securely calculates modular exponentiation.

This function calculates modular exponentiation in a secure manner. It randomizes the computation by Euclidean splitting: exponent = b * q + r, where b is a 64-bit odd random number (with both MSbit and LSbit set), and r = exponent % b. The exponentiation is calculated by two steps: (1) m0 = m^q mod n; and (2) result = m0^b * m^r mod n. In addition, base operands are re-randomized, by adding random multiples of the modulus to them before performing modular multiplications.

Parameters
[in]pSessionhandle for the current CL session.
[in]pExppointer to exponent
[in]pExpTemppointer to temporary buffer
[in]expByteLengthbyte length of exponent
[in]iT3_iX_iT2_iT1indices of PKC operands
[in]iN_iTE_iT0_iRindices of PKC operands
[in]secOptionoption to disable the operand re-randomization
Parameter properties
session:
The session pointed to by pSession has to be initialized prior to a call to this function.
pExp
the exponent is a big-endian octet string and shall be non-zero.
pExpTemp
the temporary buffer can be in either CPU or PKC workarea.
It shall be CPU word aligned, and its length shall be a multiple of CPU word and greater than expByteLength.
It can share the space with exponent (i.e., pExpTemp = pExp), but the exponent will be overwritten.
iT3_iX_iT2_iT1
iT1 (bits 0~7): index of temp1 (PKC operand).
Its size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iT2 (bits 8~15): index of temp2 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iX (bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE).
It will be overwritten.
iT3 (bits 24~31): index of temp3 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iN_iTE_iT0_iR
iR (bits 0~7): index of result (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iT0 (bits 8~15): index of temp0 (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iTE (bits 16~23): index of temp4 (PKC operand).
The size shall be at least (6 * MCUXCLPKC_WORDSIZE).
iN (bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN).
The upper 32 bits of N shall be null, which can be obtained for instance by applying 32-bit modulus blinding, or by artificially increasing PS1 lengths and all buffer sizes by 1 PKC word.
NDash of modulus shall be stored in the PKC word before modulus.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize = MCUXCLPKC_ROUNDUP_SIZE(lenN), where lenN is the length of modulus n. As the upper 32 bits of N should be null, operandSize >= lenN + 4 bytes.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller. The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMATH_STATUS_OKfunction executed successfully
MCUXCLMATH_STATUS_ERRORerror occurred during operation
Attention
This function uses PRNG which has to be initialized prior to calling the function.

◆ mcuxClMath_ExactDivideOdd()

void mcuxClMath_ExactDivideOdd ( uint32_t  iR_iX_iY_iT,
uint32_t  xPkcByteLength,
uint32_t  yPkcByteLength 
)

Calculates exact division with odd divisor.

This function calculates exact division R = X/Y, where divisor Y is odd and dividend X shall be exactly a multiple of Y. If X is not a multiple of Y, result will be incorrect.

Parameters
[in]iR_iX_iY_iTindices of PKC operands
[in]xPkcByteLengthlength of X
[in]yPkcByteLengthlength of Y
Parameter properties
iR_iX_iY_iT
iT (bits 0~7): index of temp (PKC operand).
Its size shall be at least (3 * MCUXCLPKC_WORDSIZE).
The offset (UPTRT[iT]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
iY (bits 8~15): index of divisor Y (PKC operand), size = yPkcByteLength.
The most significant PKC word of Y shall be nonzero.
iX (bits 16~23): index of dividend X (PKC operand), size = xPkcByteLength.
X will be destroyed by this function.
CAUTION: if xPkcByteLength = MCUXCLPKC_WORDSIZE, this function will access to (read) one extra PKC word of X, i.e., X[MCUXCLPKC_WORDSIZE ~ 2*MCUXCLPKC_WORDSIZE - 1]. The value of this PKC word will not affect correctness of the result, but caller shall ensure that this PKC word is accessible by PKC.
iR (bits 24~31): index of result R (PKC operand), size = (xPkcByteLength - yPkcByteLength + MCUXCLPKC_WORDSIZE).
xPkcByteLength
It shall be a multiple of MCUXCLPKC_WORDSIZE.
yPkcByteLength
It shall be a multiple of MCUXCLPKC_WORDSIZE.
PKC properties
PS1 lengths
Unused (modified and restored in the function).
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.

◆ mcuxClMath_ExactDivide()

void mcuxClMath_ExactDivide ( uint32_t  iR_iX_iY_iT,
uint32_t  xPkcByteLength,
uint32_t  yPkcByteLength 
)

Calculates exact division (supporting even divisor).

This function calculates exact division R = X/Y, where dividend X shall be exactly a multiple of divisor Y. If X is not a multiple of Y, result will be incorrect.

This function trims trailing zero bits of Y and gets Y' = Y >> trailingZeros(Y), and X' = X >> ((trailingZeros(Y) / 8*MCUXCLPKC_WORDSIZE) * 8*MCUXCLPKC_WORDSIZE). It relies on mcuxClMath_ExactDivideOdd to calculate R' = X'/Y', and then calculates R = R' >> (trailingZeros(Y) % (8*MCUXCLPKC_WORDSIZE)).

Parameters
[in]iR_iX_iY_iTPointer table indices of parameters
[in]xPkcByteLengthlength of X
[in]yPkcByteLengthlength of Y
Parameter properties
iR_iX_iY_iT
iT (bits 0~7): index of temp (PKC operand).
Its size shall be at least (3 * MCUXCLPKC_WORDSIZE).
iY (bits 8~15): index of divisor Y (PKC operand), size = yPkcByteLength.
The most significant PKC word of Y shall be nonzero.
The offset (UPTRT[iY]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
iX (bits 16~23): index of dividend X (PKC operand), size = xPkcByteLength.
X will be destroyed by this function.
CAUTION: if the length of trimmed X' is MCUXCLPKC_WORDSIZE, this function will access to (read) one extra PKC word of X, i.e., X[xPkcByteLength ~ xPkcByteLength + MCUXCLPKC_WORDSIZE - 1]. The value of this PKC word will not affect correctness of the result, but caller shall ensure that this PKC word is accessible by PKC. If caller cannot guarantee the length of trimmed X' greater than MCUXCLPKC_WORDSIZE, X shall be stored in buffer of the size, xPkcByteLength + MCUXCLPKC_WORDSIZE.
iR (bits 24~31): index of result R (PKC operand). Its buffer size shall be at least (xPkcByteLength - yPkcByteLength + 2*MCUXCLPKC_WORDSIZE). The result fits in size = (xPkcByteLength - yPkcByteLength + MCUXCLPKC_WORDSIZE).
xPkcByteLength
It shall be a multiple of MCUXCLPKC_WORDSIZE.
yPkcByteLength
It shall be a multiple of MCUXCLPKC_WORDSIZE.
PKC properties
PS1 lengths
Unused (modified and restored in the function).
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
mcuxClPkc_WaitForReady will be called before returning to caller.
The PKC calculation might be still on-going, call mcuxClPkc_WaitForFinish before CPU accesses to the result.