[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: C_RenameToken (was: C_ChangeLabel/C_ClearToken)
My thought about renaming tokens is that it would be normal user
function, not an SO function, though nothing should preclude an
SO from using the function too. Our company's implementation
of a software token is SO-less. I'd have to be my own SO for
my software token, so we figured why bother with an SO at all.
The spec does allow for token initialization outside of Cryptoki,
so we took advantage of that. (It may or may not stay that way.)
The SO's 'lifetime' of usefulness to the normal user is short:
(1) initialize tokens, including the initial token name, and
(2) set initial PINs.
After that, most of time, the SO doesn't really do much more
for normal users. Yes, if users need tokens reinitialized,
or some public objects need tending, the SO is there for that.
Normal users change token PINs without SO intervention, so why
shouldn't he be able to change his token's name?
Coming from that background, I was hoping to see a new function
that allows normal users a little more control over their tokens.
Not everything about the token should be modifiable, resource
and session limits for example. Those token attributes can be
enforced by the device-dependent implementation.
I do think authentication is required to change token names.
But normal user C_Login should suffice; it shouldn't need to
be limited to the SO only. Write-protected tokens and read-only
sessions should not allow changing token names. SO sessions and
normal user sessions shouldn't step on each other, thus the
usual checking for simultaneous user and SO sessions should
still occur as expected. For those implementations that fiddle
with CKF_WRITE_PROTECTED to force authentication with C_Login,
they should also do that for changing the token name too. All
those details are already spelled out in the rest of the spec.
I'm still waffling between two different versions/usages of the
interface. Maybe someone else will have clearer insight. I'd
be happy with either
rv = C_RenameToken(hSession, pPin, ulPinLen, pNewLabel);
or
rv = C_Login(hSession, eUser, pPin, ulPinLen);
rv = C_RenameToken(hSession, pNewLabel);
In the first version, the requirement to authenticate is explicit,
but both versions require authenticating to the token to change the
token name successfully. I left pPin and ulPinLen in my interface
proposal, because it's much easier for me to rip it out later than
it is to add it.
Here it is, written up as if it were ready to be incorporated:
<body>
<ul> <b>C_RenameToken</b>
<p> CK_DEFINE_FUNCTION(CK_RV, C_RenameToken) (
CK_SESSION_HANDLE hSession,
CK_UTF8CHAR_PTR pPin, /* TBD */
CK_ULONG ulPinLen, /* TBD */
CK_UTF8CHAR_PTR pNewLabel
);
<p> <b>C_RenameToken</b> modifies the label of a particular token in
the system for which the user session is currently logged in.
<i>hSession</i> is the session's handle; <i>pPin</i> points to the
user's PIN; <i>ulPinLen</i> is the length in bytes of the PIN;
<i>pNewLabel</i> points to the 32-byte label of the token (which
must be padded with blank characters, and which must <i>not</i> be
null-terminated). This standard allows PIN values to contain any
valid UTF8 character, but the token may impose subset restrictions.
<p> <b>C_RenameToken</b> can only be called in the "R/W SO Functions"
or "R/W User Functions" state. Either the SO user or a normal
user must have successfully authenticated with <b>C_Login</b>.
An attempt to call it from a session in any other state fails
with error CKR_SESSION_READ_ONLY or CKR_USER_NOT_LOGGED_IN.
<p> The <i>pPin</i> parameter is checked against the existing user
PIN to authorize the token renaming operation. The
<b>CKF_TOKEN_INITIALIZED</b> flag in the <b>CK_TOKEN_INFO</b>
structure indicates the action that will result from calling
<b>C_RenameToken</b>. If set, the token will be renamed, and
the client must supply the existing user password in <i>pPin</i>.
<p> If the token has a "protected authentication path", as indicated
by the <b>CKF_PROTECTED_AUTHENTICATION_PATH</b> flag in its
<b>CK_TOKEN_INFO</b> 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 rename a token with
such a protected authentication path, the <i>pPin</i> parameter
to <b>C_RenameToken</b> should be NULL_PTR. During the execution
of <b>C_RenameToken</b>, the user's PIN will be entered through
the protected authentication path.
<p> If the token has a protected authentication path other than a
PINpad, then it is token-dependent whether or not
<b>C_RenameToken</b> can be used to rename the token.
<p> A token cannot be renamed if Cryptoki detects that <i>any</i>
application has an open session with it; when a call to
<b>C_RenameToken</b> is made under such circumstances, the call
fails with error CKR_SESSION_EXISTS. Unfortunately, it may happen
when <b>C_RenameToken</b> is called that some other application
<i>does</i> 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 <b>C_RenameToken</b> call are undefined.
<p> Return values: CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED,
CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_FUNCTION_NOT_SUPPORTED
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_OK,
CKR_PIN_EXPIRED, CKR_PIN_INCORRECT, CKR_PIN_LOCKED,
CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID,
CKR_SESSION_READ_ONLY (for normal user),
CKR_SESSION_READ_ONLY_EXISTS (SO user with normal R/O user logged in),
CKR_SESSION_READ_WRITE_SO_EXISTS (normal user while SO logged in),
CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_WRITE_PROTECTED,
CKR_USER_NOT_LOGGED_IN,
CKR_ARGUMENTS_BAD.
<p> Example:
<pre>
CK_SESSION_HANDLE hSession;
CK_UTF8CHAR_PTR pin = "MyPIN";
CK_UTF8CHAR label[32];
CK_RV rv;
.
.
/* CKU_SO or CKU_USER may be selected. */
rv = C_Login(hSession, CKU_USER, pin, strlen(pin));
if (rv == CKR_OK) {
.
.
memset(label, ' ', sizeof(label));
memcpy(label, "My token", strlen("My token"));
rv = C_RenameToken(hSession, pin, strlen(pin), label);
if (rv == CKR_OK) {
.
.
}
}
</pre>
</body>
Regards,
D.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]