Init this token

Namespace:  Cryptware.NCryptoki
Assembly:  NCryptoki (in NCryptoki.dll)

Syntax

Visual Basic (Declaration)
Public Function InitToken ( _
	pin As Byte(), _
	label As String _
) As Integer
C#
public int InitToken(
	byte[] pin,
	string label
)
Visual C++
public:
virtual int InitToken(
	[InAttribute] array<unsigned char>^ pin, 
	String^ label
) sealed
JavaScript
function initToken(pin, label);

Parameters

pin
Type: array<System..::..Byte>[]()[]
PIN
label
Type: System..::..String
Label

Return Value

0 if no error occurs, PKCS#11 error code otherwise

Implements

ISlot..::..InitToken(array<Byte>[]()[][], String)

Remarks

InitToken initializes a token. pin points to the SO’s initial PIN (which need not be null-terminated); label points to the 32-byte label of the token (which must be padded with blank characters). This standard allows PIN values to contain any valid UTF8 character, but the token may impose subset restrictions. If the token has not been initialized (i.e. new from the factory), then the pin parameter becomes the initial value of the SO PIN. If the token is being reinitialized, the pin parameter is checked against the existing SO PIN to authorize the initialization operation. In both cases, the SO PIN is the value pPin after the function completes successfully. If the SO PIN is lost, then the card must be reinitialized using a mechanism outside the scope of this standard. The CKF_TOKEN_INITIALIZED flag in the CK_TOKEN_INFO structure indicates the action that will result from calling InitToken. If set, the token will be reinitialized, and the client must supply the existing SO password in pin. 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 pin parameter to InitToken should be null. During the execution of 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 tokendependent whether or not 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 InitToken is made under such circumstances, the call fails with error CKR_SESSION_EXISTS. Unfortunately, it may happen when 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.
The InitToken function may not be sufficient to properly initialize complex tokens. In these situations, an initialization mechanism outside the scope of Cryptoki must be employed. The definition of “complex token” is product specific.

See Also