Cryptoki: a cryptographic Token Interface
Download 360.55 Kb.
|
pkcs11-base-v2.40-cos01
- Navigate this page:
- C_InitToken
C_GetMechanismInfoCK_DEFINE_FUNCTION(CK_RV, C_GetMechanismInfo)( CK_SLOT_ID slotID, CK_MECHANISM_TYPE type, CK_MECHANISM_INFO_PTR pInfo ); C_GetMechanismInfo obtains information about a particular mechanism possibly supported by a token. slotID is the ID of the token’s slot; type is the type of mechanism; pInfo points to the location that receives the mechanism information. 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_MECHANISM_INVALID, CKR_OK, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED. Example: CK_SLOT_ID slotID; CK_MECHANISM_INFO info; CK_RV rv; .
/* Get information about the CKM_MD2 mechanism for this token */ rv = C_GetMechanismInfo(slotID, CKM_MD2, &info); if (rv == CKR_OK) { if (info.flags & CKF_DIGEST) { . . . } } C_InitTokenCK_DEFINE_FUNCTION(CK_RV, C_InitToken)( CK_SLOT_ID slotID, CK_CHAR_PTR pPin, CK_ULONG ulPinLen, CK_CHAR_PTR pLabel ); C_InitToken initializes a token. slotID is the ID of the token’s slot; pPin points to the SO’s initial PIN (which need not be null-terminated); ulPinLen is the length in bytes of the PIN; pLabel points to the 32-byte label of the token (which must be padded with blank characters, and which must not be null-terminated). When a token is initialized, all objects that can be destroyed are destroyed (i.e., all except for “indestructible” objects such as keys built into the token). Also, access by the normal user is disabled until the SO sets the normal user’s PIN. Depending on the token, some “default” objects may be created, and attributes of some objects may be set to default values. 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. To initialize a token with such a protected authentication path, the pPin parameter to C_InitToken should be NULL_PTR. During the execution of C_InitToken, the SO’s PIN will be entered through the protected authentication path. If the token has a protected authentication path other than a PINpad, then it is token-dependent whether or not C_InitToken can be used to initialize the token. A token cannot be initialized if Cryptoki detects that any application has an open session with it; when a call to C_InitToken is made under such circumstances, the call fails with error CKR_SESSION_EXISTS. Unfortunately, it may happen when C_InitToken is called that some other application does have an open session with the token, but Cryptoki cannot detect this, because it cannot detect anything about other applications using the token. If this is the case, then the consequences of the C_InitToken call are undefined. 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_PIN_INCORRECT, CKR_PIN_LOCKED, CKR_SESSION_EXISTS, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, CKR_TOKEN_WRITE_PROTECTED. Example: CK_SLOT_ID slotID; CK_CHAR_PTR pin = “MyPIN”; CK_CHAR label[32]; CK_RV rv; .
memset(label, ‘ ’, sizeof(label)); memcpy(label, “My first token”, strlen(“My first token”)); rv = C_InitToken(slotID, pin, strlen(pin), label); if (rv == CKR_OK) { . . . } Download 360.55 Kb. Share with your friends:
|