APIs for PKA

Introduction

This module contains APIs to program and use the PKA.

Files
file	pka.h
	This file contains the prototype of PKA driver APIs.

Data Structures
struct	PKA_RSAPubkey
	RSA public key. All values are in biginteger format (size followed by word value array, least significant word first) More...
struct	PKA_RSAPrivkey
	RSA private key. All values are in biginteger format (size followed by word value array, least significant word first) More...
struct	PKA_ECPoint
	EC Point, also the public key. More...
struct	PKA_ECPrimeCurveP
	EC prime curve parameters. More...
struct	PKA_ECDSASig
	ECDSA signature. More...
struct	PKA_Attrs
	PKA attributes. More...
struct	PKA_Config
	PKA driver context. More...

Functions
PKA_Handle	PKA_open (uint32_t index)
	Function to Open PKA instance, enable PKA engine, Initialize clocks and Load PKA Fw. More...
PKA_Return_t	PKA_close (PKA_Handle handle)
	Function to close a PKA module specified by the PKA handle. More...
PKA_Return_t	PKA_RSAPrivate (PKA_Handle handle, const uint32_t m[PKA_BIGINT_MAX], const struct PKA_RSAPrivkey *k, uint32_t result[PKA_BIGINT_MAX])
	This Function performs Decryption or Signing operations. More...
PKA_Return_t	PKA_RSAPublic (PKA_Handle handle, const uint32_t m[PKA_BIGINT_MAX], const struct PKA_RSAPubkey *k, uint32_t result[PKA_BIGINT_MAX])
	This Function performs Encryption or Verification operations. More...
PKA_Return_t	PKA_ECDSASign (PKA_Handle handle, const struct PKA_ECPrimeCurveP *cp, const uint32_t priv[PKA_EC_BIGINT_MAX], const uint32_t k[PKA_EC_BIGINT_MAX], const uint32_t h[PKA_EC_BIGINT_MAX], struct PKA_ECDSASig *sig)
	ECDSA sign primitive function. More...
PKA_Return_t	PKA_ECDSAVerify (PKA_Handle handle, const struct PKA_ECPrimeCurveP *cp, const struct PKA_ECPoint *pub, const struct PKA_ECDSASig *sig, const uint32_t h[PKA_EC_BIGINT_MAX])
	ECDSA verify primitive function. More...

Typedefs
typedef void *	PKA_Handle
	Handle to the PKA driver. More...

Enumerations
enum	PKA_Return_t { PKA_RETURN_SUCCESS = 0xCEF6A572U, PKA_RETURN_FAILURE = 0xD20341DDU }
	PKA Driver Error code. More...

Macros
#define	PKA_BIGINT_MAX   (130U)
#define	PKA_EC_BIGINT_MAX   (18U)
#define	PKA_EC_PARAM_MAXLEN   (68U)
#define	PKA_BIGINT_LEN(bytelen)   (((bytelen) / 4U) + 1U)
#define	PKA_RSA_KEY_E_MAXLEN   (8U)
#define	PKA_RSA_KEY_N_MAXLEN   (520U)
#define	PKA_RSA_KEY_PQ_MAXLEN   ((PKA_RSA_KEY_N_MAXLEN / 2U) + 4U)
#define	PKA_RSA_SIG_MAXLEN   PKA_RSA_KEY_N_MAXLEN

Macro Definition Documentation

PKA_BIGINT_MAX

#define PKA_BIGINT_MAX   (130U)

Max size of bigint in words - for RSA

PKA_EC_BIGINT_MAX

#define PKA_EC_BIGINT_MAX   (18U)

Max size of bigint in words - for ECDSA

PKA_EC_PARAM_MAXLEN

#define PKA_EC_PARAM_MAXLEN   (68U)

Maximum length of a big integer used in EC crypto in bytes, enough to accommodate 521-bit prime curves

PKA_BIGINT_LEN

#define PKA_BIGINT_LEN

(

bytelen

)

(((bytelen) / 4U) + 1U)

Length of a biginteger array in words, the +1 is for the size

PKA_RSA_KEY_E_MAXLEN

#define PKA_RSA_KEY_E_MAXLEN   (8U)

RSA KEY E maximun length

PKA_RSA_KEY_N_MAXLEN

#define PKA_RSA_KEY_N_MAXLEN   (520U)

RSA KEY N maximun length

PKA_RSA_KEY_PQ_MAXLEN

#define PKA_RSA_KEY_PQ_MAXLEN   ((PKA_RSA_KEY_N_MAXLEN / 2U) + 4U)

RSA KEY PQ maximun length

PKA_RSA_SIG_MAXLEN

#define PKA_RSA_SIG_MAXLEN   PKA_RSA_KEY_N_MAXLEN

RSA KEY SIG maximun length

Typedef Documentation

PKA_Handle

typedef void* PKA_Handle

Handle to the PKA driver.

Enumeration Type Documentation

PKA_Return_t

enum PKA_Return_t

PKA Driver Error code.

The enumeration describes all the possible return and error codes which the PKA Driver can return

Enumerator
PKA_RETURN_SUCCESS	Success/pass return code
PKA_RETURN_FAILURE	General or unspecified failure/error

Function Documentation

PKA_open()

PKA_Handle PKA_open

(

uint32_t

index

)

Function to Open PKA instance, enable PKA engine, Initialize clocks and Load PKA Fw.

Returns

A PKA_Handle on success or a NULL on an error or if it has been opened already

PKA_close()

PKA_Return_t PKA_close

(

PKA_Handle

handle

)

Function to close a PKA module specified by the PKA handle.

Parameters

handle

PKA_Handle returned from PKA_open()

PKA_RSAPrivate()

PKA_Return_t PKA_RSAPrivate	(	PKA_Handle	handle,
		const uint32_t	m[PKA_BIGINT_MAX],
		const struct PKA_RSAPrivkey *	k,
		uint32_t	result[PKA_BIGINT_MAX]
	)

This Function performs Decryption or Signing operations.

Parameters

handle	PKA_Handle returned from PKA_open()
m	m value in bigint format.
k	RSA private key
result	Result of the operation in bigint format. caller must allocate memory size of (2 * sizeof(p)) for the result.

Returns

PKA_RETURN_SUCCESS if requested operation completed. PKA_RETURN_FAILURE if requested operation not completed.

PKA_RSAPublic()

PKA_Return_t PKA_RSAPublic	(	PKA_Handle	handle,
		const uint32_t	m[PKA_BIGINT_MAX],
		const struct PKA_RSAPubkey *	k,
		uint32_t	result[PKA_BIGINT_MAX]
	)

This Function performs Encryption or Verification operations.

Parameters

handle	PKA_Handle returned from PKA_open()
m	m value in bigint format.
k	RSA public key
result	Result of the operation in bigint format. caller must allocate the same memory as s and n for this array.

Returns

PKA_RETURN_SUCCESS if requested operation completed. PKA_RETURN_FAILURE if requested operation not completed.

PKA_ECDSASign()

PKA_Return_t PKA_ECDSASign	(	PKA_Handle	handle,
		const struct PKA_ECPrimeCurveP *	cp,
		const uint32_t	priv[PKA_EC_BIGINT_MAX],
		const uint32_t	k[PKA_EC_BIGINT_MAX],
		const uint32_t	h[PKA_EC_BIGINT_MAX],
		struct PKA_ECDSASig *	sig
	)

ECDSA sign primitive function.

Parameters

handle	PKA_Handle returned from PKA_open()
cp	EC curve parameters
priv	EC private key
k	Random number for each signing
h	Hash value of message to sign in bigint format
sig	ECDSA Signature - 'r' and 's' values

Returns

PKA_RETURN_SUCCESS if requested operation completed. PKA_RETURN_FAILURE if requested operation not completed.

PKA_ECDSAVerify()

PKA_Return_t PKA_ECDSAVerify	(	PKA_Handle	handle,
		const struct PKA_ECPrimeCurveP *	cp,
		const struct PKA_ECPoint *	pub,
		const struct PKA_ECDSASig *	sig,
		const uint32_t	h[PKA_EC_BIGINT_MAX]
	)

ECDSA verify primitive function.

Parameters

handle	PKA_Handle returned from PKA_open()
cp	EC curve parameters
pub	EC Public key
sig	ECDSA Signature - 'r' & 's' value in bigint format
h	Hash value of message to verify in bigint format

Returns

PKA_RETURN_SUCCESS if requested operation completed. PKA_RETURN_FAILURE if requested operation not completed.

Variable Documentation

gPkaConfig

PKA_Config gPkaConfig[]

extern

Externally defined driver configuration array.

gPkaConfigNum

uint32_t gPkaConfigNum

extern

Externally defined driver configuration Num.