Pkcs #11: Cryptographic Token Interface Standard rsa laboratories



Download 1.99 Mb.
Page14/50
Date28.01.2017
Size1.99 Mb.
#9297
1   ...   10   11   12   13   14   15   16   17   ...   50

8.7. 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;
The fields of the structure have the following meanings:

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 , 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.


Download 1.99 Mb.

Share with your friends:
1   ...   10   11   12   13   14   15   16   17   ...   50




The database is protected by copyright ©ininet.org 2024
send message

    Main page