Synchronize token and host

This article describes the function(s) on which the synchronize token and host functionality is based. It contains information about parameters and possible return codes, as well as a prototype for each function.

AAL2SyncTokenAndHostICSF

Function prototype

aat_int32 AAL2SyncTokenAndHostICSF (
                                TDigipassBlob*   DPBlob,
                                TKernelParms*    RunTimeParms,
                                aat_ascii*       aStorageKeyNameIn,
                                aat_ascii*       aInitialVectorIn,
                                aat_ascii*       Password1,
                                aat_ascii*       Challenge1,
                                aat_ascii*       Password2,
                                aat_ascii*       Challenge2);

Description

Based on two contiguous Digipass responses, this function synchronizes one of the following:

• The host time with the Digipass time.
• The host event counter with the Digipass event counter.

This function can either be used for the following:

• Time-based-only algorithms
• Event-based-only algorithms

Time- and event-based algorithms are not supported.

The AAL2GetTokenInfoEx function can be used to retrieve the algorithm: TIME BASED, EVENT BASED, TIME AND EVENT BASED.

For time-based Challenge/Response Digipass authenticators, the CheckChallenge kernel parameter must be set to 4 for the synchronization (i.e. to allow two consecutive authentication requests in the same time step).

Time-based only algorithm

This function can be called to fix the following scenarios:

• A valid password (response) generated by a Digipass authenticator is rejected because the Digipass authenticator has not been used for a long period of time.
• A Digipass clock has drifted too far and is now outside the time synchronization window.

• Now, a valid password (response) generated from the Digipass is rejected by the HOST.

After calling AAL2SyncTokenAndHost, the new time drift is stored in the authenticator application BLOB, and a valid password will be accepted again.

With VACMAN Controller 3.7.10 and later/Authentication Suite Server SDK, this function will use the SyncWindow kernel parameter instead of iTimeWindow as a reference for the synchronization time window limit.

Event-based only algorithm

This function can be called to fix the following scenario:

1. The Digipass authenticator generates a password (response) based on event 1000.
2. A validation is performed on the host with this password so that this event is stored in the authenticator application BLOB.
3. The Digipass user then generates another ten passwords without a validation on the host.
4. The Digipass authenticator generates a password based on event 1011.
5. A validation is attempted on the host with this password.
6. The event window is too small and the host rejects this valid password because it is outside the event synchronization window.

After calling AAL2SyncTokenAndHost, the event used to generate the last of the two contiguous responses is stored in the authenticator application BLOB, and a valid password will be accepted again.

For event-based Digipass authenticators to work properly, AAL2SyncTokenAndHost must be used with the EventWindow kernel parameter greater than with the validation with AAL2VerifyPassword. If the same EventWindow is used, the synchronization will fail for the same reasons as the authentication (Digipass event outside the event synchronization window).

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 two consecutive passwords, it returns either SUCCESS or SUCCESS with the relevant scoring warning code. See the list of return codes in Table: Return codes (AAL2SyncTokenAndHostICSF) for more details.

Parameters

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

COBOL calling convention

Entry point: AA2STAHI
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-RETURN          PIC S9(8) USAGE BINARY.
02   W-PASSWORD1       PIC X(17).
02   W-CHALLENGE1      PIC X(17).
02   W-PASSWORD2       PIC X(17).
02   W-CHALLENGE2      PIC X(17).
02   W-STORAGEKEY      PIC X(65).
02   W-INITVECTOR      PIC X(17).
02   W-API-NAME         PIC X(8) VALUE 'AA2STAHI'.
. . .
     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-PASSWORD1
           BY REFERENCE W-CHALLENGE1
           RETURNING W-RETURN

Return codes