Cryptographic Token Interface Standard

PKCS#11


OTP mechanisms

The following table shows, for the OTP mechanisms defined in this document, their support by different cryptographic operations. For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed. There is also no guarantee that a token that supports one mechanism for some operation supports any other mechanism for any other operation (or even supports that same mechanism for any other operation).

Table 87: OTP mechanisms vs. applicable functions
 
Functions
           
Mechanism
Encrypt
&
Decrypt
Sign
&
Verify
SR
&
VR1
Digest
Gen.
Key/
Key
Pair
Wrap
&
Unwrap
Derive
CKM_SECURID_KEY_GEN        
X
   
CKM_SECURID  
X
         
CKM_HOTP_KEY_GEN        
X
   
CKM_HOTP  
X
         
CKM_ACTI_KEY_GEN        
X
   
CKM_ACTI  
X
         

The remainder of this section will present in detail the OTP mechanisms and the parameters that are supplied to them.

CK_PARAM_TYPE

CK_PARAM_TYPE is a value that identifies an OTP parameter type. It is defined as follows:

typedef CK_ULONG CK_PARAM_TYPE;

The following CK_PARAM_TYPE types are defined:

Table 88: OTP parameter types
Parameter Data type Meaning
CK_OTP_PIN RFC 2279 string A UTF8 string containing a PIN for use when computing or verifying PIN-based OTP values.
CK_OTP_CHALLENGE Byte array Challenge to use when computing or verifying challenge-based OTP values.
CK_OTP_TIME RFC 2279 string UTC time value in the form YYYYMMDDhhmmss to use when computing or verifying time-based OTP values.
CK_OTP_COUNTER Byte array Counter value to use when computing or verifying counter-based OTP values.
CK_OTP_FLAGS CK_FLAGS Bit flags indicating the characteristics of the sought OTP as defined below.
CK_OTP_OUTPUT_LENGTH CK_ULONG Desired output length (overrides any default value). A Cryptoki library will return CKR_MECHANISM_PARAM_INVALID if a provided length value is not supported.
CK_OTP_FORMAT CK_ULONG Returned OTP format (allowed values are the same as for CKA_OTP_FORMAT). This parameter is only intended for C_Sign output, see below. When not present, the returned OTP format will be the same as the value of the CKA_OTP_FORMAT attribute for the key in question.
CK_OTP_VALUE Byte array An actual OTP value. This parameter type is intended for C_Sign output, see below.

The following table defines the possible values for the CK_OTP_FLAGS type:

Table 89: OTP Mechanism Flags
Bit flag Mask Meaning
CKF_NEXT_OTP 0x00000001 True (i.e. set) if the OTP computation shall be for the next OTP, rather than the current one (current being interpreted in the context of the algorithm, e.g. for the current counter value or current time window). A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if the CKF_NEXT_OTP flag is set and the OTP mechanism in question does not support the concept of "next" OTP or the library is not capable of generating the next OTP

Applications that may need to retrieve the next OTP should be prepared to handle this situation. For example, an application could store the OTP value returned by C_Sign so that, if a next OTP is required, it can compare it to the OTP value returned by subsequent calls to C_Sign should it turn out that the library does not support the CKF_NEXT_OTP flag.

.
CKF_EXCLUDE_TIME 0x00000002 True (i.e. set) if the OTP computation must not include a time value. Will have an effect only on mechanisms that do include a time value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.
CKF_EXCLUDE_COUNTER 0x00000004 True (i.e. set) if the OTP computation must not include a counter value. Will have an effect only on mechanisms that do include a counter value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.
CKF_EXCLUDE_CHALLENGE 0x00000008 True (i.e. set) if the OTP computation must not include a challenge. Will have an effect only on mechanisms that do include a challenge in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.
CKF_EXCLUDE_PIN 0x00000010 True (i.e. set) if the OTP computation must not include a PIN value. Will have an effect only on mechanisms that do include a PIN in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.
CKF_USER_FRIENDLY_OTP 0x00000020 True (i.e. set) if the OTP returned shall be in a form suitable for human consumption. If this flag is set, and the call is successful, then the returned CK_OTP_VALUE shall be a UTF8-encoded printable string. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if this flag is set when CKA_OTP_USER_FRIENDLY_MODE for the key in question is CK_FALSE.

Note: Even if CKA_OTP_FORMAT is not set to CK_OTP_FORMAT_BINARY, then there may still be value in setting the CKF_USER_FRIENDLY flag (assuming CKA_USER_FRIENDLY_MODE is CK_TRUE, of course) if the intent is for a human to read the generated OTP value, since it may become shorter or otherwise better suited for a user. Applications that do not intend to provide a returned OTP value to a user should not set the CKF_USER_FRIENDLY_OTP flag.

CK_OTP_PARAM; CK_OTP_PARAM_PTR

CK_OTP_PARAM is a structure that includes the type, value, and length of an OTP parameter. It is defined as follows:

typedef struct CK_OTP_PARAM {
CK_PARAM_TYPE type;
CK_VOID_PTR pValue;
CK_ULONGulValueLen;
} CK_OTP_PARAM;

type the parameter type
pValue pointer to the value of the parameter
ulValueLen length in bytes of the value

If a parameter has no value, then ulValueLen = 0, and the value of pValue is irrelevant. Note that pValue is a "void" pointer, facilitating the passing of arbitrary values. Both the application and the Cryptoki library must ensure that the pointer can be safely cast to the expected type (i.e., without word-alignment errors).

CK_OTP_PARAM_PTR is a pointer to a CK_OTP_PARAM.

CK_OTP_PARAMS; CK_OTP_PARAMS_PTR CK_OTP_PARAMS is a structure that is used to provide parameters for OTP mechanisms in a generic fashion. It is defined as follows:

typedef struct CK_OTP_PARAMS {
CK_OTP_PARAM_PTR pParams;
CK_ULONG ulCount;
} CK_OTP_PARAMS;

pParams pointer to an array of OTP parameters
ulCount the number of parameters in the array

CK_OTP_PARAMS_PTR is a pointer to a CK_OTP_PARAMS.

When calling C_SignInit or C_VerifyInit with a mechanism that takes a CK_OTP_PARAMS structure as a parameter, the CK_OTP_PARAMS structure shall be populated in accordance with the 'CKA_OTP_ X_REQUIREMENT ' key attributes for the identified key, where X is PIN, CHALLENGE, TIME, or COUNTER.

For example, if CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_MANDATORY, then the CK_OTP_TIME parameter shall be present. If CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_OPTIONAL, then a CK_OTP_TIME parameter may be present. If it is not present, then the library may collect it (during the C_Sign call). If CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_IGNORED, then a provided CK_OTP_TIME parameter will always be ignored. Additionally, a provided CK_OTP_TIME parameter will always be ignored if CKF_EXCLUDE_TIME is set in a CK_OTP_FLAGS parameter. Similarly, if this flag is set, a library will not attempt to collect the value itself, and it will also instruct the token not to make use of any internal value, subject to token policies. It is an error (CKR_MECHANISM_PARAM_INVALID) to set the CKF_EXCLUDE_TIME flag when the CKA_TIME_REQUIREMENT attribute is CK_OTP_PARAM_MANDATORY.
The above discussion holds for all CKA_OTP_''X''_REQUIREMENT attributes (''i.e''., CKA_OTP_PIN_REQUIREMENT, CKA_OTP_CHALLENGE_REQURIEMENT, CKA_OTP_COUNTER_REQUIREMENT, CKA_OTP_TIME_REQUIREMENT). A library may set a particular CKA_OTP_''X''_REQUIREMENT attribute to CK_OTP_PARAM_OPTIONAL even if it is required by the mechanism as long as the token (or the library itself) has the capability of providing the value to the computation. One example of this is a token with an on-board clock.

In addition, applications may use the CK_OTP_FLAGS, the CK_OTP_OUTPUT_FORMAT and the CK_OUTPUT_LENGTH parameters to set additional parameters.

CK_OTP_SIGNATURE_INFO, CK_OTP_SIGNATURE_INFO_PTR CK_OTP_SIGNATURE_INFO is a structure that is returned by all OTP mechanisms in successful calls to C_Sign (C_SignFinal). The structure informs applications of actual parameter values used in particular OTP computations in addition to the OTP value itself. It is used by all mechanisms for which the key belongs to the class CKO_OTP_KEY and is defined as follows:

typedef struct CK_OTP_SIGNATURE_INFO {
CK_OTP_PARAM_PTR pParams;
CK_ULONG ulCount;
} CK_OTP_SIGNATURE_INFO;

pParams pointer to an array of OTP parameter values
ulCount the number of parameters in the array

After successful calls to C_Sign or C_SignFinal with an OTP mechanism, the pSignature parameter will be set to point to a CK_OTP_SIGNATURE_INFO structure. One of the parameters in this structure will be the OTP value itself, identified with the CK_OTP_VALUE tag. Other parameters may be present for informational purposes, e.g. the actual time used in the OTP calculation. In order to simplify OTP validations, authentication protocols may permit authenticating parties to send some or all of these parameters in addition to OTP values themselves. Applications should therefore check for their presence in returned CK_OTP_SIGNATURE_INFO values whenever such circumstances apply.

Since C_Sign and C_SignFinal follows the convention described in Section 11.2 on producing output, a call to C_Sign (or C_SignFinal) with pSignature set to NULL_PTR will return (in the pulSignatureLen parameter) the required number of bytes to hold the CK_OTP_SIGNATURE_INFO structure as well as all the data in all its CK_OTP_PARAM components. If an application allocates a memory block based on this information, it shall therefore not subsequently de-allocate components of such a received value but rather de-allocate the complete CK_OTP_PARAMS structure itself. A Cryptoki library that is called with a non-NULL pSignature pointer will assume that it points to a contiguous memory block of the size indicated by the pulSignatureLen parameter.

When verifying an OTP value using an OTP mechanism, pSignature shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAMS structure returned by a call to C_Sign. The CK_OTP_PARAMS value supplied in the C_VerifyInit call sets the values to use in the verification operation.

CK_OTP_SIGNATURE_INFO_PTR points to a CK_OTP_SIGNATURE_INFO.


RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v230mechanism1