AAL2GenUnlockAuthCodeICSF

Function prototype

aat_int32 AAL2GenUnlockAuthCodeICSF (
                                 TDigipassBlob*   DPData,
                                 TKernelParms*    CallParms,
                                 aat_ascii*       aStorageKeyNameIn,
                                 aat_ascii*        aInitialVectorIn,
                                 aat_int32        UnlockAuthIndex,
                                 aat_ascii*       UnlockAuthCode,
                                 aat_int32*       UnlockAuthCounter);

Description

If a user's Digipass authenticator is locked because of wrong PIN entries, the Digipass administrator has to authenticate the user before verifying the Digipass unlock code. This function generates unlock authentication codes, which are used to authenticate the user during a Digipass unlock operation. AAL2AuthorizeUnlock validates the unlock authentication code before generating the unlock code.

An unlock authentication code is valid only once. After it has been used, a new unlock authentication code needs to be generated. It is possible to generate multiple unlock authentication codes at a time.

Important notes

• Unlock authentication codes need to be used in the given sequence. Codes that are skipped will no longer be valid.
• It is not mandatory to implement the unlock user authentication in the way described. OneSpan proposes this function as an option but the integrator is free to implement other authentication mechanisms. However, OneSpan strongly recommends that you implement a strong authentication process in any unlock scheme.
• In case of Unlock V2 support, the unlock authentication code generation function must be used with the dedicated Unlock V2 BLOB instead of the Digipass authentication BLOB.

Parameters

COBOL calling convention

Entry point: AA2GUAIC
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-RANDOM-NBR         PIC X(9).
02   W-UNLOCK-AUTHCODE    PIC X(9).
02   W-STORAGEKEY         PIC X(65).
02   W-INITVECTOR         PIC X(17).
02   W-RETURN             PIC S9(8) USAGE BINARY.
02   W-UNLOCK-INDEX       PIC S9(8) USAGE BINARY.
02   W-UNLOCK-COUNTER     PIC S9(8) USAGE BINARY.
02   W-API-NAME            PIC X(8) VALUE 'AA2GUAIC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-BLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY VALUE W-UNLOCK-INDEX
           BY REFERENCE W-UNLOCK-AUTHCODE
           BY REFERENCE W-UNLOCK-COUNTER
           RETURNING W-RETURN

Return codes