Login to the token
Namespace:
Cryptware.NCryptokiAssembly: NCryptoki (in NCryptoki.dll)
Syntax
Visual Basic (Declaration) |
---|
Public Function Login ( _ userType As Integer, _ pin As String _ ) As Integer |
C# |
---|
public int Login( int userType, string pin ) |
Visual C++ |
---|
public: virtual int Login( int userType, String^ pin ) sealed |
JavaScript |
---|
function login(userType, pin); |
Parameters
- userType
- Type: System..::..Int32
user type
- pin
- Type: System..::..String
pin
Return Value
0 if no error occurs, PKCS#11 error code otherwiseImplements
ISession..::..Login(Int32, String)
Remarks
When the user type is either CKU_SO or CKU_USER, if the call succeeds, each of the
application's sessions will enter either the "R/W SO Functions" state, the "R/W User
Functions" state, or the "R/O User Functions" state. If the user type is
CKU_CONTEXT_SPECIFIC , the behavior of C_Login depends on the context in which
it is called. Improper use of this user type will result in a return value
CKR_OPERATION_NOT_INITIALIZED.
If the token has a “protected authentication path”, as indicated by the CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. Or the user might not even use a PIN—authentication could be achieved by some fingerprint-reading device, for example. To log into a token with a protected authentication path, the pin parameter to Login should be null. When Login returns, whatever authentication method supported by the token will have been performed; a return value of CKR_OK means that the user was successfully authenticated, and a return value of CKR_PIN_INCORRECT means that the user was denied access. If there are any active cryptographic or object finding operations in an application’s session, and then C_Login is successfully executed by that application, it may or may not be the case that those operations are still active. Therefore, before logging in, any active operations should be finished.
If the application calling Login has a R/O session open with the token, then it will be unable to log the SO into a session (see Section 6.7.7). An attempt to do this will result in the error code CKR_SESSION_READ_ONLY_EXISTS. Login may be called repeatedly, without intervening C_Logout calls, if (and only if) a key with the CKA_ALWAYS_AUTHENTICATE attribute set to CK_TRUE exists, and the user needs to do cryptographic operation on this key. See further Section 10.9 of PKCS#11 v.20 specifications.
If the token has a “protected authentication path”, as indicated by the CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. Or the user might not even use a PIN—authentication could be achieved by some fingerprint-reading device, for example. To log into a token with a protected authentication path, the pin parameter to Login should be null. When Login returns, whatever authentication method supported by the token will have been performed; a return value of CKR_OK means that the user was successfully authenticated, and a return value of CKR_PIN_INCORRECT means that the user was denied access. If there are any active cryptographic or object finding operations in an application’s session, and then C_Login is successfully executed by that application, it may or may not be the case that those operations are still active. Therefore, before logging in, any active operations should be finished.
If the application calling Login has a R/O session open with the token, then it will be unable to log the SO into a session (see Section 6.7.7). An attempt to do this will result in the error code CKR_SESSION_READ_ONLY_EXISTS. Login may be called repeatedly, without intervening C_Logout calls, if (and only if) a key with the CKA_ALWAYS_AUTHENTICATE attribute set to CK_TRUE exists, and the user needs to do cryptographic operation on this key. See further Section 10.9 of PKCS#11 v.20 specifications.