--- title: "AAL2AuthorizeUnlockICSF" slug: "a3s-cppprg-icsf-zos-aal2authorizeunlockicsf-4-0" updated: 2026-11-11T10:02:33Z published: 2026-11-11T10:02:33Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2authorizeunlockicsf-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. # AAL2AuthorizeUnlockICSF ## Function prototype ```cpp aat_int32 AAL2AuthorizeUnlockICSF( TDigipassBlob* DPData, TKernelParms* CallParms, aat_ascii* aStorageKeyNameIn, aat_ascii* aInitialVectorIn, aat_ascii* aUnlockAuthCode, aat_ascii* RandomNumber, aat_ascii* UnlockCode); ``` ## Description If a user's Digipass authenticator is locked because of wrong PIN entries, the Digipass administrator will be able to unlock this user with this function, which performs the following actions: - Validating the unlock authentication code - If the unlock authentication code is correct, obtaining the initialized unlock information of the user's Digipass authenticator from the authenticator application BLOB and performing the unlock code calculation. This function authenticates the user and generates an unlock code that the user enters into the Digipass authenticator in response to the displayed random number. If a Digipass instance has more than one application and an unlock mechanism not based on Unlock V2, AAL2SyncTokenBLOB should be called to synchronize the unlock authentication counter value stored in the different authenticator application BLOBs after a call to AAL2AuthorizeUnlock. > In case of Unlock V2 support, the Authorize Unlock function must be used with the dedicated Unlock V2 BLOB instead of the Digipass authentication BLOB. The synchronization mentioned above is not applicable in this case. ## 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_ascii * | UnlockAuthCode | I | String of up to 8 numeric characters, null-terminated or padded with spaces. This parameter holds the unlock authentication code that is generated by AAL2GenUnlAuthCode. | | aat_ascii * | RandomNumber | I | String of 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. | | aat_ascii * | UnlockCode | O | String of 7 or 8 numeric characters which the user needs to enter into the Digipass authenticator to unlock it. | ## COBOL calling convention ```custom Entry point: AA2AUKIC 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-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 'AA2AUKIC'. . . . CALL W-API-NAME USING BY REFERENCE W-BLOB BY REFERENCE W-KERNELPARMS BY REFERENCE W-STORAGEKEY BY REFERENCE W-INITVECTOR BY REFERENCE W-UNLOCK-AUTHCODE BY REFERENCE W-RANDOM-NBR BY REFERENCE W-UNLOCK-CODE RETURNING W-RETURN. ``` ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 813 | Unlock authentication code is too short | | 133 | Invalid RandomNumber pointer | 814 | Unlock authentication code is too long | | 134 | Invalid UnlockCode pointer | 900 | Invalid session context handle | | 138 | Unlock function not supported | 908 | HSM key not found | | 208 | Application disabled | 951 | Invalid HSM key type for HSM decryption | | 209 | Grace period expired | 1000 | Function does not support EMV-CAP | | 210 | Allowed use count reached | 1104 | Virtual token is not a primary token | | 211 | Virtual token not supported | 1118 | Unsupported BLOB | | 412 | Invalid checksum (software) | -101 | Random number too small | | 413 | Invalid Base64 format | -102 | Random number too long | | 414 | Invalid checksum (HSM) | -103 | Random number check digit wrong | | 510 | Invalid Digipass data pointer | -104 | Random number character not decimal | | 810 | Unlock authentication code validation failed | -310 | Invalid reserved parameter | | 811 | Invalid unlock authentication code pointer | -1501 | Memory allocation failed |