OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

pkcs11 message

[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);
    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:


    <ul> <b>C_RenameToken</b>

<p> CK_DEFINE_FUNCTION(CK_RV, C_RenameToken) (
	CK_UTF8CHAR_PTR pPin,		/* TBD */
	CK_ULONG ulPinLen,		/* TBD */

<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

<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.

    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),

<p> Example:

    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) {



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]