One-Time Password Support

This section describes support of One-Time Password (OTP) through PKCS#11 API in order to supersede the ACOMX API.

Mechanisms

The following table shows which OTP mechanisms are supported by different cryptographic operations.

Lines in grey correspond to unsupported mechanisms.

  Functions
Mechanism Encrypt & Decrypt Sign & Verify SR & VR1 Digest Gen. Key/Key Pair Wrap & Unwrap Derive
CKM_SECURID_KEY_GEN            
CKM_SECURID            
CKM_HOTP_KEY_GEN            
CKM_HOTP            
CKM_ACTI_KEY_GEN            
CKM_ACTI            

Key Objects

OTP key objects (object class CKO_OTP_KEY) hold secret keys used by OTP tokens. Key type for ActivIdentity ACTI secret keys is CKK_ACTI.

Key Objects Attributes

This table lists the common OTP key attributes:

Attribute Data Type Meaning
CKA_OTP_FORMAT CK_ULONG

Format of OTP values produced with this key:

  • CK_OTP_FORMAT_DECIMAL = Decimal (default) (UTF8-encoded)

  • CK_OTP_FORMAT_HEXADECIMAL = Hexadecimal (UTF8-encoded)

  • CK_OTP_FORMAT_ALPHANUMERIC = Alphanumeric (UTF8-encoded)

  • CK_OTP_FORMAT_BINARY = Only binary values.

CKA_OTP_LENGTH CK_ULONG Default length of OTP values (in the CKA_OTP_FORMAT) produced with this key.
CKA_OTP_USER_FRIENDLY_MODE CK_BOOL

CK_TRUE (meaning the token is capable of returning OTPs suitable for human consumption)
CKA_OTP_CHALLENGE_REQUIREMENT CK_ULONG

Parameter requirements when generating OTP values with this key:

  • CK_OTP_PARAM_MANDATORY = A challenge must be supplied.

  • CK_OTP_PARAM_OPTIONAL = A challenge may be supplied but need not be. (should never happen in this middleware)

  • CK_OTP_PARAM_IGNORED = A challenge, if supplied, will be ignored.

CKA_OTP_TIME_REQUIREMENT CK_ULONG

Parameter requirements when generating OTP values with this key:

  • CK_OTP_PARAM_MANDATORY = A time value must be supplied.

  • CK_OTP_PARAM_OPTIONAL = A time value may be supplied but need not be.

  • CK_OTP_PARAM_IGNORED = A time value, if supplied, will be ignored.

CKA_OTP_COUNTER_REQUIREMENT CK_ULONG

Parameter requirements when generating OTP values with this key:

  • CK_OTP_PARAM_MANDATORY = A counter value must be supplied.

  • CK_OTP_PARAM_OPTIONAL = A counter value may be supplied but need not be.

  • CK_OTP_PARAM_IGNORED = A counter value, if supplied, will be ignored.

CKA_OTP_COUNTER Byte array Value of the associated internal counter. Default value is empty (i.e. ulValueLen = 0). For ACTI keys, value shall be an 8 bytes unsigned integer in big endian (i.e. network byte order) form.
CKA_OTP_TIME RFC 2279 string Value of the associated internal UTC time in the form YYYYMMDDhhmmss. Default value is empty (i.e. ulValueLen= 0).
CKA_OTP_SERVICE_IDENTIFIER RFC 2279 string Text string that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0).

For OTP tokens with multiple keys, the keys may be enumerated using C_FindObjects.

The CKA_OTP_SERVICE_IDENTIFIER attribute is used to distinguish between keys.

Proprietary Key Attributes

Attribute Data Type Meaning
CKA_OTP_DERIVATION CK_BOOL Set to CK_TRUE if the derivation flag is set (flag indicating whether the secret key used in the synchronous authentication algorithm is derived at each authentication). Default value: set to CK_FALSE.
CKA_OTP_COUNTER_INCREMENT CK_BOOL Set to CK_TRUE if the counter increment flag is set (flag indicating whether the counter used in the synchronous authentication algorithm is increased at each authentication). Default value: set to CK_FALSE.

Proprietary key attributes are defined as follows:

#define CKA_OTP_DERIVATION		CKA_VENDOR_DEFINED + 0x00000330
#define CKA_OTP_COUNTER_INCREMENT	 CKA_VENDOR_DEFINED + 0x00000331

Mechanism Parameters

Parameters Type

Parameter Data Type Meaning
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_VALUE Byte array An actual OTP value. This parameter type is intended for C_Sign output, see below.

OTP Mechanisms Flags

Attribute Mask Meaning
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_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.

Parameters Structures

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_ULONG ulValueLen;
} CK_OTP_PARAM;

The fields of the structure have the following meanings:

  • type is the parameter type

  • pValue is the pointer to the value of the parameter

  • ulValueLen is the length in bytes of the value

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;

The fields of the structure have the following meanings:

  • pParams is the pointer to an array of OTP parameters

  • ulCount is the number of parameters in the array

OTP Functions

The functions used to compute an OTP are:

  • C_SignInit

  • C_Sign

in the context and conditions that have previously been described.

When calling C_SignInit with the CKM_ACTI 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 CHALLENGE, TIME, or COUNTER.

CK_OTP_SIGNATURE_INFO is a structure that is returned by all OTP mechanisms in successful calls to C_Sign. 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;

The fields of the structure have the following meanings:

  • pParams is the pointer to an array of OTP parameter values

  • ulCount is the number of parameters in the array

After successful calls to C_Sign 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 follows the convention described above (7.8.2) on producing output, a call to C_Sign 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 signing or verifying using the CKM_ACTI mechanism, pData shall be set to NULL_PTR and ulDataLen shall be set to 0.