43.3.3.2 Accessing Different Library Services

All cryptographic services in the library are accessed by the macro vPUKCL_Process. All of these services use the same process for receiving and returning parameters. PUKCL receives two arguments: the requested service and a pointer to a structure called the parameter block. The parameter block contains two structures, a common parameter structure for all commands and specific parameter structure for each service. A specific service is accessed with vPUKCL_Process by passing the service name as the first argument. For example, to perform SelfTest, use vPUKCL_Process(SelfTest, pvPUKCLParam).

PUKCL Parameter Block

typedef struct _PUKCL_param {
    PUKCL_HEADER PUKCL_Header;
    union {
    _PUKCL_CLEARFLAGS PUKCL_ClearFlags;
    _PUKCL_COMP       PUKCL_Comp;
    _PUKCL_CONDCOPY   PUKCL_CondCopy;
    _PUKCL_CRT        PUKCL_CRT;
    _PUKCL_DIV        PUKCL_Div;
    _PUKCL_EXPMOD     PUKCL_ExpMod;
    _PUKCL_FASTCOPY   PUKCL_FastCopy;
    _PUKCL_FILL       PUKCL_Fill;
    _PUKCL_FMULT      PUKCL_Fmult;
    _PUKCL_GCD        PUKCL_GCD;
    _PUKCL_PRIMEGEN   PUKCL_PrimeGen;
    _PUKCL_REDMOD     PUKCL_RedMod;
    _PUKCL_RNG        PUKCL_Rng;
    _PUKCL_SELFTEST   PUKCL_SelfTest;
    _PUKCL_SMULT      PUKCL_Smult;
    _PUKCL_SQUARE     PUKCL_Square;
    _PUKCL_SWAP       PUKCL_Swap;
    
    // ECC
    _PUKCL_ZPECCADD                   PUKCL_ZpEccAdd;
    _PUKCL_ZPECCDBL                   PUKCL_ZpEccDbl;
    _PUKCL_ZPECCADDSUB                PUKCL_ZpEccAddSub;
    _PUKCL_ZPECCMUL                   PUKCL_ZpEccMul;
    _PUKCL_ZPECDSAGENERATE            PUKCL_ZpEcDsaGenerate;
    _PUKCL_ZPECDSAVERIFY              PUKCL_ZpEcDsaVerify;
    _PUKCL_ZPECDSAQUICKVERIFY         PUKCL_ZpEcDsaQuickVerify;
    _PUKCL_ZPECCQUICKDUALMUL          PUKCL_ZpEccQuickDualMul;
    _PUKCL_ZPECCONVPROJTOAFFINE       PUKCL_ZpEcConvProjToAffine;
    _PUKCL_ZPECCONVAFFINETOPROJECTIVE PUKCL_ZpEcConvAffineToProjective;
    _PUKCL_ZPECRANDOMIZECOORDINATE    PUKCL_ZpEcRandomiseCoordinate;
    _PUKCL_ZPECPOINTISONCURVE         PUKCL_ZpEcPointIsOnCurve;

    // ECC
    _PUKCL_GF2NECCADD                   PUKCL_GF2NEccAdd;
    _PUKCL_GF2NECCDBL                   PUKCL_GF2NEccDbl;
    _PUKCL_GF2NECCMUL                   PUKCL_GF2NEccMul;
    _PUKCL_GF2NECDSAGENERATE            PUKCL_GF2NEcDsaGenerate;
    _PUKCL_GF2NECDSAVERIFY              PUKCL_GF2NEcDsaVerify;
    _PUKCL_GF2NECCONVPROJTOAFFINE       PUKCL_GF2NEcConvProjToAffine;
    _PUKCL_GF2NECCONVAFFINETOPROJECTIVE PUKCL_GF2NEcConvAffineToProjective;
    _PUKCL_GF2NECRANDOMIZECOORDINATE    PUKCL_GF2NEcRandomiseCoordinate;
    _PUKCL_GF2NECPOINTISONCURVE         PUKCL_GF2NEcPointIsOnCurve;
    } P;
} PUKCL_PARAM,

PUKCL_HEADER Structure

The PUKCL_HEADER is common for all services of the library. This header includes standard fields to indicate the requested service, sub-service, options, return status, and so on, as shown in the following tables.

Different terms used in the below description to be understood, are as follows:

Parameter – Represents a variable used by the PUKCL. Every parameter belongs to either PUKCL_HEADER or PUKCL Service Specific Header
Type – Indicates the data type. For details on data type, please refer to CryptoLib_typedef_pb.h file in the library
Dir – Direction. Indicates whether PUKCL considers the variable as input or output. Input means that the application passes data to the PUKCL using the variable. Output means that the PUKCL uses the variable to pass data to the application.
Location – Suggests whether the parameter need to be stored in Crypto RAM or device SRAM. The PUKCL driver has macros for placing parameters into Crypto RAM, so that the user does not have to worry about the addresses
Data Length – If a parameter is a pointer variable, the Data Length column shows the size of the data pointed by the pointer

Table 43-1. PUKCL_HEADER Structure
Parameter	Type	Direction	Location	Data Length	Before Executing the Service	After Executing the Service
u1Service	u1	I	–	–	Required service	Executed service
u1SubService	u1	I	–	–	Required sub-service	Executed sub-service
u2Option	u2	I	–	–	Required option	Executed option
Specific	PUKCL_STATUS	I/O	–	–	See Table 43-2	See Table 43-2
u2Status (see Return Codes)	u2	I/O	–	–	–	Output Status
Reserved	u2	–	–	–	–	–
Reserved	u4	–	–	–	–	–

The Specific field in the PUKCL_HEADER structure is another structure named PUKCL_STATUS. The following table describes this structure. The details of the use of these bits are provided in the individual service descriptions.

PUKCL_STATUS Structure

Members of the PUKCL_STATUS structure are shown in the following table.

Table 43-2. PUKCL_STATUS Structure
Parameter	Type	Direction	Location	Data Length	Before Executing the Service	After Executing the Service
CarryIn (see Note 1)	bit	I	–	–	CarryIn	–
CarryOut	bit	O	–	–	–	CarryOut
Zero	bit	O	–	–	–	1: Result is zero 0: Result is not zero
Gf2n (see Note 1)	bit	I	–	–	Mathematical field 0: Integers (Z_p) 1: Field GF(2ⁿ)	–
Violation	bit	O	–	–	–	Indicates a violation

Note:

Two of these fields must be filled in to avoid problems during computations. If the Gf2n and CarryIn fields are not reset or initialized properly, problems may be encountered during computations. For instance, not initializing the Gf2n field may result in getting a correct mathematical result, but computed over GF(2ⁿ) instead of Z_p.

PUKCL Service Specific Header

Details about each service specific header are provided with service descriptions in a subsequent section. Such structures may contain input or output parameters. A parameter is considered as an input parameter when it used for passing information to the PUKCL, and it is considered as an output parameter when the PUKCL uses it to pass a result back to the application code.

The following code provides the service specific header example for the SelfTest service.

typedef struct _PUKCL_selftest {
	u4 u4Version;
	u4 u4PUKCCVersion;
	u4 u4CheckNum1;
	u4 u4CheckNum2;
	u1 u1Step;
} _PUKCL_SELFTEST;

After the SelfTest service is invoked (with vPUKCL_Process(SelfTest, pvPUKCLParam)), the service specific return values can be checked using pvPUKCLParam.

To check whether the version returned by the PUKCL is correct, the following code can be used.

while (pvPUKCLParam->P.PUKCL_SelfTest.u4Version != PUKCL_VERSION);

In a similar way, other returns can also be accessed.