Function prototype
aat_int32 AAL2DPXGetTokenBlobsEx(
TDPXHandle* dpx_Handle
TKernelParms* CallParms,
aat_int16* Appl_count,
aat_ascii Serial_Appli[8][23],
aat_ascii TokenType[6],
aat_ascii AuthMode[8][3],
TDigipassBlob DPData[8],
aat_int32* SeqNumThreshold,
aat_ascii* ActivationVector,
aat_int32* ActivationVectorLen);
Description
This function is used to import all the application BLOBs of one Digipass authenticator in a single call (each application BLOB is stored in the DPData array parameter).
The name of each application is concatenated with the Digipass serial number and returned in the Serial_Appli array. In the same way, the authentication mode to use for each authenticator application is returned in the AuthMode array. The physical Digipass device type is returned in TokenType.
The number of authenticator application BLOBs requested/returned is described in the application count. If the dpx_Handle contains more than one Digipass authenticator, AAL2DPXGetTokenBlobsEx must be called several times to import all Digipass authenticators.
This function replaces the former function AAL2DPXGetTokenBlobs to support DPX files containing master activation licenses (in the context of multi-device licensing) but also supports traditional DPX files containing Digipass applications (in the context of single-device licensing). For more information on the licensing model, refer to the Authentication Suite Server SDK Product Guide.
In case of DPX files containing master activation licenses (in the context of multi-device licensing), the function AAL2DPXGetTokenBlobsEx will allow importing a master activation application BLOB, the associated activation vector and the associated sequence number threshold from a DPX file:
- The master activation application BLOB and the associated activation vector are involved in the activation process of the Digipass instance related to a particular license of the imported DPX file.
- The activation vector holds some parameters for the Activation Message 1 that will be generated afterwards by Authentication Suite Server SDK for a particular license.
- The sequence number threshold is a number from 1 to 99, indicating the number of instances which can be activated from the license; configured by OneSpan at the time of order.
The function AAL2DPXGetTokenBlobsEx must be called several times to import all Digipass authenticators from a DPX file, once for each serial number.
AAL2DPXGetTokenBlobsEx returns 107 when the last Digipass authenticator has been imported.
After importing all Digipass authenticators from a DPX file the function AAL2DPXClose must be called.
OneSpan recommends using the new function AAL2DPXGetTokenBlobsEx2 rather than AAL2DPXGetTokenBlobsEx.
Parameters
Table: Parameters (AAL2DPXGetTokenBlobsEx) | 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_int16 * | Appl_count | O | Points to a short integer where the function returns the number of Digipass applications found for the Digipass authenticator. |
| aat_ascii [8][23] | Serial_Appli | O | Set of up to eight 22 + 1 character strings, null-terminated, each composed of the 10-digit Digipass device serial number concatenated with its 12-digit application name. Each array entry represents the logical instance of a Digipass cryptographic application with its unique secrets and parameters. |
| aat_ascii [6] | TokenType | O | String of 5 +1 characters, null-terminated. Gives the physical Digipass device type. It may be used for information purposes or to determine which flashing pattern protocol to use to send data through the device's optical interface, if any. Possible values: - AKII
- AUTCD
- DP100
- DP300
- DP500
- DP600
- DP700
- etc.
|
| aat_ascii [8][3] | AuthMode | O | Set of up to eight 2+1 character strings, null-terminated. Defines each returned authenticator application authentication mode. RO:Response-Only CR: Challenge/Response SG: Signature MM: Multi-Mode UL: Unlock V2 dedicated application MA: Master Activation Application Signature mode devices may also be used for Challenge/Response authentication if they are programmed to accept a single input data field. |
| TDigipassBlob [8] | DPData | O | Up to 8 authenticator application BLOBs. Upon return from the function call, these BLOBs must be written to the application database. |
| aat_int32 * | SeqNumThreshold | O | Pointer on an integer value containing when the function returns, the sequence number threshold of the master activation application (from 1 to 99). Returned value is 0 when the Digipass authenticator does not contain a master activation application MA. |
| aat_ascii * | ActivationVector | O | 76+1 output string containing the activation vector corresponding to the master activation application returned. It will return an empty string if the Digipass authenticator does not contain a master activation application MA. |
| aat_int32 * | ActivationVectorLen | I/O | In input, this parameter must indicate the size of the allocated buffer for the activation vector parameter (recommended 77 bytes). In output, this parameter indicates the length of the activation vector string (without the null-terminated character). |
Return codes
Table: Return Codes (AAL2DPXGetTokenBlobsEx) | Code | Meaning | Code | Meaning |
|---|
| 100 | Success | -1503 | Handle key is pointer null |
| 107 | Success – end of file reached | -1504 | Invalid handle context eyecatcher |
| -10 | Error null pointer | -1505 | Invalid handle key eyecatcher |
| -11 | Error bad argument | -1506 | Invalid selected application |
| -12 | Error DPX clear failed | -1507 | Selected application pointer is null |
| -13 | Error DES calculation | -1508 | InitKey pointer is null |
| -22 | Error file rewind failed | -1509 | File name pointer is null |
| -23 | Error file not open | -1510 | Invalid selected application |
| -24 | Error file not closed | -1514 | Serial number pointer is null |
| -30 | Error fatal error | -1515 | Digipass type pointer is null |
| -31 | Error file has errors | -1516 | Authentication mode pointer is null |
| -32 | Error too many errors | -1517 | Digipass data pointer is null |
| -33 | Error too much info | -1525 | Unlock mixed versions in same DPX |
| -40 | Error void text | -1526 | Invalid unlock challenge length in DPX |
| -41 | Error truncated text | -1527 | Invalid unlock code type in DPX |
| -42 | Error no DF records | -1528 | Invalid unlock code length in DPX |
| -43 | Error unexpected record | -1530 | EMV HSM DPX not supported |
| -44 | Error bad record type | -1531 | EMV SSM DPX not supported |
| -45 | Error unexpected content | -1537 | Invalid master activation application |
| -46 | Error line exhausted | -1538 | Sequence number threshold pointer is null |
| -47 | Error missing quotes | -1539 | Activation vector pointer is null |
| -48 | Error missing field name | -1540 | Activation vector length pointer is null |
| -49 | Error bad field name | -1541 | Invalid activation vector buffer length |
| -50 | Error bad field type | -1542 | Invalid master application number |
| -51 | Error field size | -1543 | Function does not support this DPX |
| -52 | Error line size | -1547 | Invalid GM/T 0004-2012 application |
| -100 | Error DH file content | -1548 | Invalid time step for GM/T 0004-2012 algorithm |
| -101 | Error DH date content | -1549 | Invalid unlock type for AES HSM encryption |
| -102 | Error DH version content | -1550 | Invalid application key type for AES HSM encryption |
| -103 | Error DH created by content | -2000 | Error t300 sernumber |
| -200 | Error DC HSH content | -2001 | Error t300 fabsecret |
| -201 | Error DC DEL content | -2002 | Error t300 unl64key |
| -202 | Error HSH value | -2003 | Error t300 codeword |
| -203 | Error DEL value | -2004 | Error t300 des64key |
| -300 | Error DF field name | -2005 | Error t300 tdes64key |
| -301 | Error DF descriptor | -2006 | Error t300 offset |
| -400 | Error DA record | -2007 | Error t300 ivright |
| -401 | Error DA field | -2008 | Error t300 ivleft |
| -500 | Error Digipass field value | -2009 | Error t300 root |
| -501 | Error Digipass descriptor | -2010 | Error t300 today |
| -502 | Error Digipass unknown descriptor | -2011 | Error t300 tomorrow |
| -503 | Error Digipass record redefinition | -2012 | Error t300 daycut |
| -504 | Error Digipass record overflow | -2020 | Error t500 sernumber |
| -800 | Error CT field type | -2021 | Error t500 fabsecret |
| -801 | Error CT name redefinition | -2022 | Error t500 ipin |
| -802 | Error CT field length | -2023 | Error t500 codeword |
| -803 | Error CT field name | -2024 | Error t500 des64key |
| -804 | Error CT too many entries | -2040 | Error t700 sernumber |
| -900 | Error DE DEF records content | -2041 | Error t700 fabsecret |
| -901 | Error DE data records content | -2042 | Error t700 unl64key |
| -902 | Error DE tokens content | -2043 | Error t700 codeword |
| -1500 | Cannot allocate memory | -2044 | Error t700 des64key |
| -1501 | Handle pointer is null | -2045 | Error t700 tdes64key |
| -1502 | Handle context is pointer null | | |