Function prototype
aat_int32 AAL2Unlock (TDigipassBlob* DPData,
TKernelParms* CallParms,
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 provide an unlock code thanks to this function.
This function generates an UnlockCode that the user has to enter into the Digipass authenticator in response to the displayed RandomNumber.
The former unlock mechanism uses the same authenticator application BLOB as the Digipass authentication application (RO, CR, SG, or MM).
The new unlock mechanism Unlock V2 (used with compliant Digipass authenticators only) uses a dedicated Unlock V2 application BLOB. If Unlock V2 is supported by the Digipass authenticator, the Unlock V2 application BLOB must be imported like any other authenticator application BLOB (this Unlock V2 application BLOB has authentication mode UL), and must be used when calling the unlock APIs instead of the Digipass authentication BLOB (RO, CR, SG, or MM).
Parameters
Table: Parameters (AAL2Unlock) | 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 * | 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 is locked. |
| aat_ascii * | UnlockCode | O | String of 7 or 8 numeric characters which the user has to enter into the Digipass authenticator to unlock it (recommended buffer size is 9 bytes). |
Return codes
Table: Return codes (AAL2Unlock) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 1000 | Function does not support EMV-CAP |
| 133 | Invalid RandomNumber pointer | 1104 | Virtual token is not a primary token |
| 134 | Invalid UnlockCode pointer | 1116 | Response check digit not allowed |
| 138 | Unlock function not supported | 1117 | Challenge check digit not allowed |
| 208 | Application disabled | 1118 | Unsupported BLOB |
| 209 | Grace period expired | -101 | Random number too small |
| 210 | Allowed use count reached | -102 | Random number too long |
| 211 | Virtual token not supported | -103 | Random number check digit wrong |
| 412 | Invalid checksum | -104 | Random number character not decimal |
| 413 | Invalid Base64 format | -310 | Invalid reserved parameter |
| 510 | Invalid Digipass data pointer | -1501 | Memory allocation failed |