AAL2VerifyPasswordICSF

Function prototype (aal2sdk.h)

aat_int32 AAL2VerifyPasswordICSF (
                               TDigipassBlob*   DPBlob,
                               TKernelParms*    CallParms,
                               aat_ascii*       aStorageKeyNameIn,
                               aat_ascii*       aInitialVectorIn,
                               aat_ascii*       aResponseIn,
                               aat_ascii*       aChallengeIn,
                               aat_ascii*       ReturnHostCode,
                               aat_int32*       ReturnHostCodeLength);

Description

The AAL2VerifyPasswordICSF function performs Digipass owner's authentication by controlling if a given Digipass-generated dynamic password is valid for a specified Digipass described by its application BLOB DPBlob. Optionally, the previously generated Challenge is also passed to this function.

Retrurn host code

In addition, a new feature is present that allows a client to authenticate back the Host server that validated the dynamic password.

It facilitates a two way authentication process. The server validates the user's dynamic password and returns a host code as an acknowledgement that the user is able to verify on its Digipass.

This allows the end user to be sure that the host server is the correct one. This function is particularly useful for web implementations.

GO1 integration

This function can also be used for static PIN management for Digipass GO 1 or Digipass GO 3. In this case a password could have different appearances as in the examples below:

• No static PIN - Regular password authentication request 89574526
• Static PIN - Same authentication request in combination with static PIN usage 123489574526, the static PIN is entered before the dynamic password, the AAL2VerifyPasswordICSF function will evaluate static PIN and dynamic password in sequence.
• Static PIN Change - Same authentication request in combination with static PIN usage and a request for PIN change 12348957452643214321. The static PIN is entered before the dynamic password and both New PIN + New PIN confirmation are entered after. The AAL2VerifyPasswordICSF function will evaluate static PIN and dynamic password in sequence then process for a PIN change.

This function allows the customer to address the HSM storage key by name and to specify an initial vector. The initial vector is used during the 3DES/AES decryption/encryption of the sensitive data of the authenticator application BLOB.

Score-based Digipass

For Digipass devices that integrate the score-based algorithm, Authentication Suite Server SDK performs a score-based authentication which allows retrieving the Digipass scoring value. Once Authentication Suite Server SDK has successfully validated the password, it returns either SUCCESS or SUCCESS with the relevant scoring warning code. See the list of return codes in Table: Return codes (AAL2VerifyPasswordICSF) for more details.

Parameters

The memory management of the output parameters must be performed by the calling function.

COBOL calling convention

Entry point: AA2VVPIC
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-INITVECTOR      PIC X(17).
02   W-API-NAME        PIC X(8) VALUE 'AA2VVPIC'.
. . .
     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-HOSTCODE
           BY REFERENCE W-HOSTCODE-LENGTH
           RETURNING W-RETURN

Return codes

* Specific score-based authentication codes; see  Score-based Digipass.