--- title: "AAL2UnlockICSF" slug: "a3s-cppprg-icsf-zos-aal2unlockicsf-4-0" updated: 2026-11-11T09:54:58Z published: 2026-11-11T09:54:58Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2unlockicsf-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. # AAL2UnlockICSF ## Function prototype (aal2sdk.h) ```cpp aat_int32 AAL2UnlockICSF ( TDigipassBlob* DPBlob, TKernelParms* CallParms, aat_ascii* aStorageKeyNameIn, aat_ascii* aInitialVectorIn, aat_ascii* aRandomNumberIn, aat_ascii* aUnlockCode); ``` ## Description If a user's Digipass authenticator is locked because of wrong PIN entries, the Digipass administrator will be able to unlock the Digipass authenticator using this function. It obtains the initialized unlock information of the user's Digipass authenticator from the authenticator application BLOB and performs the unlock code calculation. This function generates an unlock code that the user enters in their Digipass authenticator in response to the currently displayed random number. ## 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. | | TKernelParms * | CallParms | I | Structure of run time parameters to use during the HSM unlock 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 * | aRandomNumberIn | I | Up to 8 numeric characters, null terminated or padded with spaces. This parameter holds the random number that is generated and displayed by a Digipass authenticator when it gets locked - the Unlock challenge. | | aat_ascii * | aUnlockCode | O | 7 or 8 numeric characters, which the user will have to enter on the Digipass authenticator to unlock it. | ## COBOL calling convention ```custom Entry point: AA2ULKIC 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-CODE 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-API-NAME PIC X(8) VALUE 'AA2ULKIC'. . . . CALL W-API-NAME USING BY REFERENCE W-BLOB BY REFERENCE W-KERNELPARMS BY REFERENCE W-STORAGEKEY BY REFERENCE W-INITVECTOR BY REFERENCE RANDOM-NBR BY REFERENCE UNLOCK-CODE RETURNING W-RETURN ``` ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 908 | HSM key not found | | 133 | Invalid RandomNumber pointer | 951 | Invalid HSM key type for HSM decryption | | 134 | Invalid UnlockCode pointer | 1000 | Function does not support EMV-CAP | | 138 | Unlock function not supported | 1104 | Virtual token is not a primary token | | 208 | Application disabled | 1116 | Response check digit not allowed | | 209 | Grace period expired | 1117 | Challenge check digit not allowed | | 210 | Allowed use count reached | 1118 | Unsupported BLOB | | 211 | Virtual token not supported | -101 | Random number too small | | 412 | Invalid checksum | -102 | Random number too long | | 413 | Invalid Base64 format | -103 | Random number check digit wrong | | 414 | Invalid checksum (HSM) | -104 | Random number character not decimal | | 510 | Invalid Digipass data pointer | -310 | Invalid reserved parameter | | 900 | Invalid session context handle | -1501 | Memory allocation failed |