Cryptoki: a cryptographic Token Interface
Session management functions
Download 360.55 Kb.
|
pkcs11-base-v2.40-cos01
- Navigate this page:
- C_OpenSession
10.6. Session management functionsA typical application might perform the following series of steps to make use of a token (note that there are other reasonable sequences of events that an application might perform): Select a token. Make one or more calls to C_OpenSession to obtain one or more sessions with the token. Call C_Login to log the user into the token. Since all sessions an application has with a token have a shared login state, C_Login only needs to be called for one of the sessions. Perform cryptographic operations using the sessions with the token. Call C_CloseSession once for each session that the application has with the token, or call C_CloseAllSessions to close all the application’s sessions simultaneously. As has been observed, an application may have concurrent sessions with more than one token. It is also possible for a token to have concurrent sessions with more than one application. Cryptoki provides the following functions for session management: C_OpenSessionCK_DEFINE_FUNCTION(CK_RV, C_OpenSession)( CK_SLOT_ID slotID, CK_FLAGS flags, CK_VOID_PTR pApplication, CK_NOTIFY Notify, CK_SESSION_HANDLE_PTR phSession ); C_OpenSession opens a session between an application and a token in a particular slot. slotID is the slot’s ID; flags indicates the type of session; pApplication is an application-defined pointer to be passed to the notification callback; Notify is the address of the notification callback function (see Section ); phSession points to the location that receives the handle for the new session. When opening a session with C_OpenSession, the flags parameter consists of the logical OR of zero or more bit flags defined in the CK_SESSION_INFO data type. For legacy reasons, the CKF_SERIAL_SESSION bit must always be set; if a call to C_OpenSession does not have this bit set, the call should return unsuccessfully with the error code CKR_PARALLEL_NOT_SUPPORTED. There may be a limit on the number of concurrent sessions an application may have with the token, which may depend on whether the session is “read-only” or “read/write”. An attempt to open a session which does not succeed because there are too many existing sessions of some type should return CKR_SESSION_COUNT. If the token is write-protected (as indicated in the CK_TOKEN_INFO structure), then only read-only sessions may be opened with it. If the application calling C_OpenSession already has a R/W SO session open with the token, then any attempt to open a R/O session with the token fails with error code CKR_SESSION_READ_WRITE_SO_EXISTS (see Section ). The Notify callback function is used by Cryptoki to notify the application of certain events. If the application does not wish to support callbacks, it should pass a value of NULL_PTR as the Notify parameter. See Section for more information about application callbacks. Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_COUNT, CKR_SESSION_PARALLEL_NOT_SUPPORTED, CKR_SESSION_READ_WRITE_SO_EXISTS, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, CKR_TOKEN_WRITE_PROTECTED. Example: see C_CloseSession. Download 360.55 Kb. Share with your friends:
|