The functions listed in this section allow the FM to ask the firmware to associate user data with certain firmware structures. The firmware guarantees cleanup of the associated buffer when the structure in question is destroyed.

The freeing of the user data is performed by a callback to a user function. If the data is allocated using malloc(), and it contains no pointers to other allocated structures, the free function is typically the standard free() function.

>FM_SetAppUserData

>FM_GetAppUserData

>FM_SetSlotUserData

>FM_GetSlotUserData

>FM_SetTokenUserData

>FM_GetTokenUserData

>FM_SetTokenAppUserData

>FM_GetTokenAppUserData

>FM_SetSessionUserData

>FM_GetSessionUserData

FM_SetAppUserData

This function can be used to associate user data with the calling application. The data is associated with the PID of the calling application. The function specified in this call will be called to free the data when the last application using the library finalizes (e.g. when it calls C_Finalize()).

If the application already has associated user data, it will be freed (by calling the current free function) before the new data association is created.

Synopsis

#include <objstate.h>
CK_RV FM_SetAppUserData(FmNumber_t fmNo,
CK_VOID_PTR userData,
CK_VOID (*freeUserData)(CK_VOID_PTR));

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
userData	Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed.
freeUserData	Address of a function that will be called to free the userData if the library decides that it should be freed. it must be non-NULL if userData is not NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: freeUserData was NULL, when userData was not NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_GetAppUserData

This function is used to obtain the userData associated with the current application. If there are no associated buffers, NULL is returned in ppUserData.

Synopsis

#include <objstate.h>
CK_RV FM_SetAppUserData(FmNumber_t fmNo,
CK_VOID_PTR_PTR ppuserData);

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
ppuserData	Address of a variable (of type CK_Void_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL.

Return Code

CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.

CKR_ARGUMENTS_BAD: ppUserData was NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_SetSlotUserData

This function can be used to associate user data with a slot. The data is associated with the slot identified by slotId. The function specified in this call will be called to free the data when the last application using the library finalizes.

If the slot already has associated user data it will be freed, by calling the current free function, before the new data association is created.

Synopsis

#include <objstate.h>
CK_RV FM_SetSlotUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID of the slot.
userData	Address of the memory block that will be associated with the session handle. If it is NULL, the current associated buffer is freed.
freeUserData	Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: freeUserData was NULL, when userData was not NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_GetSlotUserData

This function is used to obtain the userData associated with the specified slot. if there are no associated buffers, NULL is returned in ppUserData. 

Synopsis

#include <objstate.h>
CK_RV FM_GetSlotUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID_PTR_PTR ppUserData);

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID indicating the slot to be used.
ppuserData	Address of a variable (of type CK_Void_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL.

Return Code

CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.

CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SLOT_ID_INVALID: The specified slot ID is invalid.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_SetTokenUserData

This function can be used to associate user data with a token. The data is associated with the token in slotId by the library. The function specified in this call will be called to free the data when the last application using the library finalizes, or when the token is removed from that slot.

If the token already has associated user data it will be freed, by calling the current free function, before the new data association is created.

Synopsis

#include <objstate.h>
CK_RV FM_SetTokenUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID of the slot containing the token.
userData	Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed.
freeUserData	Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SLOT_ID_INVALID: The specified slot ID is invalid.

CKR_TOKEN_NOT_PRESENT: The specified slot does not contain a token.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_GetTokenUserData

This function is used to obtain the userData associated with the specified token. If there are no associated buffers, or if the token is not present, NULL is returned in ppUserData.

Synopsis

#include <objstate.h>
CK_RV FM_GetTokenUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR_PTR ppUserData);

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID of the slot containing the token.
ppuserData	Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SLOT_ID_INVALID: The specified slot ID is invalid.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_SetTokenAppUserData

This function can be used to associate user data with a token in the context of the calling application. The data is associated with the token (token, PID) pair. The function specified in this call will be called to free the data when the last application using the library finalizes, or when the token is removed from that slot.

If the token already has associated user data it will be freed, by calling the current free function, before the new data association is created.

Synopsis

#include <objstate.h>
CK_RV FM_SetTokenAppUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID of the slot containing the token.
userData	Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed.
freeUserData	Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SLOT_ID_INVALID: The specified slot ID is invalid.

CKR_TOKEN_NOT_PRESENT: The specified slot does not contain a token.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_GetTokenAppUserData

This function is used to obtain the userData associated with the specified token in the application context. If there are no associated buffers, or if the token is not present, NULL is returned in ppUserData.

Synopsis

#include <objstate.h>
CK_RV FM_GetTokenAppUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR_PTR ppUserData);

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
slotId	The slot ID of the slot containing the token.
ppuserData	Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SLOT_ID_INVALID: The specified slot ID is invalid.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_SetSessionUserData

This function can be used to associate user data with a session handle. The data is associated with the (PID, hSession) pair by the library. The function specified in this call will be called to free the user data if the session is closed (via a C_CloseSession() or a C_CloseAllSessions() cal), or the application owning the session finalizes.

If the session handle already contains user data it will be freed, by calling the current free function, before the new data association is created.

Synopsis

#include <objstate.h>
CK_RV FM_SetSessionUserData(FmNumber_t fmNo,
CK_SESSION_HANDLE hSession,
CK_VOID_PTR userData,
CK_VOID (*freeUserData)(CK_VOID_PTR));

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
hSession	A session handle, which was obtained from an C_OpenSession() call. The validity of this parameter is checked.
userData	Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed.
freeUserData	Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL.

Return Code

CKR_OK: The operation was successful.

CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SESSION_HANDLE_INVALID: The specified session handle is invalid.

CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.

FM_GetSessionUserData

This function is used to obtain the userData associated with the specified session handle. If there are no associated buffers, NULL is returned in ppUserData.

Synopsis

#include <objstate.h>
CK_RV FM_GetSessionUserData(FmNumber_t fmNo,
CK_SESSION_HANDLE hSession,
CK_VOID_PTR_PTR ppUserData);

Parameter	Description
fmNo	The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software.
hSession	A session handle, which was obtained from an C_OpenSession() call. The validity of this parameter is checked.
ppuserData	Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL.

Return Code

CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.

CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.

CKR_SESSION_HANDLE_INVALID: hSession is not a valid session handle.