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

 MCUX_CSSL_FP_PROTECTED_TYPE (void) mcuxClMath_InitLocalUptrt(uint32_t i3_i2_i1_i0
 Initializes and uses the new UPTRT and returns the address of original UPTRT. More...
 
 MCUX_CSSL_FP_PROTECTED_TYPE (uint32_t) mcuxClMath_TrailingZeros(uint8_t iX)
 Counts number of trailing zero bits of a PKC operand. More...
 

Variables

uint32_t i7_i6_i5_i4
 
uint32_t uint16_t * localPtrUptrt
 
uint32_t uint16_t uint8_t noOfIndices
 
uint32_t uint16_t uint8_t const uint16_t ** oldPtrUptrt
 
uint32_t * pNumLeadingZeros
 
uint16_t length
 
uint32_t iT1_iT2_iT3
 
uint32_t expByteLength
 
uint32_t uint32_t iR_iX_iN_iT
 
const uint8_t * pExp
 
const uint8_t uint32_t * pExpTemp
 
const uint8_t uint32_t uint32_t uint32_t iT3_iX_iT2_iT1
 
const uint8_t uint32_t uint32_t uint32_t uint32_t iN_iTE_iT0_iR
 
const uint8_t uint32_t uint32_t uint32_t uint32_t uint32_t secOption
 
uint32_t xPkcByteLength
 
uint32_t uint32_t yPkcByteLength
 

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

◆ MCUX_CSSL_FP_PROTECTED_TYPE() [1/2]

MCUX_CSSL_FP_PROTECTED_TYPE ( void  )

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

Wait until PKC is ready to accept new calculation.

Wait until PKC finishes calculations.

Start a PKC FUP program calculation.

Start a PKC calculation with one constant parameter.

Start a PKC calculation.

Initialize UPTR table.

deinitialize PKC hardware

Calculates exact division (supporting even divisor).

Calculates exact division with odd divisor.

Calculates modular exponentiation.

Calculates modular reduction with even modulus.

Calculates modular inversion, with odd modulus.

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

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

Prepares modulus (calculates NDash) for PKC modular multiplication.

Prepares shifted modulus.

Counts number of leading zero bits of a PKC operand.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

This function deinitializes PKC hardware, and optionally restores PKC configuration (except STOP bit).

Parameters
[in]pStatepointer to PKC state backup structure. If it's not a NULL pointer, PKC state will be restored from this structure.

This function initializes elements in UPTR table. UPTR table contains the address (16-bit offset in PKC workarea) of each buffer (PKC operand). Each element of the table will be initialized with a 16-bit offset, associated with a buffer allocated in sequence in PKC workarea. When calling this function, there shall be no on-going and pending PKC calculations using the specified UPTR table elements.

Parameters
[out]pUPTRTpointer to the first element to be initialized in UPTR table.
[in]pBaseBufferaddress of the buffer in PKC workarea, with which the first element will be associated.
[in]bufferLengthbyte length of each buffer in PKC workarea.
[in]noOfBuffernumber of elements to be initialized.
Parameter properties
pUPTRT
this pointer shall be 2-byte aligned.
pBaseBuffer
this address shall be MCUXCLPKC_WORDSIZE aligned.
bufferLength
this length shall be a multiple of MCUXCLPKC_WORDSIZE.

This function performs one specified PKC calculation, of which the operand(s) and result are specified by the indices of UPTR table.

Parameters
[in]param_modeparam (the higher 8 bits) indicates the type of the calculation (L0 or L1) and the parameter set (PS1 or PS2).
mode (the lower 8 bits) indicates the calculation, either an L0 operation or L1 microcode.
[in]iR_iX_iY_iZindices of the operand(s) and the result in UPTR table.
Attention
The PKC calculation might be still on-going when returning to caller, call #mcuxClPkc_WaitForFinish before CPU accesses to the result.

This function performs one specified PKC calculation, of which the operand(s) and result are specified by the indices of UPTR table, and a 8-bit constant parameter is directly provided. This function can also be used to perform an L0 operation without using Z operand, e.g., OP_MUL, R = X0 * Y.

Parameters
[in]param_modeparam (the higher 8 bits) indicates the type of the calculation (always L0) and the parameter set (PS1 or PS2).
mode (the lower 8 bits) indicates the calculation, an L0 operation.
[in]iR_iX_iY_Cindices of the operand(s) and the result in UPTR table, and a direct 8-bit constant.
Attention
The PKC calculation might be still on-going when returning to caller, call #mcuxClPkc_WaitForFinish before CPU accesses to the result.

This function triggers PKC to start the calculation of a FUP program.

Parameters
[in]pUPTR2-byte aligned address of the FUP program.
[in]uLengthlength (number of calculation) of the FUP program.
Attention
The PKC calculation might be still on-going when returning to caller, call #mcuxClPkc_WaitForFinish before CPU accesses to the result.

This function waits until PKC finishes on-going and pending calculations (if there is any). When returning to caller, PKC is in idle state, and result in PKC workarea is ready.

This function waits until PKC is ready to accept next calculation (i.e., no pending calculation).

◆ MCUX_CSSL_FP_PROTECTED_TYPE() [2/2]

MCUX_CSSL_FP_PROTECTED_TYPE ( uint32_t  )

Counts number of trailing zero bits of a PKC operand.

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.

Securely calculates modular exponentiation.

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

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_ERRORCODE_OKfunction executed successfully
MCUXCLMATH_ERRORCODE_ERRORerror occurred during operation
Attention
This function uses PRNG which has to be initialized prior to calling the function.