--- title: "AAL2GenUnlockAuthCode" slug: "a3s-cppprg-aal2genunlockauthcode-4-0" updated: 2026-11-11T09:57:24Z published: 2026-11-11T09:57:24Z canonical: "docs.onespan.com/a3s-cppprg-aal2genunlockauthcode-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. # AAL2GenUnlockAuthCode ## Function prototype ```cpp aat_int32 AAL2GenUnlockAuthCode (                                  TDigipassBlob*   DPData,                                  TKernelParms*    CallParms,                                  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_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 (recommended buffer size is 9 bytes). | | aat_int32 * | UnlockAuthCounter | O | Optional value. This parameter receives the counter value used to generate the unlock authentication code. | ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 812 | Invalid unlock authentication index | | 138 | Unlock function not supported | 1000 | Function does not support EMV-CAP | | 412 | Invalid checksum | 1104 | Virtual token is not a primary token | | 413 | Invalid Base64 format | 1118 | Unsupported BLOB | | 510 | Invalid Digipass data pointer | -1501 | Memory allocation failed | | 811 | Invalid unlock authentication code pointer | | |