Init this token
Namespace:
Cryptware.NCryptokiAssembly: 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 otherwiseImplements
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.
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.