User-level applications in the Cryptographic Framework access PKCS #11 functions through thecryptoki library, which is provided in thelibpkcs11.so module. Thepkcs11_softtoken.so module is a PKCS #11 soft token implementationthat is provided by Oracle Corporation to supply cryptographic mechanisms. The softtoken plugin is the default source of mechanisms. Cryptographic mechanisms can also besupplied through third-party plugins.
This section lists the PKCS #11 functions and return values that are supported by the soft token. Return codes vary depending on the providers that are plugged into the framework. The section also describes some common functions. For a complete description of all the elements in thecryptoki library, refer tolibpkcs11(3LIB).
Ensure that direct bindings are used for all providers. See theld(1) man page andOracle Solaris 11.4 Linkers and Libraries Guidefor more information.
The following list shows the categories of PKCS #11 functions that are supported bypkcs11_softtoken.so in the Cryptographic Framework with the associated functions:
General purpose –C_Initialize(),C_Finalize(),C_GetInfo(),C_GetFunctionList()
Session management –C_OpenSession(),C_CloseSession(),C_GetSessionInfo(),C_CloseAllSessions(),C_Login(),C_Logout()
Slot and token management –C_GetSlotList(),C_GetSlotInfo(),C_GetMechanismList(),C_GetMechanismInfo(),C_SetPIN()
Encryption and decryption –C_EncryptInit(),C_Encrypt(),C_EncryptUpdate(),C_EncryptFinal(),C_DecryptInit(),C_Decrypt(),C_DecryptUpdate(),C_DecryptFinal()
Message digesting –C_DigestInit(),C_Digest(),C_DigestKey(),C_DigestUpdate(),C_DigestFinal()
Signing and applying MAC –C_Sign(),C_SignInit(),C_SignUpdate(),C_SignFinal(),C_SignRecoverInit(),C_SignRecover()
Signature verification –C_Verify(),C_VerifyInit(),C_VerifyUpdate(),C_VerifyFinal(),C_VerifyRecoverInit(),C_VerifyRecover()
Dual-purpose cryptographic functions –C_DigestEncryptUpdate(),C_DecryptDigestUpdate(),C_SignEncryptUpdate(),C_DecryptVerifyUpdate()
Random number generation –C_SeedRandom(),C_GenerateRandom()
Object management –C_CreateObject(),C_DestroyObject(),C_CopyObject(),C_FindObjects(),C_FindObjectsInit(),C_FindObjectsFinal(),C_GetAttributeValue(),C_SetAttributeValue()
Key management –C_GenerateKey(),C_GenerateKeyPair(),C_DeriveKey()
This section provides descriptions of the following functions for using PKCS #11:
C_Initialize() initializes the PKCS #11 library.C_Initialize() uses the following syntax:
C_Initialize(CK_VOID_PTRpInitArgs);
pInitArgs is either the null valueNULL_PTR or else a pointer to a CK_C_INITIALIZE_ARGS structure.WithNULL_PTR, the library uses the Oracle Solaris mutexesas locking primitives to arbitrate the access to internal shared structuresbetween multiple threads. Note that the Cryptographic Frameworkdoes not accept mutexes. Because this implementation of thecryptoki libraryhandles multithreading safely and efficiently, usingNULL_PTR isrecommended. An application can also usepInitArgs toset flags such as CKF_LIBRARY_CANT_CREATE_OS_THREADS.C_Finalize() signalsthat the application is through with the PKCS #11 library.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK,C_Initialize() returns the following values:
CKR_ARGUMENTS_BAD
CKR_CANT_LOCK
CKR_CRYPTOKI_ALREADY_INITIALIZED (not fatal)
C_GetInfo() gets manufacturer and version information about thecryptoki library.C_GetInfo() uses thefollowing syntax:
C_GetInfo(CK_INFO_PTRpInfo);
C_GetInfo() returns the following values:
cryptokiVersion = 2, 11
manufacturerID = Oracle Corporation.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK,C_GetInfo() returns the following values:
CKR_ARGUMENTS_BAD
CKR_CRYPTOKI_NOT_INITIALIZED
C_GetSlotList() gets a list of available slots. If no additionalcryptographic providers have been installed other thanpkcs11_softtoken.so, thenC_GetSlotList() returns the default slot only.C_GetSlotList() uses the following syntax:
C_GetSlotList(CK_BBOOLtokenPresent, CK_SLOT_ID_PTRpSlotList, CK_ULONG_PTRpulCount);
When set to TRUE,tokenPresent limits the search to those slots whose tokens are present.
WhenpSlotList is set to NULL_PTR,C_GetSlotlist() returns the number of slots only.pulCount isa pointer to the location to receive the slot count.
WhenpSlotList points to the buffer to receivethe slots,*pulCount is set to the maximum expectednumber of CK_SLOT_ID elements. On return,*pulCount isset to the actual number of CK_SLOT_ID elements.
Typically, PKCS #11 applications callC_GetSlotList() twice.The first time,C_GetSlotList() is called to get the numberof slots for memory allocation. The second time,C_GetSlotList() iscalled to retrieve the slots.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK,C_GetSlotlist() returns the following values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
C_GetTokenInfo() gets informationabout a specific token.C_GetTokenInfo() uses the followingsyntax:
C_GetTokenInfo(CK_SLOT_IDslotID, CK_TOKEN_INFO_PTRpInfo);
slotID identifies the slot for the token.slotID has to be a valid ID that was returned byC_GetSlotList().pInfo is a pointer to the location toreceive the token information.
Ifpkcs11_softtoken.so is the only installed provider,thenC_GetTokenInfo() returns the following fields andvalues:
label – Sun Software PKCS#11 softtoken.
flags –CKF_DUAL_CRYPTO_OPERATIONS,CKF_TOKEN_INITIALIZED,CKF_RNG,CKF_USER_PIN_INITIALIZED, andCKF_LOGIN_REQUIRED, which are set to 1.
ulMaxSessionCount – Set toCK_EFFECTIVELY_INFINITE.
ulMaxRwSessionCount - Set toCK_EFFECTIVELY_INFINITE.
ulMaxPinLen – Set to 256.
ulMinPinLen – Set to 1.
ulTotalPublicMemory set toCK_UNAVAILABLE_INFORMATION.
ulFreePublicMemory set toCK_UNAVAILABLE_INFORMATION.
ulTotalPrivateMemory set toCK_UNAVAILABLE_INFORMATION.
ulFreePrivateMemory set toCK_UNAVAILABLE_INFORMATION.
In addition to CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, and CKR_OK,C_GetSlotlist() returns the following values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
The following return values are relevant for plugins with hardwaretokens:
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 sessionwith a specific token in a specific slot.C_OpenSession()uses the following syntax:
C_OpenSession(CK_SLOT_IDslotID, CK_FLAGSflags, CK_VOID_PTRpApplication, CK_NOTIFYNotify, CK_SESSION_HANDLE_PTRphSession);
slotID identifies the slot.flags indicateswhether the session is read-write or read-only.pApplication isa 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() returns the following values:
CKR_ARGUMENTS_BAD
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
CKR_TOKEN_WRITE_PROTECTED (occurs withwrite-protected tokens)
The following return values are relevant for plugins 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 bythe specified token.C_GetMechanismList() uses the followingsyntax:
C_GetMechanismList(CK_SLOT_IDslotID, CK_MECHANISM_TYPE_PTRpMechanismList, CK_ULONG_PTRpulCount);
slotID identifies the slot for the token.pulCount is a pointer to the location to receive the number ofmechanisms. WhenpMechanismList is set to NULL_PTR,the number of mechanisms is returned in*pulCount.Otherwise,*pulCount must be set to the size of thelist andpMechanismList points to the buffer to holdthe list.
When the PKCS #11 soft token is plugged in,C_GetMechanismList() returns thefollowing 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() returns the following values:
CKR_ARGUMENTS_BAD
CKR_BUFFER_TOO_SMALL
CKR_CRYPTOKI_NOT_INITIALIZED
CKR_SLOT_ID_INVALID
The following return values are relevant for plugins with hardware tokens:
CKR_DEVICE_ERROR
CKR_DEVICE_MEMORY
CKR_DEVICE_REMOVED
CKR_TOKEN_NOT_PRESENT
CKR_TOKEN_NOT_RECOGNIZED
In addition to the standard PKCS #11 functions, two convenience functions are supplied with the Cryptographic Framework:
SUNW_C_GetMechSession() is a convenience function that initializes theCryptographic Framework. The function then starts a session with the specifiedmechanism.SUNW_C_GetMechSession() uses the followingsyntax:
SUNW_C_GetMechSession(CK_MECHANISM_TYPEmech, C\K_SESSION_HANDLE_PTRhSession)
Themech parameter is used to specify the mechanismto be used.hSession is a pointer to the session location.
Internally,SUNW_C_GetMechSession() callsC_Initialize() to initialize thecryptoki library.SUNW_C_GetMechSession() next callsC_GetSlotList() andC_GetMechanismInfo() to search through the available slots for a token with the specifiedmechanism. When the mechanism is found,SUNW_C_GetMechSession() callsC_OpenSession() to open a session.
TheSUNW_C_GetMechSession() only needs to be calledonce. However, callingSUNW_C_GetMechSession() multipletimes does not cause any problems.
SUNW_C_KeyToObject() creates a secret key object. The calling program mustspecify the mechanism to be used and raw key data. Internally,SUNW_C_KeyToObject() determines the type of key for thespecified mechanism. A generic key object is created throughC_CreateObject().SUNW_C_KeyToObject()next callsC_GetSessionInfo() andC_GetMechanismInfo() to get the slot and mechanism.C_SetAttributeValue() then sets the attribute flag forthe key object according to the type of mechanism.