--- title: "AAL2SyncTokenAndHostICSF" slug: "a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0" updated: 2026-11-11T09:54:58Z published: 2026-11-11T09:54:58Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # AAL2SyncTokenAndHostICSF ## Function prototype ```cpp 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)](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#TAB_Return_codes) for more details. ## Parameters > The memory management of the output parameters must be performed by the calling function. | Type | Name | Use | Description | | --- | --- | --- | --- | | TDigipassBlob * | DPBlob | I/O | authenticator application BLOB. Upon return from the function call, this BLOB must be rewritten to the application database to reflect 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 HSM storage key used to encrypt the sensitive authenticator applicationBLOB 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 * | Password1 | 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 device. | | aat_ascii * | Challenge1 | I | Up to 16 numeric characters, left justified, null terminated or right padded with spaces. This parameter holds the challenge that was proposed to the user to generate CodeToVerify. If no challenge was generated, this parameter should be NULL. | | aat_ascii * | Password2 | I | String of up to 17+24 numeric or hexadecimal characters, left-justified, null-terminated or right-padded with spaces. This is the next password generated by the Digipass device. | | aat_ascii * | Challenge2 | I | Up to 16 numeric characters, left justified, null terminated or right padded with spaces. This parameter holds the challenge that was proposed to the user to generate CodeToVerify. If no challenge was generated, this parameter should be NULL. | ## COBOL calling convention ```custom 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 | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 510 | Invalid Digipass data pointer | | 10001 | Success with context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 802 | Change password mandatory | | 10002 | Success with user warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 803 | New password too short | | 10003 | Success with user & context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 804 | New password too long | | 10004 | Success with platform warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 900 | Invalid session context handle | | 10005 | Success with platform & context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 908 | HSM key not found | | 10006 | Success with platform & user warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 951 | Invalid HSM key type for HSM decryption | | 10007 | Success with platform & user & context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#Cite_1) | 1116 | Response check digit not allowed | | 1 | Code not verified | 1117 | Challenge check digit not allowed | | 2 | Static password validation failed | 1118 | Unsupported BLOB | | 130 | Invalid response pointer | -101 | Challenge too short | | 131 | Missing required challenge | -102 | Challenge too long | | 132 | Unsupported token type | -103 | Challenge check digit wrong | | 140 | Challenge corrupted | -108 | Challenge character invalid | | 201 | Code replay attempt | -201 | Response length out of bounds | | 202 | Identification error threshold reached | -202 | Response too short | | 205 | Inactive days reached | -203 | Response too long | | 208 | Application disabled | -204 | Response check digit wrong | | 412 | Invalid checksum (software) | -205 | Response character not decimal | | 413 | Invalid Base64 format | -206 | Response character not hexadecimal | | 414 | Invalid checksum (HSM) | | | 1. Specific score-based authentication code (see [Score-based DIGIPASS](/secsdks/docs/a3s-cppprg-icsf-zos-aal2synctokenandhosticsf-4-0#scorebased-digipass))