Authentication Suite Server SDK for Thales ProtectServer HSM is based on two different modules, a host module (host API) and an HSM module (FM module). All Authentication Suite Server SDK command transactions with the FM module are executed using the C_Digest method of the Thales ProtectServer HSM host API.
Authentication Suite Server SDK FM command transaction with C_Digest
The Authentication Suite Server SDK for HSM functionalities are categorized as follows:
- Functionalities that use the HSM
- Functionalities that do not use the HSM
The functionalities related to the HSM are based on two Authentication Suite Server SDK functions. The first function generates a command for the FM module, the second function processes the HSM's reply returned by the FM module.
The FM module extends the C_Digest() method of the Thales ProtectServer HSM host API to support execution of Authentication Suite Server SDK command transactions. With the C_Digest() method of the Thales ProtectServer HSM host API, an Authentication Suite Server SDK command message can be sent to the FM module. The Authentication Suite Server SDK command message is a buffer generated by the Authentication Suite Server SDK host API function AAL2GenxxxxCmd of Authentication Suite Server SDK for Thales ProtectServer HSM. As a result in this case, the C_Digest() method returns an Authentication Suite Server SDK reply message, which is a buffer generated by the FM module and needs to be processed by the Authentication Suite Server SDK host API function AAL2ProcxxxxRpl of Authentication Suite Server SDK for Thales ProtectServer HSM.
The functionalities related to the HSM need one or more HSM keys to work. You need to ensure that the proper HSM key(s) are created before.
HSM keys used by Authentication Suite Server SDK for HSM are either HSM storage keys and/or HSM transport keys in case of Digipass applications.
The C_Digest() call must contain the following input data bytes (pData parameter):
- x bytes containing the Authentication Suite Server SDK command
Figure: Input data bytes in C-Digest for an Authentication Suite Server SDK command transaction
The C_Digest() call produces the following output digest bytes (pDigest parameter):
- x bytes containing the Authentication Suite Server SDK reply
Figure: Output digest bytes in C-Digest for an Authentication Suite Server SDK command transaction
To execute Authentication Suite Server SDK command transactions with the FM module using the C_Digest() method, it is not required to initialize first a particular digesting mechanism with the C_DigestInit() method.
When a Cryptoki session is opened without first initializing a particular digesting mechanism with the C_DigestInit() method, the active digesting mechanism used by the C_Digest() method for this Cryptoki session will be initialized by default to execute Authentication Suite Server SDK command transactions.
Execution of Authentication Suite Server SDK command transactions with the FM module requires using the single-part digesting method C_Digest(). Multi-part digesting methods (C_DigestUpdate(), C_DigestKey(), C_DigestEncryptUpdate(), C_DecryptDigestUpdate() and C_DigestFinal()) do not support execution of Authentication Suite Server SDK command transactions.
Using C_Digest to perform other digesting mechanisms
The Authentication Suite Server SDK FM module overloads the C_Digest() method of the Thales ProtectServer HSM host API. Prior to VACMAN Controller for Thales ProtectServer HSM 3.18.0, it was not possible to use the C_Digest() method for standard digesting mechanisms (for example CKM_SHA_1 meaning SHA1 hashing) when the FM module was uploaded into the HSM.
As of VACMAN Controller for Thales ProtectServer HSM 3.18.0, it has been possible to use the C_Digest() method for the execution of Authentication Suite Server SDK command transactions, or for the execution of standard digesting mechanisms (for example SHA1 hashing).
When a Cryptoki session is opened without first initializing a particular digesting mechanism with the C_DigestInit() method, the active digesting mechanism used by the C_Digest() method for this Cryptoki session will be initialized by default to execute Authentication Suite Server SDK command transactions (see Authentication Suite Server SDK FM command transaction with C_Digest).
When a digesting mechanism has been initialized for a given Cryptoki session with the C_DigestInit() method to perform a standard digesting mechanism (for example SHA1 hashing), the C_Digest() method will no longer perform execution of Authentication Suite Server SDK command transactions for this Cryptoki session. In this case (Cryptoki session already initialized with a standard mechanism), if execution of Authentication Suite Server SDK command transaction(s) using the same Cryptoki session is required, it is necessary to explicitly initialize the digesting mechanism with the custom mechanism 0xC000F001 implemented within the FM module (see Example).
Example
CK_RV rv = CKR_OK;
CK_SESSION_HANDLE hSession;
CK_SLOT_ID slotID = 0;
CK_MECHANISM mech;
CK_BYTE bCommand[] = {0x30, 0x00}; // VC Command Buffer to get the FM library version
CK_BYTE bReply[8192];
CK_ULONG CmdSize = sizeof(bCommand);
CK_ULONG ReplySize = sizeof(bReply);
// Open a new Cryptoki session
rv = C_OpenSession(slotID,
CKF_RW_SESSION|CKF_SERIAL_SESSION,
NULL,
NULL,
&hSession);
if (rv) return (rv);
// No digesting mechanism has been initialized for this Cryptoki session,
// C_Digest will then execute VC command transaction by default
// i.e: bReply will contain the VC reply of the VC command bCommand
ReplySize = sizeof(bReply);
rv = C_Digest(hSession,
bCommand,
(CK_ULONG)CmdSize,
bReply,
(CK_ULONG_PTR)&ReplySize);
if (rv)
{
C_CloseSession(hSession);
return (rv);
}
// Initialize digesting mechanism with SHA1 hash mechanism for this
// Cryptoki session
memset(&mech, 0, sizeof(CK_MECHANISM));
mech.mechanism = CKM_SHA_1;
rv = C_DigestInit(hSession,
&mech);
if (rv)
{
C_CloseSession(hSession);
return (rv);
}
// Digesting mechanism has been initialized with SHA1 hash mechanism
// for this Cryptoki session:
// C_Digest will then now perform SHA1 hashing
// i.e: bReply will contain the hash value of bCommand
ReplySize = sizeof(bReply);
rv = C_Digest(hSession,
bCommand,
(CK_ULONG)CmdSize,
bReply,
(CK_ULONG_PTR)&ReplySize);
if (rv)
{
C_CloseSession(hSession);
return (rv);
}
// Digesting mechanism has been already initialized
// (with SHA1 hash mechanism) for this Cryptoki session
// To execute VC command transaction(s) with this Cryptoki session,
// it is necessary to re-initialize the digesting mechanism to execute
// 'VC Command Transaction': custom mechanism 0xC000F001
memset(&mech, 0, sizeof(CK_MECHANISM));
mech.mechanism = 0xC000F001UL;
rv = C_DigestInit(hSession,
&mech);
if (rv)
{
C_CloseSession(hSession);
return (rv);
}
// Digesting mechanism has been initialized with 'VC Command Transaction'
// mechanism for this Cryptoki session:
// C_Digest will then now execute VC command transaction
// i.e: bReply will contain the VC reply of the VC command bCommand
ReplySize = sizeof(bReply);
rv = C_Digest(hSession,
bCommand,
(CK_ULONG)CmdSize,
bReply,
(CK_ULONG_PTR)&ReplySize);
if (rv)
{
C_CloseSession(hSession);
return (rv);
}
rv = C_CloseSession(hSession);
return (rv);