Function prototype
aat_int32 AAL2AuthorizeUnlock (
TDigipassBlob* DPData,
TKernelParms* CallParms,
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
Table: Parameters (AAL2AuthorizeUnlock) | 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 * | 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 (recommended buffer size is 9 bytes). |
Return codes
Table: Return codes (AAL2AuthorizeUnlock) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 811 | Invalid unlock authentication code pointer |
| 133 | Invalid RandomNumber pointer | 813 | Unlock authentication code is too short |
| 134 | Invalid UnlockCode pointer | 814 | Unlock authentication code is too long |
| 138 | Unlock function not supported | 1000 | Function does not support EMV-CAP |
| 208 | Application disabled | 1104 | Virtual token is not a primary token |
| 209 | Grace period expired | 1118 | Unsupported BLOBBLOB |
| 210 | Allowed use count reached | -101 | Random number too small |
| 211 | Virtual token not supported | -102 | Random number too long |
| 412 | Invalid checksum | -103 | Random number check digit wrong |
| 413 | Invalid Base64 format | -104 | Random number character not decimal |
| 510 | Invalid Digipass data pointer | -310 | Invalid reserved parameter |
| 810 | Unlock authentication code validation failed | -1501 | Memory allocation failed |