AAL2VerifyPasswordEsICSF

Function prototype

aat_int32 AAL2VerifyPasswordEsICSF (
                               TDigipassBlob*   DPData,
                               TKernelParms*    CallParms,
                               aat_ascii*       aStorageKeyNameIn,
                               aat_ascii*       aInitialVectorIn,
                               aat_ascii*       aResponseIn,
                               aat_ascii*       aChallengeIn,
                               aat_ascii*       aServerPublicKey,
                               aat_ascii*       aReturnHostCodeOut,
                               aat_int32*       ReturnHostCodeLenOut);

Description

This function is an extension of AAL2VerifyPasswordICSF, offering the enhanced security feature. This feature prevents potential man-in-the-middle attacks in the architecture integrating software Digipass. 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 AAL2VerifyPasswordICSF.

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

Digipass 110 and DIGIPASS for Web have been discontinued.

Parameters

Table: Parameters (AAL2VerifyPasswordEsICSF)
Type	Name	Use	Description
TDigipassBlob *	DPData	I/O	authenticator application BLOB. Upon return from the function call, this BLOB must be rewritten to the application database to reflect the changes.
TKernelParms *	CallParms	I	Structure of runtime parameters to use during this function call.
aat_ascii *	aStorageKeyNameIn	I	String of up to 64+1 characters, left-justified, null-terminated, or right-padded with spaces. This is the label of the ICSF storage key used to encrypt the sensitive Digipass application BLOB data.
aat_ascii *	aInitialVectorIn	I	String of 16 or 32 hexadecimal characters, left-justified, null-terminated. 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 dynamic password generated by the Digipass.
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 may have been proposed to the user to generate the password to verify. 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.
aat_ascii *	ReturnHostCode	O	String 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 *	ReturnHostCodeLength	O	Pointer to a long integer that will contain the length of the return host code which has been generated.

COBOL calling convention

Entry point: AA2VPEIC
02   W-BLOB             PIC X(248).
02   W-KERNELPARMS.
     03   W-PARMCOUNT   PIC 9(8) USAGE BINARY.
     03   W-PARM01      PIC 9(8) USAGE BINARY.
     . . .
     03   W-PARM19      PIC 9(8) USAGE BINARY.
02   W-HOSTCODE         PIC X(17).
02   W-HOSTCODE-LENGTH  PIC 9(8) USAGE BINARY.
02   W-RETURN           PIC S9(8) USAGE BINARY.
02   W-PASSWORD         PIC X(17).
02   W-CHALLENGE        PIC X(17).
02   W-STORAGEKEY       PIC X(65).
02   W-SERVER-PUBKEY    PIC X(1025).
02   W-INITVECTOR       PIC X(17).
02   W-API-NAME          PIC X(8) VALUE 'AA2VPEIC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-BLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY REFERENCE W-PASSWORD
           BY REFERENCE W-CHALLENGE
           BY REFERENCE W-SERVER-PUBKEY
           BY REFERENCE W-HOSTCODE
           BY REFERENCE W-HOSTCODE-LENGTH
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2VerifyPasswordEsICSF)
Code	Meaning	Code	Meaning
0	Success	804	New password too long
1000	Success with context warning[1]	806	Static password change not supported
1000	Success with user warning[1]	900	Invalid session context handle
1000	Success with user & context warning[1]	908	HSM key not found
1000	Success with platform warning[1]	951	Invalid HSM key type for HSM decryption
1000	Success with platform & context	1039	Invalid response length with DP algorithm
1000	Success with platform & user warning[1]	1040	Invalid host code length with DP algorithm
1000	Success with platform & user & context	1103	Unlock Version 2 not supported
1	Code not verified	1116	Response check digit not allowed
2	Static password validation failed	1117	Challenge check digit not allowed
130	Invalid response pointer	1118	Unsupported BLOB
131	Missing required challenge	-101	Challenge too short
132	Unsupported token type	-102	Challenge too long
140	Challenge corrupted	-103	Challenge check digit wrong
201	Code replay attempt	-105	Challenge minimum length not allowed
202	Identification error threshold reached	-106	Challenge maximum length not allowed
205	Inactive days reached	-107	Challenge number wrong
208	Application disabled	-108	Challenge character invalid
412	Invalid checksum (software)	-153	Server public key too long
413	Invalid Base64 format	-201	Response length out of bounds
414	Invalid checksum (HSM)	-202	Response too short
510	Invalid Digipass data pointer	-203	Response too long
600	Invalid Gordian root information	-204	Response check digit wrong
601	Invalid Gordian today information	-205	Response character not decimal
602	Invalid Gordian tomorrow information	-206	Response character not hexadecimal
603	Invalid Gordian stimulus information	-207	Response character set not specified
802	Change password mandatory	-1501	Memory allocation failed
803	New password too short

Specific score-based authentication code (see Score-based DIGIPASS)