Defines all functions of mcuxClMath. More...

Macros
#define	MCUXCLMATH_SHIFTMODULUS(iNShifted, iN)
	Helper macro for mcuxClMath_ShiftModulus.

#define	MCUXCLMATH_FP_SHIFTMODULUS(iNShifted, iN)
	Helper macro for mcuxClMath_ShiftModulus with flow protection.

#define	MCUXCLMATH_NDASH(iN, iT)
	Helper macro for mcuxClMath_NDash.

#define	MCUXCLMATH_FP_NDASH(iN, iT)
	Helper macro for mcuxClMath_NDash with flow protection.

#define	MCUXCLMATH_QDASH(iQDash, iNShifted, iN, iT, len)
	Helper macro for mcuxClMath_QDash.

#define	MCUXCLMATH_FP_QDASH(iQDash, iNShifted, iN, iT, len)
	Helper macro for mcuxClMath_QDash with flow protection.

#define	MCUXCLMATH_QSQUARED(iQSqr, iNShifted, iN, iT)
	Helper macro for mcuxClMath_QSquared.

#define	MCUXCLMATH_FP_QSQUARED(iQSqr, iNShifted, iN, iT)
	Helper macro for mcuxClMath_QSquared with flow protection.

#define	MCUXCLMATH_MODINV(iR, iX, iN, iT)
	Helper macro for mcuxClMath_ModInv.

#define	MCUXCLMATH_FP_MODINV(iR, iX, iN, iT)
	Helper macro for mcuxClMath_ModInv with flow protection.

#define	MCUXCLMATH_REDUCEMODEVEN(iR, iX, iN, iT0, iT1, iT2, iT3)
	Helper macro for mcuxClMath_ReduceModEven.

#define	MCUXCLMATH_FP_REDUCEMODEVEN(iR, iX, iN, iT0, iT1, iT2, iT3)
	Helper macro for mcuxClMath_ReduceModEven with flow protection.

#define	MCUXCLMATH_MODEXP_SQRMULTL2R(pExp, byteLenExp, iR, iX, iN, iT)
	Helper macro for mcuxClMath_ModExp_SqrMultL2R.

#define	MCUXCLMATH_FP_MODEXP_SQRMULTL2R(pExp, byteLenExp, iR, iX, iN, iT)
	Helper macro for mcuxClMath_ModExp_SqrMultL2R with flow protection.

#define	MCUXCLMATH_SECMODEXP(session, pExp, pExpTemp, byteLenExp, iR, iX, iN, iTE, iT0, iT1, iT2, iT3)
	Helper macro for mcuxClMath_SecModExp.

#define	MCUXCLMATH_EXACTDIVIDEODD(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
	Helper macro for mcuxClMath_ExactDivideOdd.

#define	MCUXCLMATH_FP_EXACTDIVIDEODD(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
	Helper macro for mcuxClMath_ExactDivideOdd with flow protection.

#define	MCUXCLMATH_EXACTDIVIDE(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
	Helper macro for mcuxClMath_ExactDivide.

#define	MCUXCLMATH_FP_EXACTDIVIDE(iR, iX, iN, iT, xPkcByteLen, yPkcByteLen)
	Helper macro for mcuxClMath_ExactDivide with flow protection.

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.

uint32_t	mcuxClMath_LeadingZeros (uint8_t iX)
	Counts number of leading zero bits of a PKC operand.

uint32_t	mcuxClMath_TrailingZeros (uint8_t iX)
	Counts number of trailing zero bits of a PKC operand.

void	mcuxClMath_ShiftModulus (uint16_t iNShifted_iN)
	Prepares shifted modulus.

void	mcuxClMath_NDash (uint16_t iN_iT)
	Prepares modulus (calculates NDash) for PKC modular multiplication.

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.

void	mcuxClMath_QSquared (uint32_t iQSqr_iNShifted_iN_iT)
	Calculates QSquared = Q^2 mod n, where Q = 256^(operandSize) mod n.

void	mcuxClMath_ModInv (uint32_t iR_iX_iN_iT)
	Calculates modular inversion, with odd modulus.

void	mcuxClMath_ReduceModEven (uint32_t iR_iX_iN_iT0, uint32_t iT1_iT2_iT3)
	Calculates modular reduction with even modulus.

void	mcuxClMath_ModExp_SqrMultL2R (const uint8_t *pExp, uint32_t expByteLength, uint32_t iR_iX_iN_iT)
	Calculates modular exponentiation.

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)
	Securely calculates modular exponentiation.

void	mcuxClMath_ExactDivideOdd (uint32_t iR_iX_iY_iT, uint32_t xPkcByteLength, uint32_t yPkcByteLength)
	Calculates exact division with odd divisor.

void	mcuxClMath_ExactDivide (uint32_t iR_iX_iY_iT, uint32_t xPkcByteLength, uint32_t yPkcByteLength)
	Calculates exact division (supporting even divisor).

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_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_i0	the first 4 indices of offsets to be copied
[in]	i7_i6_i5_i4	the second 4 indices of offsets to be copied
[in,out]	localPtrUptrt	address of the new UPTRT to be filled
[in]	noOfIndices	number of offsets to be copied from original UPTRT to new UPTRT
[out]	oldPtrUptrt	pointer 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()

uint32_t mcuxClMath_LeadingZeros ( uint8_t iX )

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]	iX	index of PKC operand
[out]	pNumLeadingZeros	pointer 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] iX index 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

#numTrailingZeroes Number 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_iN indices 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_iT indices 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_iT	indices of PKC operands
[in]	length	specify 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_iT indices 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_iT indices 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_iT0	indices of PKC operands
[in]	iT1_iT2_iT3	indices 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).
lenX (PS1 MCLEN) >= lenN (PS1 OPLEN).
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]	pExp	pointer to exponent
[in]	expByteLength	byte length of exponent
[in]	iR_iX_iN_iT	indices 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
	)

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]	pSession	handle for the current CL session.
[in]	pExp	pointer to exponent
[in]	pExpTemp	pointer to temporary buffer
[in]	expByteLength	byte length of exponent
[in]	iT3_iX_iT2_iT1	indices of PKC operands
[in]	iN_iTE_iT0_iR	indices of PKC operands

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_ALIGN_TO_PKC_WORDSIZE(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_ALIGN_TO_PKC_WORDSIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iT0 (bits 8~15): index of temp0 (PKC operand).
The size shall be at least max(MCUXCLPKC_ALIGN_TO_PKC_WORDSIZE(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_ALIGN_TO_PKC_WORDSIZE(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_OK	function executed successfully
MCUXCLMATH_STATUS_ERROR	error 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_iT	indices of PKC operands
[in]	xPkcByteLength	length of X
[in]	yPkcByteLength	length 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, and >= yPkcByteLength.
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_iT	Pointer table indices of parameters
[in]	xPkcByteLength	length of X
[in]	yPkcByteLength	length 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.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MCUXCLMATH_SHIFTMODULUS

◆ MCUXCLMATH_FP_SHIFTMODULUS

◆ MCUXCLMATH_NDASH

◆ MCUXCLMATH_FP_NDASH

◆ MCUXCLMATH_QDASH

◆ MCUXCLMATH_FP_QDASH

◆ MCUXCLMATH_QSQUARED

◆ MCUXCLMATH_FP_QSQUARED

◆ MCUXCLMATH_MODINV

◆ MCUXCLMATH_FP_MODINV

◆ MCUXCLMATH_REDUCEMODEVEN

◆ MCUXCLMATH_FP_REDUCEMODEVEN

◆ MCUXCLMATH_MODEXP_SQRMULTL2R

◆ MCUXCLMATH_FP_MODEXP_SQRMULTL2R

◆ MCUXCLMATH_SECMODEXP

◆ MCUXCLMATH_EXACTDIVIDEODD

◆ MCUXCLMATH_FP_EXACTDIVIDEODD

◆ MCUXCLMATH_EXACTDIVIDE

◆ MCUXCLMATH_FP_EXACTDIVIDE

Function Documentation

◆ mcuxClMath_InitLocalUptrt()

◆ mcuxClMath_LeadingZeros()

◆ mcuxClMath_TrailingZeros()

◆ mcuxClMath_ShiftModulus()

◆ mcuxClMath_NDash()

◆ mcuxClMath_QDash()

◆ mcuxClMath_QSquared()

◆ mcuxClMath_ModInv()

◆ mcuxClMath_ReduceModEven()

◆ mcuxClMath_ModExp_SqrMultL2R()

◆ mcuxClMath_SecModExp()

◆ mcuxClMath_ExactDivideOdd()

◆ mcuxClMath_ExactDivide()