37.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.
- 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.hfile 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
| 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 the following table PUKCL_STATUS Structure | See the following table PUKCL_STATUS Structure |
| u2Status | 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.
| 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 (Zp) 1: Field GF(2n) |
– |
| Violation | bit | O | – | – | – | Indicates a violation |
- 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(2n) instead of Zp.
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.