Function prototype
aat_int32 AAL2DPXGetToken(TDPXHandle* dpx_Handle,
TKernelParms* CallParms,
aat_ascii* Select_appl_name,
aat_ascii* Serial_Appli,
aat_ascii* DIGIPASSType,
aat_ascii* AuthMode,
TDigipassBlob* DPData);
Description
This function is used to import a authenticator application BLOB (DPData parameter) describing an instance of one authenticator application and to retrieve other characteristics: its serial number and application name returned in Serial_Appli. The physical Digipass device type is returned in DIGIPASSType, and the authentication mode to be used with this authenticator application is returned in AuthMode.
Among the available applications, only the one indicated in the Select_appl_name argument will be imported. If the dpx_Handle contains more than one Digipass authenticator, AAL2DPXGetToken must be called several times to import all Digipass authenticators.
AAL2DPXGetToken returns 107 when the last Digipass authenticator has been imported.
OneSpan recommends using the new function AAL2DPXGetTokenBLOBsEx2 rather than AAL2DPXGetToken.
Parameters
Table: Parameters (AAL2DPXGetToken) | Type | Name | Use | Description |
|---|
| TDPXHandle * | dpx_Handle | I/O | Pointer to the handle used during the DPX file import operation. This block must be the one initialized by the AAL2DPXInit function.. |
| TKernelParms * | CallParms | I | Structure of runtime parameters to use during this function call. |
| aat_ascii * | Select_appl_name | I | String of up to 12 characters, right-padded with spaces. This parameter holds the application name to use as an import selection filter. It must be one of the application names returned by AAL2DPXInit. |
| aat_ascii * | Serial_Appli | O | String of 22 characters composed of the 10-digit Digipass device serial number concatenated with its 12-digit application name. This represents a logical instance of a Digipass cryptographic application with its unique secrets and parameters. It may be used as a search key to access your Digipass database (recommended buffer size is 23 bytes). |
| aat_ascii * | DIGIPASSType | O | String of 5 characters. Gives the physical Digipass device type. It may be used for information purposes, or to determine which flashing pattern protocol to use for sending data through the device's optical interface, if any. Possible values: - AKII
- AUTCD
- DP100
- DP300
- DP500
- DP600
- DP700
- etc.
(Recommended buffer size is 6 bytes.) |
| aat_ascii * | AuthMode | O | String of 2 characters. Defines the authenticator application authentication mode. Possible modes: - RO: Response-Only
- CR: Challenge/Response
- SG: Signature
- MM: Multi-Mode
- UL: Unlock V2-dedicated application
Signature mode devices may also be used for Challenge/Response authentication if they are programmed to accept a single input data field. (Recommended buffer size is 3 bytes). |
| TDigipassBlob * | DPData | O | authenticator application BLOB. Upon return from the function call, this BLOB must be rewritten to the application database to reflect changes. |
Return codes
Table: Return codes (AAL2DPXGetToken) | Code | Meaning | Code | Meaning |
|---|
| 100 | Success | -1500 | Cannot allocate memory |
| 107 | Success – end of file reached | -1501 | Handle pointer is null |
| -10 | Error null pointer | -1502 | Handle context is pointer null |
| -11 | Error bad argument | -1503 | Handle key is pointer null |
| -12 | Error DPX clear failed | -1504 | Invalid handle context eyecatcher |
| -13 | Error DES calculation | -1505 | Invalid handle key eyecatcher |
| -22 | Error file rewind failed | -1506 | Invalid selected application |
| -23 | Error file not open | -1507 | Selected application pointer is null |
| -24 | Error file not closed | -1508 | InitKey pointer is null |
| -30 | Error fatal error | -1509 | File name pointer is null |
| -31 | Error file has errors | -1510 | Invalid selected application |
| -32 | Error too many errors | -1514 | Serial number pointer is null |
| -33 | Error too much info | -1515 | Digipass type pointer is null |
| -40 | Error void text | -1516 | Authentication mode pointer is null |
| -41 | Error truncated text | -1517 | Digipass data pointer is null |
| -42 | Error no DF records | -1525 | Unlock mixed versions in same DPX |
| -43 | Error unexpected record | -1526 | Invalid unlock challenge length in DPX |
| -44 | Error bad record type | -1527 | Invalid unlock code type in DPX |
| -45 | Error unexpected content | -1528 | Invalid unlock code length in DPX |
| -46 | Error line exhausted | -1530 | EMV HSM DPX not supported |
| -47 | Error missing quotes | -1531 | EMV SSM DPX not supported |
| -48 | Error missing field name | -1543 | Function does not support this DPX |
| -49 | Error bad field name | -1547 | Invalid GM/T 0004-2012 application |
| -50 | Error bad field type | -1548 | Invalid time step for GM/T 0004-2012 algorithm |
| -51 | Error field size | -1549 | Invalid unlock type for AES HSM encryption |
| -52 | Error line size | -1550 | Invalid application key type for AES HSM encryption |
| -100 | Error DH file content | -2000 | Error t300 sernumber |
| -101 | Error DH date content | -2001 | Error t300 fabsecret |
| -102 | Error DH version content | -2002 | Error t300 unl64key |
| -103 | Error DH created by content | -2003 | Error t300 codeword |
| -200 | Error DC HSH content | -2004 | Error t300 des64key |
| -201 | Error DC DEL content | -2005 | Error t300 tdes64key |
| -202 | Error HSH value | -2006 | Error t300 offset |
| -203 | Error DEL value | -2007 | Error t300 ivright |
| -300 | Error DF field name | -2008 | Error t300 ivleft |
| -301 | Error DF descriptor | -2009 | Error t300 root |
| -400 | Error DA record | -2010 | Error t300 today |
| -401 | Error DA field | -2011 | Error t300 tomorrow |
| -500 | Error Digipass field value | -2012 | Error t300 daycut |
| -501 | Error Digipass descriptor | -2020 | Error t500 sernumber |
| -502 | Error Digipass unknown descriptor | -2021 | Error t500 fabsecret |
| -503 | Error Digipass record redefinition | -2022 | Error t500 ipin |
| -504 | Error Digipass record overflow | -2023 | Error t500 codeword |
| -800 | Error CT field type | -2024 | Error t500 des64key |
| -801 | Error CT name redefinition | -2040 | Error t700 sernumber |
| -802 | Error CT field length | -2041 | Error t700 fabsecret |
| -803 | Error CT field name | -2042 | Error t700 unl64key |
| -804 | Error CT too many entries | -2043 | Error t700 codeword |
| -900 | Error DE DEF records content | -2044 | Error t700 des64key |
| -901 | Error DE data records content | -2045 | Error t700 tdes64key |
| -902 | Error DE tokens content | | |