nShield-specific PKCS#11 API extensions

nShield K/N card sets use nShield-specific API calls. These calls can be used by the application in place of the standard C_Login to provide log-in to a card set with a K parameter greater than 1. The API calls include three functions, C_LoginBegin, C_LoginNext and C_LoginEnd.

The login sequence must occur in the same session.

You cannot use the API calls in load-sharing mode. To use K/N card sets in load-sharing mode, use preload to load the logical token first. The API calls also work in a non-load-sharing FIPS 140 Level 3 Security Worlds.

C_LoginBegin

Similar to C_Login, this function initiates the log-in process, ensures that the session is valid, and ensures that the user is not in load-sharing mode.

The pulK and pulN return values provide the caller with the number of card requests required. An example of the use of C_LoginBegin is shown here:

C_LoginBegin (CK_SESSION_HANDLE hSession, /* the session's handle */
              CK_USER_TYPE userType, /* the user type */
              CK_ULONG_PTR pulK, /* cards required to load logical token*/
              CK_ULONG_PTR pulN /* Number of cards in set */)

C_LoginNext

C_LoginNext is called K times until the required number of cards (for the given card set) have been presented. This function checks the Security World info to ensure that the card has changed each time. It also checks for the correct passphrase before loading the card share. pulSharesLeft allows the user application to assess the number of cards loaded to the number of cards required.

CK_RV gives various values that allow the user to access the application state using standard PKCS #11 return values (such as CKR_TOKEN_NOT_RECOGNIZED). These values reveal such information as whether the card is the same, whether the card is foreign or blank, and whether the passphrase was incorrect.

An example of the use of C_LoginNext is shown here:

C_LoginNext (CK_SESSION_HANDLE hSession, /* the session's handle */
             CK_USER_TYPE userType, /* the user type*/
             CK_CHAR_PTR pPin, /* the user's PIN*/
             CK_ULONG ulPinLen, /* the length of the PIN */
             CK_ULONG_PTR pulSharesLeft /* Number of shares still needed */)

C_LoginEnd

C_LoginEnd is called after all the shares are loaded. It constructs the logical token from the presented shares and then loads the private objects protected by the card set that are available to it:

C_LoginEnd (CK_SESSION_HANDLE hSession, /* the session's handle */
            CK_USER_TYPE userType /* the user type*/)

There must be no other calls between the functions, in that or any other session on the slot. In particular, a call that updates the Security World while using a card that has been removed at the time (for example, because a second card from the set is about to be inserted) returns CKR_DEVICE_REMOVED in the same way that it would for a single card. All sessions are then closed and the log-in process is aborted.

If other functions are accidentally called during the log-in cycle, then slot.loadcardsetstate is checked before updating the Security World. If the log-in process has not been completed, other functions return CKR_FUNCTION_FAILED and allow you to continue with the log-in process.