Cryptographic Token Interface Standard

PKCS#11

---

Locking-related types

The types in this section are provided solely for applications which need to access Cryptoki from multiple threads simultaneously. Applications which will not do this need not use any of these types.

CK_CREATEMUTEX

CK_CREATEMUTEX is the type of a pointer to an application-supplied function which creates a new mutex object and returns a pointer to it. It is defined as follows:

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_CREATEMUTEX)(
CK_VOID_PTR_PTR ppMutex
);

Calling a CK_CREATEMUTEX function returns the pointer to the new mutex object in the location pointed to by ppMutex. Such a function should return one of the following values: CKR_OK, CKR_GENERAL_ERROR, CKR_HOST_MEMORY.

CK_DESTROYMUTEX

CK_DESTROYMUTEX is the type of a pointer to an application-supplied function which destroys an existing mutex object. It is defined as follows:

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_DESTROYMUTEX)(
CK_VOID_PTR pMutex
);

The argument to a CK_DESTROYMUTEX function is a pointer to the mutex object to be destroyed. Such a function should return one of the following values: CKR_OK, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MUTEX_BAD.

CK_LOCKMUTEX and CK_UNLOCKMUTEX

CK_LOCKMUTEX is the type of a pointer to an application-supplied function which locks an existing mutex object. CK_UNLOCKMUTEX is the type of a pointer to an application-supplied function which unlocks an existing mutex object. The proper behavior for these types of functions is as follows:

• If a CK_LOCKMUTEX function is called on a mutex which is not locked, the calling thread obtains a lock on that mutex and returns.
• If a CK_LOCKMUTEX function is called on a mutex which is locked by some thread other than the calling thread, the calling thread blocks and waits for that mutex to be unlocked.
• If a CK_LOCKMUTEX function is called on a mutex which is locked by the calling thread, the behavior of the function call is undefined.
• If a CK_UNLOCKMUTEX function is called on a mutex which is locked by the calling thread, that mutex is unlocked and the function call returns. Furthermore:
• If exactly one thread was blocking on that particular mutex, then that thread stops blocking, obtains a lock on that mutex, and its CK_LOCKMUTEX call returns.
• If more than one thread was blocking on that particular mutex, then exactly one of the blocking threads is selected somehow. That lucky thread stops blocking, obtains a lock on the mutex, and its CK_LOCKMUTEX call returns. All other threads blocking on that particular mutex continue to block.
• If a CK_UNLOCKMUTEX function is called on a mutex which is not locked, then the function call returns the error code CKR_MUTEX_NOT_LOCKED.
• If a CK_UNLOCKMUTEX function is called on a mutex which is locked by some thread other than the calling thread, the behavior of the function call is undefined. CK_LOCKMUTEX is defined as follows:

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_LOCKMUTEX)(
CK_VOID_PTR pMutex
);

The argument to a CK_LOCKMUTEX function is a pointer to the mutex object to be locked. Such a function should return one of the following values: CKR_OK, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MUTEX_BAD.

CK_UNLOCKMUTEX is defined as follows:

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_UNLOCKMUTEX)(
CK_VOID_PTR pMutex
);

The argument to a CK_UNLOCKMUTEX function is a pointer to the mutex object to be unlocked. Such a function should return one of the following values: CKR_OK, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MUTEX_BAD, CKR_MUTEX_NOT_LOCKED.

CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR

CK_C_INITIALIZE_ARGS is a structure containing the optional arguments for the C_Initialize function. For this version of Cryptoki, these optional arguments are all concerned with the way the library deals with threads. CK_C_INITIALIZE_ARGS is defined as follows:

typedef struct CK_C_INITIALIZE_ARGS {
CK_CREATEMUTEX CreateMutex;
CK_DESTROYMUTEX DestroyMutex;
CK_LOCKMUTEX LockMutex;
CK_UNLOCKMUTEX UnlockMutex;
CK_FLAGS flags;
CK_VOID_PTR pReserved;
} CK_C_INITIALIZE_ARGS;

CreateMutex	pointer to a function to use for creating mutex objects
DestroyMutex	pointer to a function to use for destroying mutex objects
LockMutex	pointer to a function to use for locking mutex objects
UnlockMutex	pointer to a function to use for unlocking mutex objects
flags	bit flags specifying options for '''C_Initialize'''; the flags are defined below
pReserved	reserved for future use. Should be NULL_PTR for this version of Cryptoki

The following table defines the flags field:

Table 14, C_Initialize Parameter Flags

Bit Flag	Mask	Meaning
CKF_LIBRARY_CANT_CREATE_OS_THREADS	0x00000001	True if application threads which are executing calls to the library may not use native operating system calls to spawn new threads; false if they may
CKF_OS_LOCKING_OK	0x00000002	True if the library can use the native operation system threading model for locking; false otherwise

CK_C_INITIALIZE_ARGS_PTR is a pointer to a CK_C_INITIALIZE_ARGS.

---

RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v220