CAAM PKHA driver

Overview

This section describes the programming interface of the CAAM PKHA driver.

Data Structures
struct	caam_pkha_ecc_point_t
	PKHA ECC point structure. More...

Enumerations
enum	caam_pkha_timing_t {   kCAAM_PKHA_NoTimingEqualized = 0U,   kCAAM_PKHA_TimingEqualized = 1U }
	Use of timing equalized version of a PKHA function. More...
enum	caam_pkha_f2m_t {   kCAAM_PKHA_IntegerArith = 0U,   kCAAM_PKHA_F2mArith = 1U }
	Integer vs binary polynomial arithmetic selection. More...
enum	caam_pkha_montgomery_form_t {   kCAAM_PKHA_NormalValue = 0U,   kCAAM_PKHA_MontgomeryFormat = 1U }
	Montgomery or normal PKHA input format. More...

Functions
status_t	CAAM_PKHA_NormalToMontgomery (CAAM_Type *base, caam_handle_t *handle, const uint8_t *N, size_t sizeN, uint8_t *A, size_t *sizeA, uint8_t *B, size_t *sizeB, uint8_t *R2, size_t *sizeR2, caam_pkha_timing_t equalTime, caam_pkha_f2m_t arithType)
	Converts from integer to Montgomery format. More...
status_t	CAAM_PKHA_MontgomeryToNormal (CAAM_Type *base, caam_handle_t *handle, const uint8_t *N, size_t sizeN, uint8_t *A, size_t *sizeA, uint8_t *B, size_t *sizeB, caam_pkha_timing_t equalTime, caam_pkha_f2m_t arithType)
	Converts from Montgomery format to int. More...
status_t	CAAM_PKHA_ModAdd (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *B, size_t sizeB, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType)
	Performs modular addition - (A + B) mod N. More...
status_t	CAAM_PKHA_ModSub1 (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *B, size_t sizeB, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize)
	Performs modular subtraction - (A - B) mod N. More...
status_t	CAAM_PKHA_ModSub2 (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *B, size_t sizeB, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize)
	Performs modular subtraction - (B - A) mod N. More...
status_t	CAAM_PKHA_ModMul (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *B, size_t sizeB, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType, caam_pkha_montgomery_form_t montIn, caam_pkha_montgomery_form_t montOut, caam_pkha_timing_t equalTime)
	Performs modular multiplication - (A x B) mod N. More...
status_t	CAAM_PKHA_ModExp (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *N, size_t sizeN, const uint8_t *E, size_t sizeE, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType, caam_pkha_montgomery_form_t montIn, caam_pkha_timing_t equalTime)
	Performs modular exponentiation - (A^E) mod N. More...
status_t	CAAM_PKHA_ModRed (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType)
	Performs modular reduction - (A) mod N. More...
status_t	CAAM_PKHA_ModInv (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType)
	Performs modular inversion - (A^-1) mod N. More...
status_t	CAAM_PKHA_ModR2 (CAAM_Type *base, caam_handle_t *handle, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType)
	Computes integer Montgomery factor R^2 mod N. More...
status_t	CAAM_PKHA_ModGcd (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *N, size_t sizeN, uint8_t *result, size_t *resultSize, caam_pkha_f2m_t arithType)
	Calculates the greatest common divisor - GCD (A, N). More...
status_t	CAAM_PKHA_PrimalityTest (CAAM_Type *base, caam_handle_t *handle, const uint8_t *A, size_t sizeA, const uint8_t *B, size_t sizeB, const uint8_t *N, size_t sizeN, bool *res)
	Executes Miller-Rabin primality test. More...
status_t	CAAM_PKHA_ECC_PointAdd (CAAM_Type *base, caam_handle_t *handle, const caam_pkha_ecc_point_t *A, const caam_pkha_ecc_point_t *B, const uint8_t *N, const uint8_t *R2modN, const uint8_t *aCurveParam, const uint8_t *bCurveParam, size_t size, caam_pkha_f2m_t arithType, caam_pkha_ecc_point_t *result)
	Adds elliptic curve points - A + B. More...
status_t	CAAM_PKHA_ECC_PointDouble (CAAM_Type *base, caam_handle_t *handle, const caam_pkha_ecc_point_t *B, const uint8_t *N, const uint8_t *aCurveParam, const uint8_t *bCurveParam, size_t size, caam_pkha_f2m_t arithType, caam_pkha_ecc_point_t *result)
	Doubles elliptic curve points - B + B. More...
status_t	CAAM_PKHA_ECC_PointMul (CAAM_Type *base, caam_handle_t *handle, const caam_pkha_ecc_point_t *A, const uint8_t *E, size_t sizeE, const uint8_t *N, const uint8_t *R2modN, const uint8_t *aCurveParam, const uint8_t *bCurveParam, size_t size, caam_pkha_timing_t equalTime, caam_pkha_f2m_t arithType, caam_pkha_ecc_point_t *result)
	Multiplies an elliptic curve point by a scalar - E x (A0, A1). More...

---

Data Structure Documentation

struct caam_pkha_ecc_point_t

Data Fields
uint8_t *	X
	X coordinate (affine)
uint8_t *	Y
	Y coordinate (affine)

Enumeration Type Documentation

enum caam_pkha_timing_t

Enumerator
kCAAM_PKHA_NoTimingEqualized	Normal version of a PKHA operation.
kCAAM_PKHA_TimingEqualized	Timing-equalized version of a PKHA operation.

enum caam_pkha_f2m_t

Enumerator
kCAAM_PKHA_IntegerArith	Use integer arithmetic.
kCAAM_PKHA_F2mArith	Use binary polynomial arithmetic.

enum caam_pkha_montgomery_form_t

Enumerator
kCAAM_PKHA_NormalValue	PKHA number is normal integer.
kCAAM_PKHA_MontgomeryFormat	PKHA number is in montgomery format.

Function Documentation

status_t CAAM_PKHA_NormalToMontgomery	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	A,
		size_t *	sizeA,
		uint8_t *	B,
		size_t *	sizeB,
		uint8_t *	R2,
		size_t *	sizeR2,
		caam_pkha_timing_t	equalTime,
		caam_pkha_f2m_t	arithType
	)

This function computes R2 mod N and optionally converts A or B into Montgomery format of A or B.

Parameters

	base	CAAM peripheral base address
	N	modulus
	sizeN	size of N in bytes
[in,out]	A	The first input in non-Montgomery format. Output Montgomery format of the first input.
[in,out]	sizeA	pointer to size variable. On input it holds size of input A in bytes. On output it holds size of Montgomery format of A in bytes.
[in,out]	B	Second input in non-Montgomery format. Output Montgomery format of the second input.
[in,out]	sizeB	pointer to size variable. On input it holds size of input B in bytes. On output it holds size of Montgomery format of B in bytes.
[out]	R2	Output Montgomery factor R2 mod N.
[out]	sizeR2	pointer to size variable. On output it holds size of Montgomery factor R2 mod N in bytes.
	equalTime	Run the function time equalized or no timing equalization.
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_MontgomeryToNormal	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	A,
		size_t *	sizeA,
		uint8_t *	B,
		size_t *	sizeB,
		caam_pkha_timing_t	equalTime,
		caam_pkha_f2m_t	arithType
	)

This function converts Montgomery format of A or B into int A or B.

Parameters

	base	CAAM peripheral base address
	N	modulus.
	sizeN	size of N modulus in bytes.
[in,out]	A	Input first number in Montgomery format. Output is non-Montgomery format.
[in,out]	sizeA	pointer to size variable. On input it holds size of the input A in bytes. On output it holds size of non-Montgomery A in bytes.
[in,out]	B	Input first number in Montgomery format. Output is non-Montgomery format.
[in,out]	sizeB	pointer to size variable. On input it holds size of the input B in bytes. On output it holds size of non-Montgomery B in bytes.
	equalTime	Run the function time equalized or no timing equalization.
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_ModAdd	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	B,
		size_t	sizeB,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType
	)

This function performs modular addition of (A + B) mod N, with either integer or binary polynomial (F2m) inputs. In the F2m form, this function is equivalent to a bitwise XOR and it is functionally the same as subtraction.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	B	second addend (integer or binary polynomial)
	sizeB	Size of B in bytes
	N	modulus.
	sizeN	Size of N in bytes.
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_ModSub1	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	B,
		size_t	sizeB,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize
	)

This function performs modular subtraction of (A - B) mod N with integer inputs.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	B	second addend (integer or binary polynomial)
	sizeB	Size of B in bytes
	N	modulus
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes

Returns

Operation status.

status_t CAAM_PKHA_ModSub2	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	B,
		size_t	sizeB,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize
	)

This function performs modular subtraction of (B - A) mod N, with integer inputs.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	B	second addend (integer or binary polynomial)
	sizeB	Size of B in bytes
	N	modulus
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes

Returns

Operation status.

status_t CAAM_PKHA_ModMul	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	B,
		size_t	sizeB,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType,
		caam_pkha_montgomery_form_t	montIn,
		caam_pkha_montgomery_form_t	montOut,
		caam_pkha_timing_t	equalTime
	)

This function performs modular multiplication with either integer or binary polynomial (F2m) inputs. It can optionally specify whether inputs and/or outputs will be in Montgomery form or not.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	B	second addend (integer or binary polynomial)
	sizeB	Size of B in bytes
	N	modulus.
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)
	montIn	Format of inputs
	montOut	Format of output
	equalTime	Run the function time equalized or no timing equalization. This argument is ignored for F2m modular multiplication.

Returns

Operation status.

status_t CAAM_PKHA_ModExp	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	N,
		size_t	sizeN,
		const uint8_t *	E,
		size_t	sizeE,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType,
		caam_pkha_montgomery_form_t	montIn,
		caam_pkha_timing_t	equalTime
	)

This function performs modular exponentiation with either integer or binary polynomial (F2m) inputs.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	N	modulus
	sizeN	Size of N in bytes
	E	exponent
	sizeE	Size of E in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	montIn	Format of A input (normal or Montgomery)
	arithType	Type of arithmetic to perform (integer or F2m)
	equalTime	Run the function time equalized or no timing equalization.

Returns

Operation status.

status_t CAAM_PKHA_ModRed	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType
	)

This function performs modular reduction with either integer or binary polynomial (F2m) inputs.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	N	modulus
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_ModInv	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType
	)

This function performs modular inversion with either integer or binary polynomial (F2m) inputs.

Parameters

	base	CAAM peripheral base address
	A	first addend (integer or binary polynomial)
	sizeA	Size of A in bytes
	N	modulus
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_ModR2	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType
	)

This function computes a constant to assist in converting operands into the Montgomery residue system representation.

Parameters

	base	CAAM peripheral base address
	N	modulus
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_ModGcd	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	N,
		size_t	sizeN,
		uint8_t *	result,
		size_t *	resultSize,
		caam_pkha_f2m_t	arithType
	)

This function calculates the greatest common divisor of two inputs with either integer or binary polynomial (F2m) inputs.

Parameters

	base	CAAM peripheral base address
	A	first value (must be smaller than or equal to N)
	sizeA	Size of A in bytes
	N	second value (must be non-zero)
	sizeN	Size of N in bytes
[out]	result	Output array to store result of operation
[out]	resultSize	Output size of operation in bytes
	arithType	Type of arithmetic to perform (integer or F2m)

Returns

Operation status.

status_t CAAM_PKHA_PrimalityTest	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	A,
		size_t	sizeA,
		const uint8_t *	B,
		size_t	sizeB,
		const uint8_t *	N,
		size_t	sizeN,
		bool *	res
	)

This function calculates whether or not a candidate prime number is likely to be a prime.

Parameters

	base	CAAM peripheral base address
	A	initial random seed
	sizeA	Size of A in bytes
	B	number of trial runs
	sizeB	Size of B in bytes
	N	candidate prime integer
	sizeN	Size of N in bytes
[out]	res	True if the value is likely prime or false otherwise

Returns

Operation status.

status_t CAAM_PKHA_ECC_PointAdd	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const caam_pkha_ecc_point_t *	A,
		const caam_pkha_ecc_point_t *	B,
		const uint8_t *	N,
		const uint8_t *	R2modN,
		const uint8_t *	aCurveParam,
		const uint8_t *	bCurveParam,
		size_t	size,
		caam_pkha_f2m_t	arithType,
		caam_pkha_ecc_point_t *	result
	)

This function performs ECC point addition over a prime field (Fp) or binary field (F2m) using affine coordinates.

Parameters

	base	CAAM peripheral base address
	A	Left-hand point
	B	Right-hand point
	N	Prime modulus of the field
	R2modN	NULL (the function computes R2modN internally) or pointer to pre-computed R2modN (obtained from CAAM_PKHA_ModR2() function).
	aCurveParam	A parameter from curve equation
	bCurveParam	B parameter from curve equation (constant)
	size	Size in bytes of curve points and parameters
	arithType	Type of arithmetic to perform (integer or F2m)
[out]	result	Result point

Returns

Operation status.

status_t CAAM_PKHA_ECC_PointDouble	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const caam_pkha_ecc_point_t *	B,
		const uint8_t *	N,
		const uint8_t *	aCurveParam,
		const uint8_t *	bCurveParam,
		size_t	size,
		caam_pkha_f2m_t	arithType,
		caam_pkha_ecc_point_t *	result
	)

This function performs ECC point doubling over a prime field (Fp) or binary field (F2m) using affine coordinates.

Parameters

	base	CAAM peripheral base address
	B	Point to double
	N	Prime modulus of the field
	aCurveParam	A parameter from curve equation
	bCurveParam	B parameter from curve equation (constant)
	size	Size in bytes of curve points and parameters
	arithType	Type of arithmetic to perform (integer or F2m)
[out]	result	Result point

Returns

Operation status.

status_t CAAM_PKHA_ECC_PointMul	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const caam_pkha_ecc_point_t *	A,
		const uint8_t *	E,
		size_t	sizeE,
		const uint8_t *	N,
		const uint8_t *	R2modN,
		const uint8_t *	aCurveParam,
		const uint8_t *	bCurveParam,
		size_t	size,
		caam_pkha_timing_t	equalTime,
		caam_pkha_f2m_t	arithType,
		caam_pkha_ecc_point_t *	result
	)

This function performs ECC point multiplication to multiply an ECC point by a scalar integer multiplier over a prime field (Fp) or a binary field (F2m).

Parameters

	base	CAAM peripheral base address
	A	Point as multiplicand
	E	Scalar multiple
	sizeE	The size of E, in bytes
	N	Modulus, a prime number for the Fp field or Irreducible polynomial for F2m field.
	R2modN	NULL (the function computes R2modN internally) or pointer to pre-computed R2modN (obtained from CAAM_PKHA_ModR2() function).
	aCurveParam	A parameter from curve equation
	bCurveParam	B parameter from curve equation (C parameter for operation over F2m).
	size	Size in bytes of curve points and parameters
	equalTime	Run the function time equalized or no timing equalization.
	arithType	Type of arithmetic to perform (integer or F2m)
[out]	result	Result point

Returns

Operation status.