[pka] Public Key Accelerator

Data Structures
union	PKA_EccParam256
struct	PKA_EccPoint_

Functions
uint32_t	PKAGetOpsStatus (void)
	Gets the PKA operation status. 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	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 subtration of one big number from another. More...
uint32_t	PKABigNumSubGetResult (uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr)
	Gets the result of the subtration 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	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...

Variables
const PKA_EccPoint	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...

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

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()

{
    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()

{
    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_GR_B if the first number is greater than the second.
• PKA_STATUS_A_LT_B if the first number is less than the second.

See also

PKABigNumCmpStart()

{
    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_GR_B;
            break;

        case PKA_COMPARE_A_LESS_THAN_B:
            status = PKA_STATUS_A_LT_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()

{
    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 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().

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()

{
    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().

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()

{
    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()

{
    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()

{
     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()

{
    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 subtration 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 subtration 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:

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 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(curvePoint);
    ASSERT(curvePointX);
    ASSERT(curvePointY);
    ASSERT(curve);
    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.
    *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 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.

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

Macro Definition Documentation

#define PKA_STATUS_A_GR_B   5

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

Referenced by PKABigNumCmpGetResult().

#define PKA_STATUS_A_LT_B   6

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

Referenced by PKABigNumCmpGetResult().

#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().

#define PKA_STATUS_FAILURE   1

Failure.

Referenced by PKABigNumCmpGetResult(), and PKAGetECCResult().

#define PKA_STATUS_INVALID_PARAM   2

Invalid parameter.

#define PKA_STATUS_OPERATION_BUSY   8

PKA operation is in progress.

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

#define PKA_STATUS_OPERATION_RDY   9

No PKA operation is in progress.

Referenced by PKAGetOpsStatus().

#define PKA_STATUS_RESULT_0   4

Result is all zeros.

Referenced by PKAGetBigNumResult(), PKAGetBigNumResultRemainder(), and PKAGetECCResult().

#define PKA_STATUS_SUCCESS   0

Success.

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

Variable Documentation

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_EccPoint 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.