Example of use of sessions

We give here a detailed and lengthy example of how multiple applications can make use of sessions in a Cryptoki library. Despite the somewhat painful level of detail, we highly recommend reading through this example carefully to understand session handles and object handles.

We caution that our example is decidedly not meant to indicate how multiple applications should use Cryptoki simultaneously; rather, it is meant to clarify what uses of Cryptoki's sessions and objects and handles are permissible. In other words, instead of demonstrating good technique here, we demonstrate "pushing the envelope".

For our example, we suppose that two applications, A and B, are using a Cryptoki library to access a single token T. Each application has two threads running: A has threads A1 and A2, and B has threads B1 and B2. We assume in what follows that there are no instances where multiple threads of a single application simultaneously use the same session, and that the events of our example occur in the order specified, without overlapping each other in time.

A1 and B1 each initialize the Cryptoki library by calling C_Initialize (the specifics of Cryptoki functions will be explained in Section 11). Note that exactly one call to C_Initialize should be made for each application (as opposed to one call for every thread, for example).
A1 opens a R/W session and receives the session handle 7 for the session. Since this is the first session to be opened for A, it is a public session.
A2 opens a R/O session and receives the session handle 4. Since all of A 's existing sessions are public sessions, session 4 is also a public session.
A1 attempts to log the SO into session 7. The attempt fails, because if session 7 becomes an SO session, then session 4 does, as well, and R/O SO sessions do not exist. A1 receives an error code indicating that the existence of a R/O session has blocked this attempt to log in (CKR_SESSION_READ_ONLY_EXISTS).
A2 logs the normal user into session 7. This turns session 7 into a R/W user session, and turns session 4 into a R/O user session. Note that because A1 and A2 belong to the same application, they have equal access to all sessions, and therefore, A2 is able to perform this action.
A2 opens a R/W session and receives the session handle 9. Since all of A 's existing sessions are user sessions, session 9 is also a user session.
A1 closes session 9.
B1 attempts to log out session 4. The attempt fails, because A and B have no access rights to each other's sessions or objects. B1 receives an error message which indicates that there is no such session handle (CKR_SESSION_HANDLE_INVALID).
B2 attempts to close session 4. The attempt fails in precisely the same way as B1 's attempt to log out session 4 failed (i.e., B2 receives a CKR_SESSION_HANDLE_INVALID error code).
B1 opens a R/W session and receives the session handle 7. Note that, as far as B is concerned, this is the first occurrence of session handle 7. A 's session 7 and B 's session 7 are completely different sessions.
B1 logs the SO into [B 's] session 7. This turns B 's session 7 into a R/W SO session, and has no effect on either of A 's sessions.
B2 attempts to open a R/O session. The attempt fails, since B already has an SO session open, and R/O SO sessions do not exist. B1 receives an error message indicating that the existence of an SO session has blocked this attempt to open a R/O session (CKR_SESSION_READ_WRITE_SO_EXISTS).
A1 uses [A 's] session 7 to create a session object O1 of some sort and receives the object handle 7. Note that a Cryptoki implementation may or may not support separate spaces of handles for sessions and objects.
B1 uses [B 's] session 7 to create a token object O2 of some sort and receives the object handle 7. As with session handles, different applications have no access rights to each other's object handles, and so B 's object handle 7 is entirely different from A 's object handle 7. Of course, since B1 is an SO session, it cannot create private objects, and so O2 must be a public object (if B1 attempted to create a private object, the attempt would fail with error code CKR_USER_NOT_LOGGED_IN or CKR_TEMPLATE_INCONSISTENT).
B2 uses [B 's] session 7 to perform some operation to modify the object associated with [B 's] object handle 7. This modifies O2.
A1 uses [A 's] session 4 to perform an object search operation to get a handle for O2. The search returns object handle 1. Note that A 's object handle 1 and B 's object handle 7 now point to the same object.
A1 attempts to use [A 's] session 4 to modify the object associated with [A 's] object handle 1. The attempt fails, because A 's session 4 is a R/O session, and is therefore incapable of modifying O2, which is a token object. A1 receives an error message indicating that the session is a R/O session (CKR_SESSION_READ_ONLY).
A1 uses [A 's] session 7 to modify the object associated with [A 's] object handle 1. This time, since A 's session 7 is a R/W session, the attempt succeeds in modifying O2.
B1 uses [B 's] session 7 to perform an object search operation to find O1. Since O1 is a session object belonging to A, however, the search does not succeed.
A2 uses [A 's] session 4 to perform some operation to modify the object associated with [A 's] object handle 7. This operation modifies O1.
A2 uses [A 's] session 7 to destroy the object associated with [A 's] object handle 1. This destroys O2.
B1 attempts to perform some operation with the object associated with [B 's] object handle 7. The attempt fails, since there is no longer any such object. B1 receives an error message indicating that its object handle is invalid (CKR_OBJECT_HANDLE_INVALID).
A1 logs out [A 's] session 4. This turns A 's session 4 into a R/O public session, and turns A 's session 7 into a R/W public session.
A1 closes [A 's] session 7. This destroys the session object O1, which was created by A 's session 7.
A2 attempt to use [A 's] session 4 to perform some operation with the object associated with [A 's] object handle 7. The attempt fails, since there is no longer any such object. It returns a CKR_OBJECT_HANDLE_INVALID.
A2 executes a call to C_CloseAllSessions. This closes [A 's] session 4. At this point, if A were to open a new session, the session would not be logged in (i.e., it would be a public session).
B2 closes [B 's] session 7. At this point, if B were to open a new session, the session would not be logged in.
A and B each call C_Finalize to indicate that they are done with the Cryptoki library.

RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v210