This section provides descriptions of the following functions for using PKCS #11:
All the PKCS #11 functions are available from libpkcs11.so library. You do not have to use the C_GetFunctionList() function to get the list of functions available.
C_Initialize() initializes the PKCS #11 library. C_Initialize() uses the following syntax:
C_Initialize(CK_VOID_PTR pInitArgs);
pInitArgs is either the null value NULL_PTR or else a pointer to a CK_C_INITIALIZE_ARGS structure. With NULL_PTR, the library uses the Oracle Solaris mutexes as locking primitives to arbitrate the access to internal shared structures between multiple threads. Note that the Oracle Solaris cryptographic framework does not accept mutexes. Because this implementation of the cryptoki library handles multithreading safely and efficiently, using NULL_PTR is recommended. An application can also use pInitArgs to set flags such as CKF_LIBRARY_CANT_CREATE_OS_THREADS. C_Finalize() signals that the application is through with the PKCS #11 library.
C_Finalize() should never be called by libraries. By convention, applications are responsible for calling C_Finalize() to close out a session.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_Initialize() uses the following return values:
CKR_ARGUMENTS_BAD
CKR_CANT_LOCK
CKR_CRYPTOKI_ALREADY_INITIALIZED (not fatal)
C_GetInfo() uses manufacturer and version information about the cryptoki library. C_GetInfo() uses the following syntax:
C_GetInfo(CK_INFO_PTR pInfo);
C_GetInfo() returns the following values:
cryptokiVersion = 2, 11
manufacturerID = Sun Microsystems, Inc.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_GetInfo() gets the following return values:
CKR_ARGUMENTS_BAD
CKR_CRYPTOKI_NOT_INITIALIZED
C_GetSlotList() uses a list of available slots. If no additional cryptographic providers have been installed other than pkcs11_softtoken.so, then C_GetSlotList() returns the default slot only. C_GetSlotList() uses the following syntax:
C_GetSlotList(CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList, CK_ULONG_PTR pulCount);
When set to TRUE, tokenPresent limits the search to those slots whose tokens are present.
When pSlotList is set to NULL_PTR, C_GetSlotlist() returns the number of slots only. pulCount is a pointer to the location to receive the slot count.
When pSlotList points to the buffer to receive the slots, *pulCount is set to the maximum expected number of CK_SLOT_ID elements. On return, *pulCount is set to the actual number of CK_SLOT_ID elements.
Typically, PKCS #11 applications call C_GetSlotList() twice. The first time, C_GetSlotList() is called to get the number of slots for memory allocation. The second time, C_GetSlotList() is called to retrieve the slots.
The order of the slots is not guaranteed. The order of the slots can vary with each load of the PKCS #11 library.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_GetSlotlist() gets the following return values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
C_GetTokenInfo() gets information about a specific token. C_GetTokenInfo() uses the following syntax:
C_GetTokenInfo(CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo);
slotID identifies the slot for the token. slotID has to be a valid ID that was returned by C_GetSlotList(). pInfo is a pointer to the location to receive the token information.
If pkcs11_softtoken.so is the only installed provider, then C_GetTokenInfo() returns the following fields and values:
label – Sun Software PKCS#11 softtoken.
flags – CKF_DUAL_CRYPTO_OPERATIONS, CKF_TOKEN_INITIALIZED, CKF_RNG, CKF_USER_PIN_INITIALIZED, and CKF_LOGIN_REQUIRED, which are set to 1.
ulMaxSessionCount – Set to CK_EFFECTIVELY_INFINITE.
ulMaxRwSessionCount - Set to CK_EFFECTIVELY_INFINITE.
ulMaxPinLen – Set to 256.
ulMinPinLen – Set to 1.
ulTotalPublicMemory set to CK_UNAVAILABLE_INFORMATION.
ulFreePublicMemory set to CK_UNAVAILABLE_INFORMATION.
ulTotalPrivateMemory set to CK_UNAVAILABLE_INFORMATION.
ulFreePrivateMemory set to CK_UNAVAILABLE_INFORMATION.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_GetSlotlist() gets the following return values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
The following return values are relevant for plug-ins with hardware tokens:
CKR_DEVICE_ERROR
CKR_DEVICE_MEMORY
CKR_DEVICE_REMOVED
CKR_TOKEN_NOT_PRESENT
CKR_TOKEN_NOT_RECOGNIZED
C_OpenSession() enables an application to start a cryptographic session with a specific token in a specific slot. C_OpenSession() uses the following syntax:
C_OpenSession(CK_SLOT_ID slotID, CK_FLAGS flags, CK_VOID_PTR pApplication, CK_NOTIFY Notify, CK_SESSION_HANDLE_PTR phSession);
slotID identifies the slot. flags indicates whether the session is read-write or read-only. pApplication is a pointer that is defined by the application for use in callbacks. Notify holds the address of an optional callback function. phSession is a pointer to the location of the session handle.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_OpenSession() gets the following return values:
CKR_ARGUMENTS_BAD
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
CKR_TOKEN_WRITE_PROTECTED (occurs with write-protected tokens)
The following return values are relevant for plug-ins with hardware tokens:
CKR_DEVICE_ERROR
CKR_DEVICE_MEMORY
CKR_DEVICE_REMOVED
CKR_SESSION_COUNT
CKR_SESSION_PARALLEL_NOT_SUPPORTED
CKR_SESSION_READ_WRITE_SO_EXISTS
CKR_TOKEN_NOT_PRESENT
CKR_TOKEN_NOT_RECOGNIZED
C_GetMechanismList() gets a list of mechanism types that are supported by the specified token. C_GetMechanismList() uses the following syntax:
C_GetMechanismList(CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR pMechanismList, CK_ULONG_PTR pulCount);
slotID identifies the slot for the token. pulCount is a pointer to the location to receive the number of mechanisms. When pMechanismList is set to NULL_PTR, the number of mechanisms is returned in *pulCount. Otherwise, *pulCount must be set to the size of the list and pMechanismList points to the buffer to hold the list.
When PKCS #11 Soft Token is plugged in, C_GetMechanismList() returns the following list of supported mechanisms:
CKM_AES_CBC
CKM_AES_CBC_PAD
CKM_AES_ECB
CKM_AES_KEY_GEN
CKM_DES_CBC
CKM_DES_CBC_PAD
CKM_DES_ECB
CKM_DES_KEY_GEN
CKM_DES_MAC
CKM_DES_MAC_GENERAL
CKM_DES3_CBC
CKM_DES3_CBC_PAD
CKM_DES3_ECB
CKM_DES3_KEY_GEN
CKM_DH_PKCS_DERIVE
CKM_DH_PKCS_KEY_PAIR_GEN
CKM_DSA
CKM_DSA_KEY_PAIR_GEN
CKM_DSA_SHA_1
CKM_MD5
CKM_MD5_KEY_DERIVATION
CKM_MD5_RSA_PKCS
CKM_MD5_HMAC
CKM_MD5_HMAC_GENERAL
CKM_PBE_SHA1_RC4_128
CKM_PKCS5_PBKD2
CKM_RC4
CKM_RC4_KEY_GEN
CKM_RSA_PKCS
CKM_RSA_X_509
CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_SHA_1
CKM_SHA_1_HMAC_GENERAL
CKM_SHA_1_HMAC
CKM_SHA_1_KEY_DERIVATION
CKM_SHA_1_RSA_PKCS
CKM_SSL3_KEY_AND_MAC_DERIVE
CKM_SSL3_MASTER_KEY_DERIVE
CKM_SSL3_MASTER_KEY_DERIVE_DH
CKM_SSL3_MD5_MAC
CKM_SSL3_PRE_MASTER_KEY_GEN
CKM_SSL3_SHA1_MAC
CKM_TLS_KEY_AND_MAC_DERIVE
CKM_TLS_MASTER_KEY_DERIVE
CKM_TLS_MASTER_KEY_DERIVE_DH
CKM_TLS_PRE_MASTER_KEY_GEN
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK, C_GetSlotlist() uses the following return values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
The following return values are relevant for plug-ins with hardware tokens:
CKR_DEVICE_ERROR
CKR_DEVICE_MEMORY
CKR_DEVICE_REMOVED
CKR_TOKEN_NOT_PRESENT
CKR_TOKEN_NOT_RECOGNIZED