KMLIB Callback Prototypes Reference
This chapter contains descriptions of the following callback prototypes:
Example of Callback Prototype Use
The following code demonstrates callback prototype use using the PromptString callback.
/** Function prototype */
static CK_RV PromptString(
const char *pszMessage,
char *pBuf, CK_ULONG *pBufLen
);
/** Function implementation */
static CK_RV PromptString(
const char* pszMessage,
char* pBuf,
CK_ULONG* pBufLen
);
{
CK_RV rv = CKR_OK;
printf("%s", pszMessage);
ReadLine(pBuf, *pBufLen);
return rv;
}
int main(void){
:
:
KM_Callbacks_t km_callbacks;
memset(&km_callbacks, 0, sizeof(km_callbacks));
km_callbacks.promptString = PromptString;
:
}
UICB_PromptConfirmation_t
This function will prompt the user for confirmation of an action, as specified in pszMessage.
If cancellable is TRUE, user is given the option to cancel, as well as YES/NO. The choice is returned in pResult.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptConfirmation_t)( const char * pszMessage, CK_BBOOL bCancellable, UICB_ConfirmResult_t * pResult );
| Parameter | Description |
|---|---|
| pszMessage | Message used to prompt the user for their choice |
| bCancellable | Specifies whether to give user the option to cancel |
| pResult | Choice, as selected by the user |
UICB_PromptForSmartCard_t
Prompt and wait for a smart card to be entered in the specified slot.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptForSmartCard_t)( CK_SLOT_ID cardSlotId, const char * pszMessage, const char * pszPrompt );
| Parameters | Description |
|---|---|
| cardSlotId | ID of the slot to wait for the smart card. |
| pszMessage | The message to display. |
| pszPrompt | The prompt to display. |
UICB_PromptInt32_t
This function will prompt the user for an integer, as specified in pszMessage.
The number entered is returned in pInt.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptInt32_t)( const char * pszMessage, CK_ULONG * pUlong );
| Parameter | Description |
|---|---|
| pszMessage | Message used to prompt the user for the integer. |
| pUlong | Pointer to a CK_ULONG, which upon successful completion of this function, will contain the integer as entered by the user. |
UICB_PromptKeyComponent_t
Prompt for a key component from the user and verify its KCV. It is up to the library to convert the hex string entered as the key component to binary.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptKeyComponent_t)( int compNum, int numComps, char * pKeyComp, int * pKeyCompLen );
| Parameter | Description |
|---|---|
| compNum | The number of the key component to get. |
| numComps | The number of key components to get. |
| pKeyComp | Location to store the verified key component. |
| pKeyCompLen | Location to store the length of the key component. |
UICB_PromptPin_t
This function will prompt the user for the PIN of the specified user on the given slot.
The result is returned in the pPin parameter. The number of CK_CHARs copied into pPin is returned in pPinLen, which is also used as input to the function. If the number of CK_CHARs entered is larger than the number passed in pPinLen, the function will return CKR_BUFFER_TOO_SMALL and the required size will be returned in pPinLen.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptPin_t)( CK_SLOT_ID slotId, CK_BBOOL fConfirm, CK_USER_TYPE userType, CK_CHAR * pPin, CK_ULONG * pPinLen );
| Parameter | Description |
|---|---|
| slotId | ID of the slot for which to prompt for the PIN. |
| fConfirm | Flag to indicate whether or not to confirm entered PIN. |
| userType | User whose PIN should be prompted for. |
| pPin | Pointer to buffer to accept PIN as entered by the user. |
| pPinLen | Pointer to a CK_ULONG specifying the length of the buffer. Upon successful completion of the function, the CK_ULONG will contain either the number of bytes copied into pPin, or the length required to hold the entered PIN. |
UICB_PromptString_t
This function will prompt the user for a string, as specified in pszMessage.
The result is returned in the pszBuf parameter. The number of CK_CHARs copied into pszBuf is returned in pBufLen, which is also used as input to the function. If the number of CK_CHARs entered is larger than the number passed in in pBufLen, the function will return CKR_BUFFER_TOO_SMALL and the required size will be returned in pBufLen.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptString_t)( const char * pszMessage, char * pBuf, CK_ULONG * pBufLen );
| Parameter | Description |
|---|---|
| pszMessage | Message used to prompt the user for the string. |
| pBuf | Pointer to buffer to accept string as entered by the user. |
| pBufLen | Pointer to the length of the buffer to accept the entered string. Upon successful completion of the function, the CK_ULONG will contain either the number of bytes copied into pPin, or the length required to hold the entered string. |
UICB_PromptTokenPin_t
Prompt for a PIN.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_PromptTokenPin_t)( const char *pszMessage, CK_CHAR *pPIN, int *pPinLen );
| Parameter | Description |
|---|---|
| pszMessage | The message to display when prompting for the PIN. |
| pPIN | Location to hold the PIN entered. |
| pPinLen | Location to hold the length of the entered PIN. |
UICB_ShowExportHeader_t
Show the current smart card batch name and user number.
Synopsis
#include < uicallbacks.h >
void(* UICB_ShowExportHeader_t)( const char * pszBatchName, int custodianNumber );
| Parameter | Description |
|---|---|
| pszBatchName | The name of the current batch. |
| custodianNumber | Number of the current custodian. |
UICB_ShowImportHeader_t
Show the current smart card batch name and user number.
Synopsis
#include < uicallbacks.h >
void(* UICB_ShowImportHeader_t)( const char * pszBatchName, const char * pszUserName );
| Parameter | Description |
|---|---|
| pszBatchName | The name of the current batch. |
| pszUserName | The name of the user who owns the card. |
UICB_ShowKeyComponent_t
Display a key component and KCV.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_ShowKeyComponent_t)( int compNum, int numComps, const char * pKeyComp, const char * pKCV );
| Parameter | Description |
|---|---|
| compNum | The current key component number. |
| numComps | The number of components to display. |
| pKeyComp | The key component to display. |
| pKCV | The KCV of the component to display. |
UICB_ShowMsg_t
This function will display a message to the user as specified in pszMessage.
Synopsis
#include < uicallbacks.h >
void(* UICB_ShowMsg_t)( UICB_MsgType_t msgType, const char * pszMessage );
| Parameter | Description |
|---|---|
| pszMessage | Message to display. |
| msgType | Type of message to display. |
UICB_ShowSCBatchInfo_t
Show smart card batch information.
Synopsis
#include < uicallbacks.h >
CK_RV(* UICB_ShowSCBatchInfo_t)( const char * pszBatchName, const unsigned long timeCreated, const unsigned long cardNumber, const unsigned long numCustodians, const unsigned long custodianNumber, const char * pszUserName, const double percentageOfEks );
| Parameter | Description |
|---|---|
| pszBatchName | Name of the batch that this card belongs to. |
| timeCreated | Time this card was created. |
| cardNumber | Card number within the batch of this card. |
| numCustodians | Number of custodians within the batch. |
| custodianNumber | Number of this custodian. |
| pszUserName | Name of the user that 'owns' this card. |
| percentageOfEks | Percentage of the entire eks that has been stored on this card. |
