AAL2VerifyPasswordEx

  • Published on Jul 9, 2025
  • 1 minute(s) read
Prev Next

Function prototype

aat_int32 AAL2VerifyPasswordEx (
                                TDigipassBlob*   DPData,
                                TKernelParms*    CallParms,
                                aat_ascii*       Password,
                                aat_ascii*       Challenge,
                                aat_ascii*       ReturnHostCode,
                                aat_ascii*       ReturnHostCodeLength);

Description

This function is an extension of AAL2VerifyPassword. The functionality is identical except for the additional feature of integrating the return host code.

Return host code

By facilitating a two-way authentication process, this feature allows a client to back-authenticate the server that validates the dynamic password. The server validates the user's dynamic password and returns a host code with which the user can be sure that the authentication happened on the correct server. This function is particularly useful for web implementations.

Parameters

  Table: Parameters (AAL2VerifyPasswordEx)
TypeNameUseDescription
TDigipassBlob *DPDataI/Oauthenticator application BLOB. Upon return from the function call, this BLOB must be rewritten to the application database to reflect changes.
TKernelParms *CallParmsIStructure of runtime parameters to use during this function call.
aat_ascii *PasswordI

String of up to 17+24 numeric or hexadecimal characters, left-justified, null-terminated or right-padded with spaces. This is the dynamic password generated by the Digipass authenticator.

aat_ascii *ChallengeI

String of up to 17 numeric or hexadecimal characters, left-justified, null-terminated, or right-padded with spaces. This parameter holds the challenge that was proposed to the user to generate the password to verify. If no challenge was generated, this parameter should be NULL.

aat_ascii *ReturnHostCodeOString of up to 17 numeric or hexadecimal characters, left-justified, null-terminated, or right-padded with spaces. This is the code generated by Authentication Suite Server SDK (recommended buffer size is 18 bytes).
aat_int32 *ReturnHostCodeLengthOPointer to a long integer that indicates the length of the generated return host code.

Return codes

  Table: Return codes (AAL2VerifyPasswordEx)
CodeMeaningCodeMeaning
0Success802Change password mandatory
10001Success with context warning[1]803New password too short
10002Success with user warning[1]804New password too long
10003Success with user & context warning[1]1039Invalid response length with DP algorithm
10004Success with platform warning[1]1040Invalid host code length with DP algorithm
10005Success with platform & context warning[1]1103Unlock Version 2 not supported
10006Success with platform & user warning[1]1116Response check digit not allowed
10007Success with platform & user & context warning[1]1117Challenge check digit not allowed
1Code not verified1118Unsupported BLOB
2Static password validation failed-101Challenge too short
130Invalid response pointer-102Challenge too long
131Missing required challenge-103Challenge check digit wrong
132Unsupported token type-105Challenge minimum length not allowed
140Challenge corrupted-106Challenge maximum length not allowed
201Code replay attempt-107Challenge number wrong
202Identification error threshold reached-108Challenge character invalid
205Inactive days reached-201Response length out of bounds
208Application disabled-202Response too short
412Invalid checksum-203Response too long
413Invalid Base64 format-204Response check digit wrong
510Invalid Digipass data pointer-205Response character not decimal
600Invalid Gordian root information-206Response character not hexadecimal
601Invalid Gordian today information-207Response character set not specified
602Invalid Gordian tomorrow information-1501Memory allocation failed
603Invalid Gordian stimulus information  
  1. Specific score-based authentication code (see Score-based DIGIPASS)