Overview of the Cryptoki Library

User-level applications in the Oracle Solaris cryptographic framework access PKCS #11 functions through the cryptoki library, which is provided in the libpkcs11.so module. The pkcs11_softtoken.so module is a PKCS #11 Soft Token implementation that is provided by Oracle Corporation to supply cryptographic mechanisms. The soft token plug-in is the default source of mechanisms. Cryptographic mechanisms can also be supplied through third-party plug-ins.

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 the cryptoki library, refer to libpkcs11(3LIB) or to PKCS #11: Cryptographic Token Interface Standard on the RSA Laboratories web site.

Ensure that direct bindings are used for all providers. See ld(1) and the Linker and Libraries Guide for more information.

PKCS #11 Function List

The following list shows the categories of PKCS #11 functions that are supported by pkcs11_softtoken.so in the Oracle Solaris 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()

Functions for Using PKCS #11

This section provides descriptions of the following functions for using PKCS #11:

• PKCS #11 Functions: C_Initialize()

• PKCS #11 Functions: C_GetInfo()

• PKCS #11 Functions: C_GetSlotList()

• PKCS #11 Functions: C_GetTokenInfo()

• PKCS #11 Functions: C_OpenSession()

• PKCS #11 Functions: C_GetMechanismList()

PKCS #11 Functions: C_Initialize()

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.

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)

PKCS #11 Functions: C_GetInfo()

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 = Oracle Corporation.

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

PKCS #11 Functions: C_GetSlotList()

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.

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

PKCS #11 Functions: C_GetTokenInfo()

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

PKCS #11 Functions: C_OpenSession()

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

PKCS #11 Functions: C_GetMechanismList()

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

Extended PKCS #11 Functions

In addition to the standard PKCS #11 functions, two convenience functions are supplied with the Oracle Solaris cryptographic framework:

• Extended PKCS #11 Functions: SUNW_C_GetMechSession()

• Extended PKCS #11 Functions: SUNW_C_KeyToObject

Extended PKCS #11 Functions: SUNW_C_GetMechSession()

SUNW_C_GetMechSession() is a convenience function that initializes the Oracle Solaris cryptographic framework. The function then starts a session with the specified mechanism. SUNW_C_GetMechSession() uses the following syntax:

SUNW_C_GetMechSession(CK_MECHANISM_TYPE mech, C\
K_SESSION_HANDLE_PTR hSession)

The mech parameter is used to specify the mechanism to be used. hSession is a pointer to the session location.

Internally, SUNW_C_GetMechSession() calls C_Initialize() to initialize the cryptoki library. SUNW_C_GetMechSession() next calls C_GetSlotList() and C_GetMechanismInfo() to search through the available slots for a token with the specified mechanism. When the mechanism is found, SUNW_C_GetMechSession() calls C_OpenSession() to open a session.

The SUNW_C_GetMechSession() only needs to be called once. However, calling SUNW_C_GetMechSession() multiple times does not cause any problems.

Extended PKCS #11 Functions: SUNW_C_KeyToObject

SUNW_C_KeyToObject() creates a secret key object. The calling program must specify the mechanism to be used and raw key data. Internally, SUNW_C_KeyToObject() determines the type of key for the specified mechanism. A generic key object is created through C_CreateObject(). SUNW_C_KeyToObject() next calls C_GetSessionInfo() and C_GetMechanismInfo() to get the slot and mechanism. C_SetAttributeValue() then sets the attribute flag for the key object according to the type of mechanism.