Function prototype
aat_int32 AAL2GenVerifyPasswordEsCmd(
aat_byte *Cmd,
aat_int32 *CmdSize,
TDigipassBlob *DPData,
TKernelParms *CallParms,
aat_ascii *aStorageKeyNameIn,
aat_ascii *aIVIn,
aat_ascii *aResponseIn,
aat_ascii *aChallengeIn,
aat_ascii *aServerPublicKey);
Description
This function extends AAL2GenVerifyPasswordCmdEx by offering the enhanced security feature. This feature prevents potential man-in-the-middle attacks in the architecture integrating software Digipass authenticators. A server public key, such as a certificate, can be used in input to diversify the challenge.
The password validation with enhanced security on the HSM is identical to the functionality available with the Authentication Suite Server SDK Software Dynamic Authentication Service. For information on the associated functions, refer to the Authentication Suite Server SDK C-C++ Programmer's Guide.
This function must be used with the post-HSM API AAL2ProcVerifyPasswordEsRpl.
Parameters
Table: Parameters (AAL2GenVerifyPasswordEsCmd) | Type | Name | Use | Description |
|---|
| aat_byte * | Cmd | O | Up to 1524 bytes that serialize the VERIFY PASSWORD command type and the input data to the verify password function on the HSM: - Command type - 2 bytes
- Digipass data block - 192 bytes
- Runtime parameters - 80 bytes
- StorageKeyName - up to 128 characters
- InitialVector - 8 bytes
- Password - up to 41 characters
- Challenge - up to 17 characters
- Server public key - up to 1024 characters
- Host time - 4 bytes
Plus 28 bytes for Authentication Suite Server SDK internal use. |
| aat_int32 * | CmdSize | I/O | On entry, this parameter contains the size of the Cmd buffer.On exit, this parameter contains the length of the Cmd message. |
| TDigipassBlob * | DPData | I | Digipass description data block. |
| TKernelParms* | CallParms | I | Structure of runtime parameters to use during this function call. |
| aat_ascii * | aStorage KeyNameIn | I | String of up to 128+1 characters, left-justified, null-terminated, or right-padded with spaces. This is the label of the HSM storage key used to encrypt the sensitive Digipass application BLOB data. |
| aat_ascii * | aIVIn | I | String of 16 hexadecimal characters, left-justified, null-terminated, or right-padded with spaces. This is the initial vector used to encrypt the sensitive authenticator application BLOB data. |
| aat_ascii * | aResponseIn | I | String of up to 17+24 numeric or hexadecimal characters, left-justified, null-terminated or right-padded with spaces. This is the dyamic password generated by the Digipass authenticator. |
| aat_ascii * | aChallengeIn | I | String of up to 17 numeric characters, left-justified, null-terminated, or right-padded with spaces. This parameter holds the challenge that was proposed to the user to generate CodeToVerify. If no challenge was generated, this parameter should be NULL. |
| aat_ascii * | aServerPublicKey | I | String of up to 1024 hexadecimal characters, null-terminated. This parameter is used as a diversifier to prevent man-in-the-middle attacks. If this parameter is NULL, diversification will not take place. |
Return codes
Table: Return codes (AAL2ProcVerifyPasswordRpl) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 510 | Invalid Digipass data pointer |
| 130 | Invalid response pointer | 590 | Invalid command pointer |
| 149 | Invalid initial vector length | 706 | Invalid data buffer pointer |
| 412 | Invalid checksum (software) | 1018 | Invalid TLV item pointer |
| 413 | Invalid Base64 format | 1025 | Data buffer too small |