ctextra.h library reference

The ProtectToolkit-C SDK offers a number of extended API libraries with functionality that is extended to that of the standard PKCS#11 function set.

The following additional features do not form part of the standard PKCS#11 functionality, but are provided by Thales as part of the SafeNet ProtectToolkit-C API within the ctextra.h library.

AddAttributeSets

Add two attribute sets being careful to drop duplicates. The 'base' attributes will override 'user' attributes where duplicates are concerned. Resulting set is located in *pSum.

Synopsis

CK_RV AddAttributeSets(TOK_ATTR_DATA ** pSum,const TOK_ATTR_DATA * base,const TOK_ATTR_DATA * user);

On successful return

*pSum — reference to a newly allocated attribute set resulting from the addition. This memory needs to be released via a call to FreeAttributeSet.

at_assign

Assign one attribute value to another. Attribute types and lengths have to match up.

Synopsis

CK_RV at_assign(
CK_ATTRIBUTE * tgtNa,
const CK_ATTRIBUTE * srcNa);

To determine the length of tgtNa->pValue required, set tgtNa->pValue to NULL and check tgtNa->valueLen after invocation.

ConcatAttributeSets

Append attributes from the user set to the base set. The 'base' attributes will override 'user' attributes where duplicates are concerned.

Synopsis

CK_RV ConcatAttributeSets(
TOK_ATTR_DATA * base,
const TOK_ATTR_DATA * user);

CopyAttribute

Make a copy of an attribute from one attribute set to another. Only copy it if it is in 'src'. Overwrite it if it is in 'tgt'. Returns reference to the copied attribute in tgt attribute set.

Synopsis

CK_ATTRIBUTE * CopyAttribute(
CK_ATTRIBUTE_TYPE at,
TOK_ATTR_DATA * tgt,
const TOK_ATTR_DATA * src);

On successful return

tgt — contains value of the specified attribute from src

DupAttributes

Make a copy of an array of attributes. The returned attribute set is newly allocated. This memory needs to be released via a call to FreeAttributeSet.

Synopsis

TOK_ATTR_DATA * DupAttributes(
const CK_ATTRIBUTE * attr,
CK_COUNT attrCount);

DupAttributeSet

Make a copy of an attribute set. The returned attribute set is newly allocated. This memory needs to be released via a call to FreeAttributeSet. Synopsis

TOK_ATTR_DATA * DupAttributeSet(
const TOK_ATTR_DATA * attrData);

ExtractAllAttributes

Extract all non-sensitive valid attributes of an object.

Synopsis

CK_RV ExtractAllAttributes(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hobj,
TOK_ATTR_DATA ** pna);

On successful return

*pna — newly allocated attribute set of extracted attributes; this memory needs to be freed (see FreeAttributeSet)

FindAttr

Find the first attribute of the specified type in an attribute set.

Synopsis

CK_ATTRIBUTE * FindAttr(CK_ATTRIBUTE_TYPE attrType,const TOK_ATTR_DATA * attrData);

On successful return

Return a pointer to the attribute of the specified type.

FreeAttributes

Free all attributes contained in the attribute array, then free the array itself. This function also explicitly writes 0xaa to the memory to be freed before freeing.

Synopsis

void FreeAttributes(
CK_ATTRIBUTE_PTR attr,
CK_COUNT attrCount);

FreeAttributeSet

Free all of the attributes contained in the attribute set, and then free the set itself. This function also explicitly writes 0xaa to the memory to be freed before freeing.

Synopsis

void FreeAttributeSet(
TOK_ATTR_DATA * attr);

FreeAttributesNoClear

Free all attributes contained in the attribute array, then free the array itself. This function does not explicitly write 0xaa to the memory to be freed before freeing.

Synopsis

void FreeAttributesNoClear(
CK_ATTRIBUTE_PTR attr,
CK_COUNT attrCount);

FreeMechData

Free dynamic memory of pMech, including pMech itself.

Synopsis

void FreeMechData(
TOK_MECH_DATA * pMech);

genkMechanismTabFromMechanismTab

Creates a key generation mechanism table for the list of mechanisms supplied in mTab

Synopsis

CK_MECHANISM_TYPE * genkMechanismTabFromMechanismTab(

TOK_MECH_DATA * mTab,

unsigned int * len);

genkpMechanismTabFromMechanismTab

Creates a key pair generation mechanism table for the list of mechanisms supplied in mTab.

Synopsis

CK_MECHANISM_TYPE * genkpMechanismTabFromMechanismTab(TOK_MECH_DATA * mTab,unsigned int * len);

genMechanismTabFromMechanismTab

Creates a mechanism table for the list of mechanisms supplied in mTab.

Synopsis

CK_MECHANISM_TYPE * genMechanismTabFromMechanismTab(

TOK_MECH_DATA * mTab,

unsigned int * len);

GetCryptokiVersion

Returns the Cryptoki version information.

Synopsis

CK_VOID GetCryptokiVersion(CK_VERSION_PTR pVer);

On successful return

pVer — pointer to a value which holds Cryptoki version

GetObjAttrInfo

Get the list of attributes (type and size) of the specified object.

This function relies on the SafeNet extension CKA_ENUM_ATTRIBUTES to retrieve the list of attributes. Only the attribute type and size are returned. Attribute values must be retrieved by the caller as required.

Synopsis

CK_RV GetObjAttrInfo(CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObj,
CK_ATTRIBUTE_PTR* ppAttributes,
CK_ULONG_PTR pAttrCount);

On successful return

*ppAttributes — handle that points to the returned attributes

pAttrCount — number of returned attributes

GetObjectClassAndKeyType

Extract the object class and key type from an attribute set.

Synopsis

CK_RV GetObjectClassAndKeyType(
const TOK_ATTR_DATA * attr,
CK_OBJECT_CLASS * at_class,
CK_KEY_TYPE * kt);

On successful return

at_class — references located object class

kt — references located key type

hashMech

Return an array of all related mechanisms.

Synopsis

CK_MECHANISM_TYPE * hashMech(
unsigned int * len);

intAttr

Return the value of the attribute as an int.

Synopsis

unsigned int intAttr(
const CK_ATTRIBUTE * at);

intAttrLookup

Extract an int attribute from an attribute template.

Synopsis

unsigned int intAttrLookup(CK_ATTRIBUTE_TYPE atype,const CK_ATTRIBUTE * attr,CK_COUNT attrCount);

isBooleanAttr

Return TRUE if an attribute is a Boolean.

Synopsis

int isBooleanAttr(const CK_ATTRIBUTE * na);

isEnumeratedAttr

Return TRUE if attribute is enumerated and can have vendor-defined values.

Synopsis

int isEnumeratedAttr(
const CK_ATTRIBUTE * na);

isGenMech

Return TRUE if mechType is a key or key pair generation mechanism.

Synopsis

int isGenMech(
CK_MECHANISM_TYPE mechType);

isNumericAttr

Return TRUE if an attribute is a numeric.

Synopsis

int isNumericAttr(const CK_ATTRIBUTE * na);

isSensitiveAttr

Report TRUE for potentially sensitive attributes, as per the PKCS#11 spec. Note that the object has to be marked sensitive for this to have any effect.

ProtectToolkit-C extension: all objects have the CKA_VALUE as sensitive if the object has CKA_SENSITIVE set to TRUE. This is useful for objects that are used internally only, or just wrapped for transmission elsewhere.

Synopsis

int isSensitiveAttr(
const struct TOK_ATTR_DATA * attrData,
const CK_ATTRIBUTE * na);

KeyFromPin

Generate a double length key from a PIN, using PKCS#5 password based encryption.

Synopsis

void KeyFromPin(
unsigned char key[16],
unsigned int klen,
CK_USER_TYPE user,
const unsigned char * pin,
unsigned int pinLen);

On successful return

key — contains the generated key

kgMech

Return an array of all key generation related mechanisms.

Synopsis

CK_MECHANISM_TYPE * kgMech(
unsigned int * len);

kpgMech

Return an array of all key pair generation related mechanisms.

Synopsis

CK_MECHANISM_TYPE * kpgMech(
unsigned int * len);

ktFromMech

Return an array of key types valid for the given mechanism. The returned array does not need to be freed.

Synopsis

CK_KEY_TYPE * ktFromMech(
CK_MECHANISM_TYPE mt,
unsigned int * len);

On successful return

*len number of items in returned array

LookupMech

Return TRUE if mechType is in the pMech list.

Synopsis

int LookupMech(
TOK_MECH_DATA * pMech,
CK_MECHANISM_TYPE mechType);

MatchAttributeSet

Do a comparison of two attribute sets. Every attribute in the 'match' set must be found in the 'ad' set. It is OK if 'ad' is a super set of 'match'. Return TRUE if all attributes in 'match' were found in 'ad'.

Synopsis

int MatchAttributeSet(
const TOK_ATTR_DATA * match,
const TOK_ATTR_DATA * ad);

mechDeriveFromKt

Return an array of derive mechanisms valid for the given key type. The returned array is newly allocated and needs to be freed.

Synopsis

CK_MECHANISM_TYPE * mechDeriveFromKt(CK_KEY_TYPE kt,unsigned int * len);

On successful return

Array of CK_MECHANISM_TYPE values or NULL if key type is invalid. Caller should free the array when finished.

mechFromKt

Return an array of mechanisms valid for the given key type. The returned array is newly allocated and needs to be freed.

Synopsis

CK_MECHANISM_TYPE * mechFromKt(
CK_KEY_TYPE kt,
unsigned int * len);

On successful return

Array of CK_MECHANISM_TYPE values or NULL if key type is invalid. Caller should free the array when finished.

mechFromTokKt

Return an array of mechanisms valid for the given key type. The returned array is newly allocated and needs to be freed.

Synopsis

CK_MECHANISM_TYPE * mechFromTokKt(
TOK_MECH_DATA * mTab,

CK_KEY_TYPE kt,
unsigned int * len);

On successful return

Array of CK_MECHANISM_TYPE values or NULL if key type is invalid. Caller should free the array when finished.

mechSignFromKt

Return an array of signing mechanisms valid for the given key type. The returned array is newly allocated and needs to be freed.

Synopsis

CK_MECHANISM_TYPE * mechSignFromKt(CK_KEY_TYPE kt,unsigned int * len);

On successful return

Array of CK_MECHANISM_TYPE values or NULL if key type is invalid. Caller should free the array when finished.

mechSignRecFromKt

Return an array of signing mechanisms valid for the given key type. The returned array is newly allocated and needs to be freed.

Synopsis

CK_MECHANISM_TYPE * mechSignRecFromKt(CK_KEY_TYPE kt,unsigned int * len);

On successful return

Array of CK_MECHANISM_TYPE values or NULL if key type is invalid. Caller should free the array when finished.

NewAttributeSet

Allocate memory for an attribute set to hold the specified number of attributes. The returned memory needs to be freed (see FreeAttributeSet)

Synopsis

TOK_ATTR_DATA * NewAttributeSet(
unsigned int count);

numAttr

Return the value of the attribute as a numeric.

Synopsis

CK_NUMERIC numAttr(
const CK_ATTRIBUTE * at);

numAttrLookup

Extract a numeric attribute from an attribute template.

Synopsis

CK_NUMERIC numAttrLookup(CK_ATTRIBUTE_TYPE atype,const CK_ATTRIBUTE * attr,CK_COUNT attrCount);

NUMITEMS

This is a macro that returns the number of elements in an array.

Note

Only array definitions can be sized by this macro, not pointer definitions.

It is used wherever object templates are defined since the number of items in the template is always passed along with the template address into Cryptoki functions. Use of this macro is preferred to hard coding the number of items in the template that may change with code maintenance.

Synopsis

#define NUMITEMS(type)  (sizeof((type))/sizeof((type)[0]))

PvcFromPin

Create a PVC from a PIN using PKCS#5 password based encryption.

Synopsis

void PvcFromPin(unsigned char * key,unsigned int klen,CK_USER_TYPE user,const unsigned char * pin,unsigned int pinLen);

On successful return

key — contains the pvc

ReadAttr

Read an attribute value from an attribute set. Return TRUE if the attribute was present.

Synopsis

int ReadAttr(
void * buf,
unsigned int len,
unsigned int * plen,
CK_ATTRIBUTE_TYPE attrType,
const TOK_ATTR_DATA * attr);

On successful return

buf — contains attribute value

plen — references number of bytes copied into buf

slotIDfromSes

Extract a CK_SLOT_ID from a CK_SESSION_HANDLE. This function only works with SafeNet’s Cryptoki product because it includes an encoding of the SLOT id in the session handle. For other PKCS#11 implementations the slot ID can be obtained from the session info C_GetSessionInfo() call.

Synopsis

CK_SLOT_ID slotIDfromSes(CK_SESSION_HANDLE h);

TransferAttr

Using at_assign, copy attribute values from one array to another. The order of the attributes must be the same in both arrays.

Synopsis

CK_RV TransferAttr(
CK_ATTRIBUTE * pTgtTemplate,
const CK_ATTRIBUTE * pSrcTemplate,
CK_COUNT attrCount);

On successful return

pTgtTemplate — contains copy of attribute values from pSrcTemplate

UnwrapDec

Unwrap a key and decode its attributes.

Synopsis

int UnwrapDec(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hUnwrapper,
CK_OBJECT_HANDLE * hUnwrappedKey,
unsigned char * buf,
unsigned int bufLen);

On successful return

*hUnwrappedKey — handle to unwrapped key with attributes

WrapEnc

Wrap a key, encode its attributes and write it to a buffer.

Synopsis

int WrapEnc (
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hWrapper,
CK_OBJECT_HANDLE hWrappee,
unsigned char * buf,
unsigned int bufLen,
CK_SIZE * bytesWritten);

On successful return

buf — contains the wrapped key and encoded attributes *bytesWritten number of bytes written to buf

WriteAttr

Add/Replace an attribute to an attribute set. Delete attribute if len is 0.

Synopsis

CK_RV WriteAttr(
const void * buf,
unsigned int len,
CK_ATTRIBUTE_TYPE attrType,
TOK_ATTR_DATA * attr);

On successful return

attr — modified attribute set