--- title: "AAL2GenUnlockAuthCodeICSF" slug: "a3s-cppprg-icsf-zos-aal2genunlockauthcodeicsf-4-0" updated: 2026-11-11T09:57:24Z published: 2026-11-11T09:57:24Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2genunlockauthcodeicsf-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. # AAL2GenUnlockAuthCodeICSF ## Function prototype ```cpp 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 | 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 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_int32 | UnlockAuthIndex | I | This parameter contains the unlock authentication index value; possible parameter values range from 0 to 5: - 0: current unlock authentication code - 1: next unlock authentication code - 2: … | | aat_ascii * | UnlockAuthCode | O | Unlock authentication code. 8 numeric characters which the user needs to provide to the administrator for authentication during a Digipass unlock procedure. | | aat_int32 * | UnlockAuthCounter | O | Optional value. This parameter receives the counter value used to generate the unlock authentication code. | ## COBOL calling convention ```custom 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 | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 812 | Invalid unlock authentication index | | 138 | Unlock function not supported | 900 | Invalid session context handle | | 412 | Invalid checksum (software) | 908 | HSM key not found | | 413 | Invalid Base64 format | 1000 | Function does not support EMV-CAP | | 414 | Invalid checksum (HSM) | 1104 | Virtual token is not a primary token | | 510 | Invalid Digipass data pointer | 1118 | Unsupported BLOB | | 811 | Invalid unlock authentication code pointer | -1501 | Memory allocation failed |