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);
| Parameter | Description |
|---|---|
| pSum | Reference to addition of base and user sets |
| base | Attribute set to add to user set |
| user | Attribute set to add to base set |
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);
| Parameter | Description |
|---|---|
| tgtNa | Target attribute |
| srcNa | Source attribute |
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);
| Parameter | Description |
|---|---|
| base | Reference to attribute set to append to |
| user | Reference to attribute set to append |
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);
| Parameter | Description |
|---|---|
| at | Attribute to copy |
| tgt | Target attribute set |
| src | Source attribute set |
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);
| Parameter | Description |
|---|---|
| attr | Attribute array to duplicate |
| attrCount | Number of attributes in attr |
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);
| Parameter | Description |
|---|---|
| attrData | Attribute set to duplicate |
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);
| Parameter | Description |
|---|---|
| hSession | Open session handle |
| hObj | Object to extract from |
| pna | Reference to a reference to extracted attribute set |
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);
| Parameter | Description |
|---|---|
| attrType | Type of attribute to locate |
| attrData | Attribute set |
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);
| Parameter | Description |
|---|---|
| attr | Attribute array to free |
| attrCount | Number of attributes in the array |
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);
| Parameter | Description |
|---|---|
| attr | Reference to the attribute set to free |
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);
| Parameter | Description |
|---|---|
| attr | Attribute array to free |
| attrCount | Number of attributes in the array |
FreeMechData
Free dynamic memory of pMech, including pMech itself.
Synopsis
void FreeMechData(
TOK_MECH_DATA * pMech);
| Parameter | Description |
|---|---|
| pMech | Mechanism list to free |
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);
| Parameter | Description |
|---|---|
| mTab | Number of mechanisms to look up |
| len | Number of returned mechanisms |
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);
| Parameter | Description |
|---|---|
| mTab | List of mechanisms to look up |
| len | Number of returned mechanisms |
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);
| Parameter | Description |
|---|---|
| mTab | List of mechanisms to look up |
| len | Number of returned mechanisms |
GetCryptokiVersion
Returns the Cryptoki version information.
Synopsis
CK_VOID GetCryptokiVersion(CK_VERSION_PTR pVer);
| Parameter | Description |
|---|---|
| pVer | Returned Cryptoki version |
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);
| Parameter | Description |
|---|---|
| hSession | Handle to a valid session |
| hObj | Handle to the object to operate on |
| ppAttributes | Location to receive the attribute array (on return, ppAttributes references an array of CK_ATTRIBUTE - the caller must free the memory allocated at ppAttributes). |
| pAttrCount | Location to hold the number of CK_ATTRIBUTE entries (on return, pAttrCount is the number of CK_ATTRIBUTE entries referenced by ppAttributes). |
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);
| Parameter | Description |
|---|---|
| attr | Attribute set to extract from |
| at_class | Reference to object class to hold resulting value |
| kt | Reference to key type to hold resulting value |
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);
| Parameter | Description |
|---|---|
| len | Reference to int to hold the number of items returned |
intAttr
Return the value of the attribute as an int.
Synopsis
unsigned int intAttr(
const CK_ATTRIBUTE * at);
| Parameter | Description |
|---|---|
| at | Reference to attribute whose value is to be returned |
intAttrLookup
Extract an int attribute from an attribute template.
Synopsis
unsigned int intAttrLookup(CK_ATTRIBUTE_TYPE atype,const CK_ATTRIBUTE * attr,CK_COUNT attrCount);
| Parameter | Description |
|---|---|
| atype | Type of attribute to extract attr array of attributes to search attrCount number of attributes in attr array |
isBooleanAttr
Return TRUE if an attribute is a Boolean.
Synopsis
int isBooleanAttr(const CK_ATTRIBUTE * na);
| Parameter | Description |
|---|---|
| na | Reference to attribute to check |
isEnumeratedAttr
Return TRUE if attribute is enumerated and can have vendor-defined values.
Synopsis
int isEnumeratedAttr(
const CK_ATTRIBUTE * na);
| Parameter | Description |
|---|---|
| na | Reference to attribute to check |
isGenMech
Return TRUE if mechType is a key or key pair generation mechanism.
Synopsis
int isGenMech(
CK_MECHANISM_TYPE mechType);
| Parameter | Description |
|---|---|
| mechType | Mechanism type to check |
isNumericAttr
Return TRUE if an attribute is a numeric.
Synopsis
int isNumericAttr(const CK_ATTRIBUTE * na);
| Parameter | Description |
|---|---|
| na | Reference to attribute to check |
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);
| Parameter | Description |
|---|---|
| na | Reference to attribute to check |
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);
| Parameter | Description |
|---|---|
| key | Buffer to hold generated key |
| keylen | Number of bytes in key (should be 16) |
| user | Salt value for key generation |
| pin | Password used for key generation |
| pinLen | Number of bytes referenced by pin |
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);
| Parameter | Description |
|---|---|
| mechType | Reference to int to hold the number of items returned |
kpgMech
Return an array of all key pair generation related mechanisms.
Synopsis
CK_MECHANISM_TYPE * kpgMech(
unsigned int * len);
| Parameter | Description |
|---|---|
| len | Reference to int to hold the number of items returned |
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);
| Parameter | Description |
|---|---|
| mt | Mechanism type to get key types for |
| len | Reference to int to hold the number of items in returned array |
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);
| Parameters | Description |
|---|---|
| pMech | Reference to mechanism list |
| mechType | Mechanism to look for in pMech list |
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);
| Parameter | Description |
|---|---|
| match | Attribute set to look for |
| ad | Attribute set to compare to |
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);
| Parameter | Description |
|---|---|
| kt | Key type to look up |
| len | Pointer to integer that receives length of returned array |
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);
| Parameter | Description |
|---|---|
| kt | Key type to get mechanisms for |
| len | Reference to int to hold number of items in returned array |
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);
| Parameter | Description |
|---|---|
| mTab | List of mechanisms to look up |
| kt | Key type to get mechanisms for |
| len | Reference to int to hold number of items in returned array |
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);
| Parameter | Description |
|---|---|
| kt | Key type to get mechanisms for |
| len | Reference to int to hold number of items in returned array |
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);
| Parameter | Description |
|---|---|
| kt | Key type to get mechanisms for |
| len | Reference to int to hold number of items in returned array |
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);
| Parameter | Description |
|---|---|
| count | Number of attribute place holders to allocate in the set |
numAttr
Return the value of the attribute as a numeric.
Synopsis
CK_NUMERIC numAttr(
const CK_ATTRIBUTE * at);
| Parameter | Description |
|---|---|
| at | Reference to attribute whose value is to be returned |
numAttrLookup
Extract a numeric attribute from an attribute template.
Synopsis
CK_NUMERIC numAttrLookup(CK_ATTRIBUTE_TYPE atype,const CK_ATTRIBUTE * attr,CK_COUNT attrCount);
| Parameter | Description |
|---|---|
| atype | Type of attribute to extract attr array of attributes to search |
| attrCount | Number of attributes in attr array |
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);
| Parameter | Description |
|---|---|
| key | Resulting pvc |
| klen | Number of bytes referenced by key |
| user | Salt value |
| pin | Password |
| pinLen | Number of bytes referenced by pin |
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);
| Parameter | Description |
|---|---|
| buf | Buffer to receive attribute value |
| len | Number of bytes referenced by buf |
| plen | Reference to int to hold number of bytes copied to buf |
| attrType | Type of attribute to extract from attr |
| attr | Attribute set to search |
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);
| Parameter | Description |
|---|---|
| pTgtTemplate | Target attribute array |
| pSrcTemplate | Source attribute array |
| attrCount | Number of attributes to copy from source to target |
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);
| Parameter | Description |
|---|---|
| hSession | Open session handle |
| hUnwrapper | Handle to unwrapping key |
| hUnwrappedKey | Reference to handle to the key unwrapped |
| buf | Reference to bytes containing the key and attributes |
| bufLen | Number of bytes referenced by buf |
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);
| Parameter | Description |
|---|---|
| hSession | Open session handle |
| hWrapper | Handle to wrapping key |
| hWrappee | Wrappee handle to the key to wrap |
| buf | Reference to bytes to hold the result |
| bufLen | Number of bytes referenced by buf |
| bytesWritten | Reference to value to hold the number of bytes written to buf |
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);
| Parameter | Description |
|---|---|
| buf | Value to add to attribute set |
| len | Number of bytes to add from buf |
| attrType | Type of attribute to add |
| attr | Attribute set to modify |
On successful return
attr — modified attribute set
