AAL2VerifyPasswordEs

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

Function prototype

aat_int32 AAL2VerifyPasswordEs (
                                TDigipassBlob   *DPData,
                                TKernelParms    *CallParms,
                                aat_ascii       *aResponseIn,
                                aat_ascii       *ChallengeIn,
                                aat_ascii       *aServerPublicKey,
                                aat_ascii       *aReturnHostCodeOut,
                                aat_ascii       *ReturnHostCodeLenOut);

Description

This function is an extension of AAL2VerifyPasswordEx, 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.

This parameter is optional. If it is not used, this function is identical with AAL2VerifyPasswordEx.

The enhanced authentication feature is supported by Digipass 110 and Digipass for Web.

Parameters

  Table: Parameters (AAL2VerifyPasswordEs)
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 *aServerPublicKeyIString 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.
aat_ascii *ReturnHostCode OString 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-153Server public key too long
208Application disabled-201Response length out of bounds
412Invalid checksum-202Response too short
413Invalid Base64 format-203Response too long
510Invalid Digipass data pointer-204Response check digit wrong
600Invalid Gordian root information-205Response character not decimal
601Invalid Gordian today information-206Response character not hexadecimal
602Invalid Gordian tomorrow information-207Response character set not specified
603Invalid Gordian stimulus information-1501Memory allocation failed
  1. Specific score-based authentication code (see Score-based DIGIPASS)