[pka.h] Public Key Accelerator

Data Structures
union	PKA_EccParam224
union	PKA_EccParam256
union	PKA_EccParam384
union	PKA_EccParam512
union	PKA_EccParam521
struct	PKA_EccPoint224_
struct	PKA_EccPoint256_
struct	PKA_EccPoint384_
struct	PKA_EccPoint512_
struct	PKA_EccPoint521_

Functions
void	PKAClearPkaRam (void)
	Zeroizes PKA RAM. More...
uint32_t	PKAGetOpsStatus (void)
	Gets the PKA operation status. More...
bool	PKAArrayAllZeros (const uint8_t *array, uint32_t arrayLength)
	Checks whether and array only consists of zeros. More...
void	PKAZeroOutArray (const uint8_t *array, uint32_t arrayLength)
	Zeros-out an array. More...
uint32_t	PKABigNumModStart (const uint8_t *bigNum, uint32_t bigNumLength, const uint8_t *modulus, uint32_t modulusLength, uint32_t *resultPKAMemAddr)
	Starts a big number modulus operation. More...
uint32_t	PKABigNumModGetResult (uint8_t *resultBuf, uint32_t length, uint32_t resultPKAMemAddr)
	Gets the result of the big number modulus operation. More...
uint32_t	PKABigNumDivideStart (const uint8_t *dividend, uint32_t dividendLength, const uint8_t *divisor, uint32_t divisorLength, uint32_t *resultQuotientMemAddr, uint32_t *resultRemainderMemAddr)
	Starts a big number divide operation. More...
uint32_t	PKABigNumDivideGetQuotient (uint8_t *resultBuf, uint32_t *length, uint32_t resultQuotientMemAddr)
	Gets the quotient of the big number divide operation. More...
uint32_t	PKABigNumDivideGetRemainder (uint8_t *resultBuf, uint32_t *length, uint32_t resultRemainderMemAddr)
	Gets the remainder of the big number divide operation. More...
uint32_t	PKABigNumCmpStart (const uint8_t *bigNum1, const uint8_t *bigNum2, uint32_t length)
	Starts the comparison of two big numbers. More...
uint32_t	PKABigNumCmpGetResult (void)
	Gets the result of the comparison operation of two big numbers. More...
uint32_t	PKABigNumInvModStart (const uint8_t *bigNum, uint32_t bigNumLength, const uint8_t *modulus, uint32_t modulusLength, uint32_t *resultPKAMemAddr)
	Starts a big number inverse modulo operation. More...
uint32_t	PKABigNumInvModGetResult (uint8_t *resultBuf, uint32_t length, uint32_t resultPKAMemAddr)
	Gets the result of the big number inverse modulo operation. More...
uint32_t	PKABigNumMultiplyStart (const uint8_t *multiplicand, uint32_t multiplicandLength, const uint8_t *multiplier, uint32_t multiplierLength, uint32_t *resultPKAMemAddr)
	Starts the multiplication of two big numbers. More...
uint32_t	PKABigNumMultGetResult (uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr)
	Gets the result of the big number multiplication. More...
uint32_t	PKABigNumAddStart (const uint8_t *bigNum1, uint32_t bigNum1Length, const uint8_t *bigNum2, uint32_t bigNum2Length, uint32_t *resultPKAMemAddr)
	Starts the addition of two big numbers. More...
uint32_t	PKABigNumAddGetResult (uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr)
	Gets the result of the addition operation on two big numbers. More...
uint32_t	PKABigNumSubStart (const uint8_t *minuend, uint32_t minuendLength, const uint8_t *subtrahend, uint32_t subtrahendLength, uint32_t *resultPKAMemAddr)
	Starts the subtraction of one big number from another. More...
uint32_t	PKABigNumSubGetResult (uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr)
	Gets the result of the subtraction operation on two big numbers. More...
uint32_t	PKAEccMultiplyStart (const uint8_t *scalar, const uint8_t *curvePointX, const uint8_t *curvePointY, const uint8_t *prime, const uint8_t *a, const uint8_t *b, uint32_t length, uint32_t *resultPKAMemAddr)
	Starts ECC multiplication. More...
uint32_t	PKAEccMontgomeryMultiplyStart (const uint8_t *scalar, const uint8_t *curvePointX, const uint8_t *prime, const uint8_t *a, uint32_t length, uint32_t *resultPKAMemAddr)
	Starts ECC Montgomery multiplication. More...
uint32_t	PKAEccMultiplyGetResult (uint8_t *curvePointX, uint8_t *curvePointY, uint32_t resultPKAMemAddr, uint32_t length)
	Gets the result of ECC multiplication. More...
uint32_t	PKAEccAddStart (const uint8_t *curvePoint1X, const uint8_t *curvePoint1Y, const uint8_t *curvePoint2X, const uint8_t *curvePoint2Y, const uint8_t *prime, const uint8_t *a, uint32_t length, uint32_t *resultPKAMemAddr)
	Starts the ECC addition. More...
uint32_t	PKAEccAddGetResult (uint8_t *curvePointX, uint8_t *curvePointY, uint32_t resultPKAMemAddr, uint32_t length)
	Gets the result of the ECC addition. More...
uint32_t	PKAEccVerifyPublicKeyWeierstrassStart (const uint8_t *curvePointX, const uint8_t *curvePointY, const uint8_t *prime, const uint8_t *a, const uint8_t *b, const uint8_t *order, uint32_t length)
	Begins the validation of a public key against a Short-Weierstrass curve. More...

Variables
const PKA_EccPoint224	NISTP224_generator
	X coordinate of the generator point of the NISTP224 curve. More...
const PKA_EccParam224	NISTP224_prime
	Prime of the NISTP224 curve. More...
const PKA_EccParam224	NISTP224_a
	a constant of the NISTP224 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam224	NISTP224_b
	b constant of the NISTP224 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam224	NISTP224_order
	Order of the NISTP224 curve. More...
const PKA_EccPoint256	NISTP256_generator
	X coordinate of the generator point of the NISTP256 curve. More...
const PKA_EccParam256	NISTP256_prime
	Prime of the NISTP256 curve. More...
const PKA_EccParam256	NISTP256_a
	a constant of the NISTP256 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam256	NISTP256_b
	b constant of the NISTP256 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam256	NISTP256_order
	Order of the NISTP256 curve. More...
const PKA_EccPoint384	NISTP384_generator
	X coordinate of the generator point of the NISTP384 curve. More...
const PKA_EccParam384	NISTP384_prime
	Prime of the NISTP384 curve. More...
const PKA_EccParam384	NISTP384_a
	a constant of the NISTP384 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam384	NISTP384_b
	b constant of the NISTP384 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam384	NISTP384_order
	Order of the NISTP384 curve. More...
const PKA_EccPoint521	NISTP521_generator
	X coordinate of the generator point of the NISTP521 curve. More...
const PKA_EccParam521	NISTP521_prime
	Prime of the NISTP521 curve. More...
const PKA_EccParam521	NISTP521_a
	a constant of the NISTP521 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam521	NISTP521_b
	b constant of the NISTP521 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam521	NISTP521_order
	Order of the NISTP521 curve. More...
const PKA_EccPoint256	BrainpoolP256R1_generator
	X coordinate of the generator point of the BrainpoolP256R1 curve. More...
const PKA_EccParam256	BrainpoolP256R1_prime
	Prime of the BrainpoolP256R1 curve. More...
const PKA_EccParam256	BrainpoolP256R1_a
	a constant of the BrainpoolP256R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam256	BrainpoolP256R1_b
	b constant of the BrainpoolP256R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam256	BrainpoolP256R1_order
	Order of the BrainpoolP256R1 curve. More...
const PKA_EccPoint384	BrainpoolP384R1_generator
	X coordinate of the generator point of the BrainpoolP384R1 curve. More...
const PKA_EccParam384	BrainpoolP384R1_prime
	Prime of the BrainpoolP384R1 curve. More...
const PKA_EccParam384	BrainpoolP384R1_a
	a constant of the BrainpoolP384R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam384	BrainpoolP384R1_b
	b constant of the BrainpoolP384R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam384	BrainpoolP384R1_order
	Order of the BrainpoolP384R1 curve. More...
const PKA_EccPoint512	BrainpoolP512R1_generator
	X coordinate of the generator point of the BrainpoolP512R1 curve. More...
const PKA_EccParam512	BrainpoolP512R1_prime
	Prime of the BrainpoolP512R1 curve. More...
const PKA_EccParam512	BrainpoolP512R1_a
	a constant of the BrainpoolP512R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam512	BrainpoolP512R1_b
	b constant of the BrainpoolP512R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b). More...
const PKA_EccParam512	BrainpoolP512R1_order
	Order of the BrainpoolP512R1 curve. More...
const PKA_EccPoint256	Curve25519_generator
	X coordinate of the generator point of the Curve25519 curve. More...
const PKA_EccParam256	Curve25519_prime
	Prime of the Curve25519 curve. More...
const PKA_EccParam256	Curve25519_a
	a constant of the Curve25519 curve when expressed in Montgomery form (By^2 = x^3 + a*x^2 + x). More...
const PKA_EccParam256	Curve25519_b
	b constant of the Curve25519 curve when expressed in Montgomery form (By^2 = x^3 + a*x^2 + x). More...
const PKA_EccParam256	Curve25519_order
	Order of the Curve25519 curve. More...

Detailed Description

Introduction

The PKA (Public Key Accelerator) API provides access to the Large Number Engine (LNME). The LNME allows for efficient math operations on numbers larger than those that fit within the ALU of the system CPU. It is significantly faster to perform these operations using the LNME than implementing the same functionality in software using regular word-wise math operations. While the LNME runs in the background, the system CPU may perform other operations or be turned off.

The LNME supports both primitive math operations and serialized primitive operations (sequencer operations).

• Addition
• Multiplication
• Comparison
• Modulo
• Inverse Modulo
• ECC Point Addition (including point doubling)
• ECC Scalar Multiplication

These primitives and sequencer operations can be used to implement various public key encryption schemes. It is possible to implement the following schemes using the operations mentioned above:

• RSA encryption and decryption
• RSA sign and verify
• DHE (Diffie-Hellman Key Exchange)
• ECDH (Elliptic Curve Diffie-Hellman Key Exchange)
• ECDSA (Elliptic Curve Digital Signature Algorithm)
• ECIES (Elliptic Curve Integrated Encryption Scheme)

The DriverLib PKA functions copy the relevant parameters into the dedicated PKA RAM. The LNME requires these parameters be present and correctly formatted in the PKA RAM and not system RAM. They are copied word-wise as the PKA RAM does not support byte-wise access. The CPU handles the alignment differences during the memory copy operation. Forcing buffer alignment in system RAM results in a significant speedup of the copy operation compared to unaligned buffers.

When the operation completes, the result is copied back into a buffer in system RAM specified by the application. The PKA RAM is then cleared to prevent sensitive keying material from remaining in PKA RAM.

Function Documentation

bool PKAArrayAllZeros	(	const uint8_t *	array,
		uint32_t	arrayLength
	)

Checks whether and array only consists of zeros.

Parameters

[in]	array	is the array to check.
[in]	arrayLength	is the length of the array.

Returns

Returns true if the array contains only zeros and false if one or more bits are set.

{
    uint32_t i;
    uint8_t arrayBits = 0;

    // We could speed things up by comparing word-wise rather than byte-wise.
    // However, this extra overhead is inconsequential compared to running an
    // actual PKA operation. Especially ECC operations.
    for (i = 0; i < arrayLength; i++) {
        arrayBits |= array[i];
    }

    if (arrayBits) {
        return false;
    }
    else {
        return true;
    }

}

uint32_t PKABigNumAddGetResult	(	uint8_t *	resultBuf,
		uint32_t *	resultLength,
		uint32_t	resultPKAMemAddr
	)

Gets the result of the addition operation on two big numbers.

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in,out]	resultLength	is the address of the variable containing the length of the buffer. After the operation the actual length of the resultant is stored at this address.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKABigNumAddStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_FAILURE if the operation is not successful.
• PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less then the length of the result.

See also

PKABigNumAddStart()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    return PKAGetBigNumResult(resultBuf, resultLength, resultPKAMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumAddStart	(	const uint8_t *	bigNum1,
		uint32_t	bigNum1Length,
		const uint8_t *	bigNum2,
		uint32_t	bigNum2Length,
		uint32_t *	resultPKAMemAddr
	)

Starts the addition of two big numbers.

Parameters

[in]	bigNum1	is the pointer to the buffer containing the first big number.
[in]	bigNum1Length	is the size of the first big number in bytes.
[in]	bigNum2	is the pointer to the buffer containing the second big number.
[in]	bigNum2Length	is the size of the second big number in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKABigNumAddGetResult()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    uint32_t offset = 0;

    // Check for arguments.
    ASSERT(bigNum1);
    ASSERT(bigNum2);
    ASSERT(resultPKAMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(bigNum1, bigNum1Length, offset, PKA_O_APTR);

    offset = PKAWritePkaParam(bigNum2, bigNum2Length, offset, PKA_O_BPTR);

    // Copy the result vector address location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load C pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_CPTR) = offset >> 2;

    // Set the function for the add operation and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_ADD);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumCmpGetResult

(

void

)

Gets the result of the comparison operation of two big numbers.

This function provides the results of the comparison of two big numbers which was started using the PKABigNumCmpStart().

Returns

Returns a status code.

• PKA_STATUS_OPERATION_BUSY if the operation is in progress.
• PKA_STATUS_SUCCESS if the two big numbers are equal.
• PKA_STATUS_A_GREATER_THAN_B if the first number is greater than the second.
• PKA_STATUS_A_LESS_THAN_B if the first number is less than the second.

See also

PKABigNumCmpStart()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    uint32_t  status;

    // verify that the operation is complete.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    // Check the COMPARE register.
    switch(HWREG(PKA_BASE + PKA_O_COMPARE)) {
        case PKA_COMPARE_A_EQUALS_B:
            status = PKA_STATUS_EQUAL;
            break;

        case PKA_COMPARE_A_GREATER_THAN_B:
            status = PKA_STATUS_A_GREATER_THAN_B;
            break;

        case PKA_COMPARE_A_LESS_THAN_B:
            status = PKA_STATUS_A_LESS_THAN_B;
            break;

        default:
            status = PKA_STATUS_FAILURE;
            break;
    }

    return status;
}

uint32_t PKABigNumCmpStart	(	const uint8_t *	bigNum1,
		const uint8_t *	bigNum2,
		uint32_t	length
	)

Starts the comparison of two big numbers.

This function starts the comparison of two big numbers pointed by bigNum1 and bigNum2.

Note

bigNum1 and bigNum2 must have same size.

Parameters

[in]	bigNum1	is the pointer to the first big number.
[in]	bigNum2	is the pointer to the second big number.
[in]	length	is the size of the big numbers in bytes.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKABigNumCmpGetResult()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    uint32_t offset = 0;

    // Check the arguments.
    ASSERT(bigNum1);
    ASSERT(bigNum2);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(bigNum1, length, offset, PKA_O_APTR);

    offset = PKAWritePkaParam(bigNum2, length, offset, PKA_O_BPTR);

    // Set the PKA Function register for the Compare operation
    // and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_COMPARE);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumDivideGetQuotient	(	uint8_t *	resultBuf,
		uint32_t *	length,
		uint32_t	resultQuotientMemAddr
	)

Gets the quotient of the big number divide operation.

This function gets the quotient of the big number divide operation which was previously started using the function PKABigNumDivideStart().

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in]	length	is the size of the provided buffer in bytes.
[in]	resultQuotientMemAddr	is the address of the result location which was provided by the start function PKABigNumDivideStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_BUF_UNDERFLOW if the length is less than the length of the result.

See also

PKABigNumDivideStart()

{
    return PKAGetBigNumResult(resultBuf, length, resultQuotientMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumDivideGetRemainder	(	uint8_t *	resultBuf,
		uint32_t *	length,
		uint32_t	resultRemainderMemAddr
	)

Gets the remainder of the big number divide operation.

This function gets the remainder of the big number divide operation which was previously started using the function PKABigNumDivideStart().

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in]	length	is the size of the provided buffer in bytes.
[in]	resultRemainderMemAddr	is the address of the result location which was provided by the start function PKABigNumDivideStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_BUF_UNDERFLOW if the length is less than the length of the result.

See also

PKABigNumDivideStart()

{
    return PKAGetBigNumResultRemainder(resultBuf, length, resultQuotientMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumDivideStart	(	const uint8_t *	dividend,
		uint32_t	dividendLength,
		const uint8_t *	divisor,
		uint32_t	divisorLength,
		uint32_t *	resultQuotientMemAddr,
		uint32_t *	resultRemainderMemAddr
	)

Starts a big number divide operation.

This function starts the dive operation on the big number bigNum using the divisor. The PKA RAM location where the result will be available is stored in resultPKAMemAddr.

Parameters

[in]	dividend	is the pointer to the big number to be divided.
[in]	dividendLength	is the size of the big number dividend in bytes.
[in]	divisor	is the pointer to the divisor.
[in]	divisorLength	is the size of the divisor in bytes.
[out]	resultQuotientMemAddr	is the pointer to the quotient vector location which will be set by this function.
[out]	resultRemainderMemAddr	is the pointer to the remainder vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY, if the PKA module is busy doing some other operation.

See also

PKABigNumDivideGetResult()

{
    uint32_t offset = 0;

    // Check the arguments.
    ASSERT(dividend);
    ASSERT(divisor);
    ASSERT(resultQuotientMemAddr);
    ASSERT(resultRemainderMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(dividend, dividendLength, offset, PKA_O_APTR);

    offset = PKAWritePkaParamExtraOffset(divisor, divisorLength, offset, PKA_O_BPTR);

    // Copy the remainder result vector address location.
    if (resultRemainderMemAddr) {
        *resultRemainderMemAddr = PKA_RAM_BASE + offset;
    }

    // The remainder cannot ever be larger than the divisor. It should fit inside
    // a buffer of that size.
    offset = PKAWritePkaParamExtraOffset(0, divisorLength, offset, PKA_O_CPTR);

    // Copy the remainder result vector address location.
    if (resultQuotientMemAddr) {
        *resultQuotientMemAddr = PKA_RAM_BASE + offset;
    }

    // Load D pointer with the quotient location in PKA RAM
    HWREG(PKA_BASE + PKA_O_DPTR) = offset >> 2;

    // Start the PKCP modulo operation by setting the PKA Function register.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_DIVIDE);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumInvModGetResult	(	uint8_t *	resultBuf,
		uint32_t	length,
		uint32_t	resultPKAMemAddr
	)

Gets the result of the big number inverse modulo operation.

This function gets the result of the big number inverse modulo operation previously started using the function PKABigNumInvModStart(). The function will zero-out resultBuf prior to copying in the result of the inverse modulo operation.

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in]	length	is the size of the provided buffer in bytes.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKABigNumInvModStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less than the result.

See also

PKABigNumInvModStart()

{
    // Zero-out array in case modulo result is shorter than length
    PKAZeroOutArray(resultBuf, length);

    return PKAGetBigNumResult(resultBuf, &length, resultPKAMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumInvModStart	(	const uint8_t *	bigNum,
		uint32_t	bigNumLength,
		const uint8_t *	modulus,
		uint32_t	modulusLength,
		uint32_t *	resultPKAMemAddr
	)

Starts a big number inverse modulo operation.

This function starts the inverse modulo operation on bigNum using the divisor modulus.

Parameters

[in]	bigNum	is the pointer to the buffer containing the big number (dividend).
[in]	bigNumLength	is the size of the bigNum in bytes.
[in]	modulus	is the pointer to the buffer containing the divisor.
[in]	modulusLength	is the size of the divisor in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKABigNumInvModGetResult()

{
    uint32_t offset = 0;

    // Check the arguments.
    ASSERT(bigNum);
    ASSERT(modulus);
    ASSERT(resultPKAMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(bigNum, bigNumLength, offset, PKA_O_APTR);

    offset = PKAWritePkaParam(modulus, modulusLength, offset, PKA_O_BPTR);

    // Copy the result vector address location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load D pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_DPTR) = offset >> 2;

    // set the PKA function to InvMod operation and the start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = 0x0000F000;

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumModGetResult	(	uint8_t *	resultBuf,
		uint32_t	length,
		uint32_t	resultPKAMemAddr
	)

Gets the result of the big number modulus operation.

This function gets the result of the big number modulus operation which was previously started using the function PKABigNumModStart(). The function will zero-out resultBuf prior to copying in the result of the modulo operation.

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in]	length	is the size of the provided buffer in bytes.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKABigNumModStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_BUF_UNDERFLOW if the length is less than the length of the result.

See also

PKABigNumModStart()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    // Zero-out array in case modulo result is shorter than length
    PKAZeroOutArray(resultBuf, length);

    return PKAGetBigNumResultRemainder(resultBuf, &length, resultPKAMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumModStart	(	const uint8_t *	bigNum,
		uint32_t	bigNumLength,
		const uint8_t *	modulus,
		uint32_t	modulusLength,
		uint32_t *	resultPKAMemAddr
	)

Starts a big number modulus operation.

This function starts the modulo operation on the big number bigNum using the divisor modulus. The PKA RAM location where the result will be available is stored in resultPKAMemAddr.

Parameters

[in]	bigNum	is the pointer to the big number on which modulo operation needs to be carried out.
[in]	bigNumLength	is the size of the big number bigNum in bytes.
[in]	modulus	is the pointer to the divisor.
[in]	modulusLength	is the size of the divisor modulus in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY, if the PKA module is busy doing some other operation.

See also

PKABigNumModGetResult()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    uint32_t offset = 0;

    // Check the arguments.
    ASSERT(bigNum);
    ASSERT(modulus);
    ASSERT(resultPKAMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(bigNum, bigNumLength, offset, PKA_O_APTR);

    offset = PKAWritePkaParamExtraOffset(modulus, modulusLength, offset, PKA_O_BPTR);

    // Copy the result vector address location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load C pointer with the result location in PKA RAM
    HWREG(PKA_BASE + PKA_O_CPTR) = offset >> 2;

    // Start the PKCP modulo operation by setting the PKA Function register.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_MODULO);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumMultGetResult	(	uint8_t *	resultBuf,
		uint32_t *	resultLength,
		uint32_t	resultPKAMemAddr
	)

Gets the result of the big number multiplication.

This function gets the result of the multiplication of two big numbers operation previously started using the function PKABigNumMultiplyStart().

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in,out]	resultLength	is the address of the variable containing the length of the buffer in bytes. After the operation, the actual length of the resultant is stored at this address.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKABigNumMultiplyStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_FAILURE if the operation is not successful.
• PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less then the length of the result.

See also

PKABigNumMultiplyStart()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
     return PKAGetBigNumResult(resultBuf, resultLength, resultPKAMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumMultiplyStart	(	const uint8_t *	multiplicand,
		uint32_t	multiplicandLength,
		const uint8_t *	multiplier,
		uint32_t	multiplierLength,
		uint32_t *	resultPKAMemAddr
	)

Starts the multiplication of two big numbers.

Parameters

[in]	multiplicand	is the pointer to the buffer containing the big number multiplicand.
[in]	multiplicandLength	is the size of the multiplicand in bytes.
[in]	multiplier	is the pointer to the buffer containing the big number multiplier.
[in]	multiplierLength	is the size of the multiplier in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKABigNumMultGetResult()

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    uint32_t offset = 0;

    // Check for the arguments.
    ASSERT(multiplicand);
    ASSERT(multiplier);
    ASSERT(resultPKAMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(multiplicand, multiplicandLength, offset, PKA_O_APTR);

    offset = PKAWritePkaParam(multiplier, multiplierLength, offset, PKA_O_BPTR);


    // Copy the result vector address location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load C pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_CPTR) = offset >> 2;

    // Set the PKA function to the multiplication and start it.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_MULTIPLY);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKABigNumSubGetResult	(	uint8_t *	resultBuf,
		uint32_t *	resultLength,
		uint32_t	resultPKAMemAddr
	)

Gets the result of the subtraction operation on two big numbers.

Parameters

[out]	resultBuf	is the pointer to buffer where the result needs to be stored.
[in,out]	resultLength	is the address of the variable containing the length of the buffer. After the operation the actual length of the resultant is stored at this address.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKABigNumAddStart().

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_FAILURE if the operation is not successful.
• PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less then the length of the result.

See also

PKABigNumSubStart()

{
    return PKAGetBigNumResult(resultBuf, resultLength, resultPKAMemAddr);
}

Here is the call graph for this function:

uint32_t PKABigNumSubStart	(	const uint8_t *	minuend,
		uint32_t	minuendLength,
		const uint8_t *	subtrahend,
		uint32_t	subtrahendLength,
		uint32_t *	resultPKAMemAddr
	)

Starts the subtraction of one big number from another.

Parameters

[in]	minuend	is the pointer to the buffer containing the big number to be subtracted from.
[in]	minuendLength	is the size of the minuend in bytes.
[in]	subtrahend	is the pointer to the buffer containing the big number to subtract from the minuend.
[in]	subtrahendLength	is the size of the subtrahend in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKABigNumSubGetResult()

{
    uint32_t offset = 0;

    // Check for arguments.
    ASSERT(minuend);
    ASSERT(subtrahend);
    ASSERT(resultPKAMemAddr);


    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(minuend, minuendLength, offset, PKA_O_APTR);

    offset = PKAWritePkaParam(subtrahend, subtrahendLength, offset, PKA_O_BPTR);

    // Copy the result vector address location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load C pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_CPTR) = offset >> 2;

    // Set the function for the add operation and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = (PKA_FUNCTION_RUN | PKA_FUNCTION_SUBTRACT);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

void PKAClearPkaRam

(

void

)

Zeroizes PKA RAM.

This function uses the zeroization function in PRCM to clear the PKA RAM.

                         {
    // Get initial state
    uint32_t secdmaclkgr = HWREG(PRCM_BASE + PRCM_O_SECDMACLKGR);

    // OR in zeroize bit
    secdmaclkgr |= PRCM_SECDMACLKGR_PKA_ZERIOZE_RESET_N;

    // Start zeroization
    HWREG(PRCM_BASE + PRCM_O_SECDMACLKGR) = secdmaclkgr;

    // Wait 256 cycles for PKA RAM to be cleared
    CPUdelay(256 / 4);

    // Turn off zeroization
    HWREG(PRCM_BASE + PRCM_O_SECDMACLKGR) = secdmaclkgr & (~PRCM_SECDMACLKGR_PKA_ZERIOZE_RESET_N);
}

Here is the call graph for this function:

uint32_t PKAEccAddGetResult	(	uint8_t *	curvePointX,
		uint8_t *	curvePointY,
		uint32_t	resultPKAMemAddr,
		uint32_t	length
	)

Gets the result of the ECC addition.

This function gets the result of ECC point addition operation on the on the two given EC points, previously started using the function PKAEccAddStart().

Parameters

[out]	curvePointX	is the pointer to the structure where the X coordinate of the resultant EC point will be stored.
[out]	curvePointY	is the pointer to the structure where the Y coordinate of the resultant EC point will be stored.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKAEccAddGetResult().
[in]	length	is the length of the curve parameters in bytes.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_FAILURE if the operation is not successful.

See also

PKAEccAddStart()

{
    return PKAGetECCResult(curvePointX, curvePointY, resultPKAMemAddr, length);
}

Here is the call graph for this function:

uint32_t PKAEccAddStart	(	const uint8_t *	curvePoint1X,
		const uint8_t *	curvePoint1Y,
		const uint8_t *	curvePoint2X,
		const uint8_t *	curvePoint2Y,
		const uint8_t *	prime,
		const uint8_t *	a,
		uint32_t	length,
		uint32_t *	resultPKAMemAddr
	)

Starts the ECC addition.

Parameters

[in]	curvePoint1X	is the pointer to the buffer containing the X coordinate of the first elliptic curve point to be added. The point must be on the given curve.
[in]	curvePoint1Y	is the pointer to the buffer containing the Y coordinate of the first elliptic curve point to be added. The point must be on the given curve.
[in]	curvePoint2X	is the pointer to the buffer containing the X coordinate of the second elliptic curve point to be added. The point must be on the given curve.
[in]	curvePoint2Y	is the pointer to the buffer containing the Y coordinate of the second elliptic curve point to be added. The point must be on the given curve.
[in]	prime	is the prime of the curve.
[in]	a	is the a constant of the curve when the curve equation is expressed in short Weierstrass form (y^3 = x^2 + a*x + b).
[in]	length	is the length of the curve parameters in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKAEccAddGetResult()

{
    uint32_t offset = 0;

    // Check for the arguments.
    ASSERT(curvePoint1X);
    ASSERT(curvePoint1Y);
    ASSERT(curvePoint2X);
    ASSERT(curvePoint2Y);
    ASSERT(prime);
    ASSERT(a);
    ASSERT(resultPKAMemAddr);

    // Make sure no operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParamExtraOffset(curvePoint1X, length, offset, PKA_O_APTR);
    offset = PKAWritePkaParamExtraOffset(curvePoint1Y, length, offset, PKA_NO_POINTER_REG);


    offset = PKAWritePkaParamExtraOffset(prime, length, offset, PKA_O_BPTR);
    offset = PKAWritePkaParamExtraOffset(a, length, offset, PKA_NO_POINTER_REG);

    offset = PKAWritePkaParamExtraOffset(curvePoint2X, length, offset, PKA_O_CPTR);
    offset = PKAWritePkaParamExtraOffset(curvePoint2Y, length, offset, PKA_NO_POINTER_REG);

    // Copy the result vector location.
    *resultPKAMemAddr = PKA_RAM_BASE + offset;

    // Load D pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_DPTR) = offset >> 2;

    // Set the PKA Function to ECC-ADD and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION ) = PKA_FUNCTION_RUN_M | (0x03 << PKA_FUNCTION_SEQUENCER_OPERATIONS_S);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKAEccMontgomeryMultiplyStart	(	const uint8_t *	scalar,
		const uint8_t *	curvePointX,
		const uint8_t *	prime,
		const uint8_t *	a,
		uint32_t	length,
		uint32_t *	resultPKAMemAddr
	)

Starts ECC Montgomery multiplication.

Parameters

[in]	scalar	is pointer to the buffer containing the scalar value to be multiplied.
[in]	curvePointX	is the pointer to the buffer containing the X coordinate of the elliptic curve point to be multiplied. The point must be on the given curve.
[in]	prime	is the prime of the curve.
[in]	a	is the a constant of the curve when the curve equation is expressed in short Weierstrass form (y^3 = x^2 + a*x + b).
[in]	length	is the length of the curve parameters in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKAEccMultiplyGetResult()

{
    uint32_t offset = 0;

    // Check for the arguments.
    ASSERT(scalar);
    ASSERT(curvePointX);
    ASSERT(prime);
    ASSERT(a);
    ASSERT(length <= PKA_MAX_CURVE_SIZE_32_BIT_WORD * sizeof(uint32_t));
    ASSERT(resultPKAMemAddr);

    // Make sure no PKA operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(scalar, length, offset, PKA_O_APTR);

    offset = PKAWritePkaParamExtraOffset(prime, length, offset, PKA_O_BPTR);
    offset = PKAWritePkaParamExtraOffset(a, length, offset, PKA_NO_POINTER_REG);

    offset = PKAWritePkaParamExtraOffset(curvePointX, length, offset, PKA_O_CPTR);

    // Update the result location.
    // The resultPKAMemAddr may be 0 if we only want to check that we generated the point at infinity
    if (resultPKAMemAddr) {
        *resultPKAMemAddr =  PKA_RAM_BASE + offset;
    }

    // Load D pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_DPTR) = offset >> 2;

    // Set the PKA function to Montgomery ECC-MULT and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = PKA_FUNCTION_RUN_M | (0x02 << PKA_FUNCTION_SEQUENCER_OPERATIONS_S);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKAEccMultiplyGetResult	(	uint8_t *	curvePointX,
		uint8_t *	curvePointY,
		uint32_t	resultPKAMemAddr,
		uint32_t	length
	)

Gets the result of ECC multiplication.

This function gets the result of ECC point multiplication operation on the EC point and the scalar value, previously started using the function PKAEccMultiplyStart().

Parameters

[out]	curvePointX	is the pointer to the structure where the X coordinate of the resultant EC point will be stored.
[out]	curvePointY	is the pointer to the structure where the Y coordinate of the resultant EC point will be stored.
[in]	resultPKAMemAddr	is the address of the result location which was provided by the start function PKAEccMultiplyStart().
[in]	length	is the length of the curve parameters in bytes.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_RESULT_0 if the result is all zeros.
• PKA_STATUS_FAILURE if the operation is not successful.

See also

PKAEccMultiplyStart()

{
    return PKAGetECCResult(curvePointX, curvePointY, resultPKAMemAddr, length);
}

Here is the call graph for this function:

uint32_t PKAEccMultiplyStart	(	const uint8_t *	scalar,
		const uint8_t *	curvePointX,
		const uint8_t *	curvePointY,
		const uint8_t *	prime,
		const uint8_t *	a,
		const uint8_t *	b,
		uint32_t	length,
		uint32_t *	resultPKAMemAddr
	)

Starts ECC multiplication.

Parameters

[in]	scalar	is pointer to the buffer containing the scalar value to be multiplied.
[in]	curvePointX	is the pointer to the buffer containing the X coordinate of the elliptic curve point to be multiplied. The point must be on the given curve.
[in]	curvePointY	is the pointer to the buffer containing the Y coordinate of the elliptic curve point to be multiplied. The point must be on the given curve.
[in]	prime	is the prime of the curve.
[in]	a	is the a constant of the curve when the curve equation is expressed in short Weierstrass form (y^3 = x^2 + a*x + b).
[in]	b	is the b constant of the curve when the curve equation is expressed in short Weierstrass form (y^3 = x^2 + a*x + b).
[in]	length	is the length of the curve parameters in bytes.
[out]	resultPKAMemAddr	is the pointer to the result vector location which will be set by this function.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if successful in starting the operation.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing some other operation.

See also

PKAEccMultiplyGetResult()

{
    uint32_t offset = 0;

    // Check for the arguments.
    ASSERT(scalar);
    ASSERT(curvePointX);
    ASSERT(curvePointY);
    ASSERT(prime);
    ASSERT(a);
    ASSERT(b);
    ASSERT(length <= PKA_MAX_CURVE_SIZE_32_BIT_WORD * sizeof(uint32_t));
    ASSERT(resultPKAMemAddr);

    // Make sure no PKA operation is in progress.
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN) {
        return PKA_STATUS_OPERATION_BUSY;
    }

    offset = PKAWritePkaParam(scalar, length, offset, PKA_O_APTR);

    offset = PKAWritePkaParamExtraOffset(prime, length, offset, PKA_O_BPTR);
    offset = PKAWritePkaParamExtraOffset(a, length, offset, PKA_NO_POINTER_REG);
    offset = PKAWritePkaParamExtraOffset(b, length, offset, PKA_NO_POINTER_REG);

    offset = PKAWritePkaParamExtraOffset(curvePointX, length, offset, PKA_O_CPTR);
    offset = PKAWritePkaParamExtraOffset(curvePointY, length, offset, PKA_NO_POINTER_REG);

    // Update the result location.
    // The resultPKAMemAddr may be 0 if we only want to check that we generated the point at infinity
    if (resultPKAMemAddr) {
        *resultPKAMemAddr =  PKA_RAM_BASE + offset;
    }

    // Load D pointer with the result location in PKA RAM.
    HWREG(PKA_BASE + PKA_O_DPTR) = offset >> 2;

    // Set the PKA function to ECC-MULT and start the operation.
    HWREG(PKA_BASE + PKA_O_FUNCTION) = PKA_FUNCTION_RUN_M | (0x05 << PKA_FUNCTION_SEQUENCER_OPERATIONS_S);

    return PKA_STATUS_SUCCESS;
}

Here is the call graph for this function:

uint32_t PKAEccVerifyPublicKeyWeierstrassStart	(	const uint8_t *	curvePointX,
		const uint8_t *	curvePointY,
		const uint8_t *	prime,
		const uint8_t *	a,
		const uint8_t *	b,
		const uint8_t *	order,
		uint32_t	length
	)

Begins the validation of a public key against a Short-Weierstrass curve.

This function validates a public key against a curve. After performing multiple smaller PKA operations in polling mode, it starts an ECC scalar multiplication.

The function verifies that:

• X and Y are in the range [1, prime - 1]
• The point is not the point at infinity
• X and Y satisfy the Short-Weierstrass curve equation Y^2 = X^3 + a*X + b mod P
• Multiplying the point by the order of the curve yields the point at infinity

Parameters

[in]	curvePointX	is the pointer to the buffer containing the X coordinate of the elliptic curve point to verify.
[in]	curvePointY	is the pointer to the buffer containing the Y coordinate of the elliptic curve point to verify.
[in]	prime	is the prime of the curve.
[in]	a	is the a constant of the curve when the curve equation is expressed in Short-Weierstrass form (y^3 = x^2 + a*x + b).
[in]	b	is the b constant of the curve when the curve equation is expressed in Short-Weierstrass form (y^3 = x^2 + a*x + b).
[in]	order	is the order of the curve.
[in]	length	is the length of the curve parameters in bytes.

Returns

Returns a status code.

• PKA_STATUS_SUCCESS if the operation is successful.
• PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation.
• PKA_STATUS_FAILURE if the operation is not successful.
• PKA_STATUS_X_ZERO if X is zero.
• PKA_STATUS_Y_ZERO if Y is zero.
• PKA_STATUS_X_LARGER_THAN_PRIME if X is larger than the curve prime
• PKA_STATUS_Y_LARGER_THAN_PRIME if Y is larger than the curve prime
• PKA_STATUS_POINT_NOT_ON_CURVE if X and Y do not satisfy the curve equation

See also

PKAEccVerifyPublicKeyGetResult()

{
    uint32_t pkaResult;
    uint32_t resultAddress;
    uint32_t resultLength;
    uint8_t *scratchBuffer = (uint8_t *)(PKA_RAM_BASE + PKA_RAM_TOT_BYTE_SIZE / 2);
    uint8_t *scratchBuffer2 = scratchBuffer + 512;


    // Verify X in range [0, prime - 1]
    PKABigNumCmpStart(curvePointX,
                      prime,
                      length);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    pkaResult = PKABigNumCmpGetResult();

    if (pkaResult != PKA_STATUS_A_LESS_THAN_B) {
        return PKA_STATUS_X_LARGER_THAN_PRIME;
    }

    // Verify Y in range [0, prime - 1]
    PKABigNumCmpStart(curvePointY,
                      prime,
                      length);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    pkaResult = PKABigNumCmpGetResult();

    if (pkaResult != PKA_STATUS_A_LESS_THAN_B) {
        return PKA_STATUS_Y_LARGER_THAN_PRIME;
    }

    // Verify point on curve
    // Short-Weierstrass equation: Y ^ 2 = X ^3 + a * X + b mod P
    // Reduced: Y ^ 2 = X * (X ^ 2 + a) + b

    // tmp = X ^ 2
    PKABigNumMultiplyStart(curvePointX, length, curvePointX, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    resultLength = 200;
    pkaResult = PKABigNumMultGetResult(scratchBuffer, &resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp += a
    PKABigNumAddStart(scratchBuffer, resultLength, a, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    resultLength = 200;
    pkaResult = PKABigNumAddGetResult(scratchBuffer, &resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp *= x
    PKABigNumMultiplyStart(scratchBuffer, resultLength, curvePointX, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    resultLength = 200;
    pkaResult = PKABigNumMultGetResult(scratchBuffer, &resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp += b
     PKABigNumAddStart(scratchBuffer, resultLength, b, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    resultLength = 200;
    pkaResult = PKABigNumAddGetResult(scratchBuffer, &resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }


    // tmp2 = tmp % prime to ensure we have no fraction in the division.
    // The number will only shrink from here on out.
    PKABigNumModStart(scratchBuffer, resultLength, prime, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    // If the result is not a multiple of the word-length, the PKA HW will round up
    // because it deals in words only. That means that using 'length' directly
    // would cause and underflow, since length refers to the actual length in bytes of
    // the curve parameters while the PKA HW reports that rounded up to the next
    // word boundary.
    // Use 200 as the resultLength instead since we are copying to the scratch buffer
    // anyway.
    // Practically, this only happens with curves such as NIST-P521 that are not word
    // multiples.
    resultLength = 200;
    pkaResult = PKABigNumModGetResult(scratchBuffer2, resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp = y^2
    PKABigNumMultiplyStart(curvePointY, length, curvePointY, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    resultLength = 200;
    pkaResult = PKABigNumMultGetResult(scratchBuffer, &resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp %= prime
    PKABigNumModStart(scratchBuffer, resultLength, prime, length, &resultAddress);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    // If the result is not a multiple of the word-length, the PKA HW will round up
    // because it deals in words only. That means that using 'length' directly
    // would cause and underflow, since length refers to the actual length in bytes of
    // the curve parameters while the PKA HW reports that rounded up to the next
    // word boundary.
    // Use 200 as the resultLength instead since we are copying to the scratch buffer
    // anyway.
    // Practically, this only happens with curves such as NIST-P521 that are not word
    // multiples.
    resultLength = 200;
    pkaResult = PKABigNumModGetResult(scratchBuffer, resultLength, resultAddress);

    if (pkaResult != PKA_STATUS_SUCCESS) {
        return PKA_STATUS_FAILURE;
    }

    // tmp ?= tmp2
    PKABigNumCmpStart(scratchBuffer,
                      scratchBuffer2,
                      length);

    while(PKAGetOpsStatus() == PKA_STATUS_OPERATION_BUSY);

    pkaResult = PKABigNumCmpGetResult();

    if (pkaResult != PKA_STATUS_EQUAL) {
        return PKA_STATUS_POINT_NOT_ON_CURVE;
    }
    else {
        return PKA_STATUS_SUCCESS;
    }
}

Here is the call graph for this function:

uint32_t PKAGetOpsStatus

(

void

)

Gets the PKA operation status.

This function gets information on whether any PKA operation is in progress or not. This function allows to check the PKA operation status before starting any new PKA operation.

Returns

Returns a status code.

• PKA_STATUS_OPERATION_BUSY if the PKA operation is in progress.
• PKA_STATUS_OPERATION_RDY if the PKA operation is not in progress.

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

{
    if (HWREG(PKA_BASE + PKA_O_FUNCTION) & PKA_FUNCTION_RUN_M) {
        return PKA_STATUS_OPERATION_BUSY;
    }
    else {
        return PKA_STATUS_OPERATION_RDY;
    }
}

void PKAZeroOutArray	(	const uint8_t *	array,
		uint32_t	arrayLength
	)

Zeros-out an array.

Parameters

[in]	array	is the array to zero-out.
[in]	arrayLength	is the length of the array.

Referenced by PKABigNumInvModGetResult(), and PKABigNumModGetResult().

{
    uint32_t i;
    // Take the floor of paramLength in 32-bit words
    uint32_t arrayLengthInWords = arrayLength / sizeof(uint32_t);

    // Zero-out the array word-wise until i >= arrayLength
    for (i = 0; i < arrayLengthInWords * sizeof(uint32_t); i += 4) {
        HWREG(array + i) = 0;
    }

    // If i != arrayLength, there are some remaining bytes to zero-out
    if (arrayLength % sizeof(uint32_t)) {
        // Subtract 4 from i, since i has already overshot the array
        for (i -= 4; i < arrayLength; i++) {
            HWREGB(array + i * sizeof(uint32_t));
        }
    }
}

Macro Definition Documentation

#define BrainpoolP256R1_PARAM_SIZE_BYTES   32

#define BrainpoolP384R1_PARAM_SIZE_BYTES   48

#define BrainpoolP512R1_PARAM_SIZE_BYTES   64

#define Curve25519_PARAM_SIZE_BYTES   32

#define NISTP224_PARAM_SIZE_BYTES   28

#define NISTP256_PARAM_SIZE_BYTES   32

#define NISTP384_PARAM_SIZE_BYTES   48

#define NISTP521_PARAM_SIZE_BYTES   66

#define PKA_STATUS_A_GREATER_THAN_B   5

Big number compare return status if the first big number is greater than the second.

Referenced by PKABigNumCmpGetResult().

#define PKA_STATUS_A_LESS_THAN_B   6

Big number compare return status if the first big number is less than the second.

Referenced by PKABigNumCmpGetResult(), and PKAEccVerifyPublicKeyWeierstrassStart().

#define PKA_STATUS_BUF_UNDERFLOW   3

Buffer underflow.

Referenced by PKAGetBigNumResult(), and PKAGetBigNumResultRemainder().

#define PKA_STATUS_EQUAL   7

Big number compare return status if the first big number is equal to the second.

Referenced by PKABigNumCmpGetResult(), and PKAEccVerifyPublicKeyWeierstrassStart().

#define PKA_STATUS_FAILURE   1

Failure.

Referenced by PKABigNumCmpGetResult(), PKAEccVerifyPublicKeyWeierstrassStart(), and PKAGetECCResult().

#define PKA_STATUS_INVALID_PARAM   2

Invalid parameter.

#define PKA_STATUS_LOCATION_IN_USE   10

Location in PKA RAM is not available.

#define PKA_STATUS_OPERATION_BUSY   8

PKA operation is in progress.

Referenced by PKABigNumAddStart(), PKABigNumCmpGetResult(), PKABigNumCmpStart(), PKABigNumDivideStart(), PKABigNumInvModStart(), PKABigNumModStart(), PKABigNumMultiplyStart(), PKABigNumSubStart(), PKAEccAddStart(), PKAEccMontgomeryMultiplyStart(), PKAEccMultiplyStart(), PKAEccVerifyPublicKeyWeierstrassStart(), PKAGetBigNumResult(), PKAGetBigNumResultRemainder(), PKAGetECCResult(), and PKAGetOpsStatus().

#define PKA_STATUS_OPERATION_RDY   9

No PKA operation is in progress.

Referenced by PKAGetOpsStatus().

#define PKA_STATUS_POINT_AT_INFINITY   17

The ECC operation resulted in the point at infinity.

Referenced by PKAGetECCResult().

#define PKA_STATUS_POINT_NOT_ON_CURVE   15

The public key is not on the specified elliptic curve.

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

#define PKA_STATUS_RESULT_0   4

Result is all zeros.

#define PKA_STATUS_RESULT_ADDRESS_INCORRECT   16

The address of the result passed into one of the PKA*GetResult functions is incorrect.

Referenced by PKAGetBigNumResult().

#define PKA_STATUS_SUCCESS   0

Success.

Referenced by PKABigNumAddStart(), PKABigNumCmpStart(), PKABigNumDivideStart(), PKABigNumInvModStart(), PKABigNumModStart(), PKABigNumMultiplyStart(), PKABigNumSubStart(), PKAEccAddStart(), PKAEccMontgomeryMultiplyStart(), PKAEccMultiplyStart(), PKAEccVerifyPublicKeyWeierstrassStart(), PKAGetBigNumResult(), PKAGetBigNumResultRemainder(), and PKAGetECCResult().

#define PKA_STATUS_X_LARGER_THAN_PRIME   13

X coordinate of public key is larger than the curve prime.

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

#define PKA_STATUS_X_ZERO   11

X coordinate of public key is 0.

#define PKA_STATUS_Y_LARGER_THAN_PRIME   14

Y coordinate of public key is larger than the curve prime.

Referenced by PKAEccVerifyPublicKeyWeierstrassStart().

#define PKA_STATUS_Y_ZERO   12

Y coordinate of public key is 0.

Variable Documentation

const PKA_EccParam256 BrainpoolP256R1_a

a constant of the BrainpoolP256R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam256 BrainpoolP256R1_b

b constant of the BrainpoolP256R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint256 BrainpoolP256R1_generator

X coordinate of the generator point of the BrainpoolP256R1 curve.

const PKA_EccParam256 BrainpoolP256R1_order

Order of the BrainpoolP256R1 curve.

const PKA_EccParam256 BrainpoolP256R1_prime

Prime of the BrainpoolP256R1 curve.

const PKA_EccParam384 BrainpoolP384R1_a

a constant of the BrainpoolP384R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam384 BrainpoolP384R1_b

b constant of the BrainpoolP384R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint384 BrainpoolP384R1_generator

X coordinate of the generator point of the BrainpoolP384R1 curve.

const PKA_EccParam384 BrainpoolP384R1_order

Order of the BrainpoolP384R1 curve.

const PKA_EccParam384 BrainpoolP384R1_prime

Prime of the BrainpoolP384R1 curve.

const PKA_EccParam512 BrainpoolP512R1_a

a constant of the BrainpoolP512R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam512 BrainpoolP512R1_b

b constant of the BrainpoolP512R1 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint512 BrainpoolP512R1_generator

X coordinate of the generator point of the BrainpoolP512R1 curve.

const PKA_EccParam512 BrainpoolP512R1_order

Order of the BrainpoolP512R1 curve.

const PKA_EccParam512 BrainpoolP512R1_prime

Prime of the BrainpoolP512R1 curve.

const PKA_EccParam256 Curve25519_a

a constant of the Curve25519 curve when expressed in Montgomery form (By^2 = x^3 + a*x^2 + x).

const PKA_EccParam256 Curve25519_b

b constant of the Curve25519 curve when expressed in Montgomery form (By^2 = x^3 + a*x^2 + x).

const PKA_EccPoint256 Curve25519_generator

X coordinate of the generator point of the Curve25519 curve.

const PKA_EccParam256 Curve25519_order

Order of the Curve25519 curve.

const PKA_EccParam256 Curve25519_prime

Prime of the Curve25519 curve.

const PKA_EccParam224 NISTP224_a

a constant of the NISTP224 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam224 NISTP224_b

b constant of the NISTP224 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint224 NISTP224_generator

X coordinate of the generator point of the NISTP224 curve.

const PKA_EccParam224 NISTP224_order

Order of the NISTP224 curve.

const PKA_EccParam224 NISTP224_prime

Prime of the NISTP224 curve.

const PKA_EccParam256 NISTP256_a

a constant of the NISTP256 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam256 NISTP256_b

b constant of the NISTP256 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint256 NISTP256_generator

X coordinate of the generator point of the NISTP256 curve.

const PKA_EccParam256 NISTP256_order

Order of the NISTP256 curve.

const PKA_EccParam256 NISTP256_prime

Prime of the NISTP256 curve.

const PKA_EccParam384 NISTP384_a

a constant of the NISTP384 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam384 NISTP384_b

b constant of the NISTP384 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint384 NISTP384_generator

X coordinate of the generator point of the NISTP384 curve.

const PKA_EccParam384 NISTP384_order

Order of the NISTP384 curve.

const PKA_EccParam384 NISTP384_prime

Prime of the NISTP384 curve.

const PKA_EccParam521 NISTP521_a

a constant of the NISTP521 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccParam521 NISTP521_b

b constant of the NISTP521 curve when expressed in short Weierstrass form (y^3 = x^2 + a*x + b).

const PKA_EccPoint521 NISTP521_generator

X coordinate of the generator point of the NISTP521 curve.

const PKA_EccParam521 NISTP521_order

Order of the NISTP521 curve.

const PKA_EccParam521 NISTP521_prime

Prime of the NISTP521 curve.