Function prototype
aat_int32 AAL2DPXGetTokenBlobsEx2(
TDPXHandle* dpx_Handle
TKernelParms* CallParms,
aat_ascii Serial[11],
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,
aat_ascii* PKBlob,
aat_int32* PKBlobLen);
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, AAL2DPXGetTokenBlobssEx2 must be called several times to import all Digipass authenticators.
This function replaces and extends the former function AAL2DPXGetTokenBlobsEx to support traditional single-device licensing DPX files containing for each Digipass authenticator a payload key in addition to some traditional Digipass applications. For more information, refer to the Authentication Suite Server SDK Product Guide.
The usage of the former functions AAL2DPXGetToken, AAL2DPXGetTokenBlobs, and AAL2DPXGetTokenBlobsEx is no longer recommended.
In case of DPX files containing master activation licenses (in the context of multi-device licensing), the function AAL2DPXGetTokenBlobsEx2 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 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. This is configured by OneSpan at the time of order.
The function AAL2DPXGetTokenBlobsEx2 must be called several times to import all Digipass authenticators from a DPX file, one time for each serial number.
In case of DPX containing payload key, each call of AAL2DPXGetTokenBlobsEx2 will return one payload key BLOB for each Digipass authenticator.
If the Digipass authenticator uses the Secure Channel feature but the DPX does not contain payload key (case of Digipass post-provisioned), the function call to AAL2DPXGetTokenBlobsEx2 will not return any payload key BLOB. The payload key BLOBs must be generated in this case using AAL2GenPayloadKeyBlob function.
No payload key BLOB will be imported or must be generated if the Digipass authenticator does not support the Secure Channel feature.
AAL2DPXGetTokenBlobsEx2 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.
Parameters
Table: Parameters (AAL2DPXGetTokenBlobsEx2) | 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 [11] | Serial | O | String of 10 + 1 character strings, null-terminated. Gives the Digipass device serial number. |
| 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). |
| aat_ascii * | PKBlob | O | A string of 88+1 characters, null-terminated. It contains the generated payload key BLOB for a Digipass serial number license. Upon return from the function call, this BLOB must be rewritten to the application database to reflect changes. |
| aat_int32 * | PKBlobLen | I/O | In input, this parameter must indicate the size of the allocated buffer for the PKBlob parameter (recommended 89 bytes). In output, this parameter indicates the length of the PKBlob string (without the null-terminated character). |
Return codes
Table: Return Codes (AAL2DPXGetTokenBlobsEx2) | Code | Meaning | Code | Meaning |
|---|
| 100 | Success | -1504 | Invalid handle context eyecatcher |
| 107 | Success – end of file reached | -1505 | Invalid handle key eyecatcher |
| -10 | Error null pointer | -1506 | Invalid selected application |
| -11 | Error bad argument | -1507 | Selected application pointer is null |
| -12 | Error DPX clear failed | -1508 | InitKey pointer is null |
| -13 | Error DES calculation | -1509 | File name pointer is null |
| -22 | Error file rewind failed | -1510 | Invalid selected application |
| -23 | Error file not open | -1514 | Serial number pointer is null |
| -24 | Error file not closed | -1515 | Digipass type pointer is null |
| -30 | Error fatal error | -1516 | Authentication mode pointer is null |
| -31 | Error file has errors | -1517 | Digipass data pointer is null |
| -32 | Error too many errors | -1525 | Unlock mixed versions in same DPX |
| -33 | Error too much info | -1526 | Invalid unlock challenge length in DPX |
| -40 | Error void text | -1527 | Invalid unlock code type in DPX |
| -41 | Error truncated text | -1528 | Invalid unlock code length in DPX |
| -42 | Error no DF records | -1530 | EMV HSM DPX not supported |
| -43 | Error unexpected record | -1531 | EMV SSM DPX not supported |
| -44 | Error bad record type | -1537 | Invalid master activation application |
| -45 | Error unexpected content | -1538 | Sequence number threshold pointer is null |
| -46 | Error line exhausted | -1539 | Activation vector pointer is null |
| -47 | Error missing quotes | -1540 | Activation vector length pointer is null |
| -48 | Error missing field name | -1541 | Invalid activation vector buffer length |
| -49 | Error bad field name | -1542 | Invalid master application number |
| -50 | Error bad field type | -1544 | Payload key BLOB pointer is null |
| -51 | Error field size | -1545 | Paylod key BLOB length pointer is null |
| -52 | Error line size | -1546 | Paylod key BLOB buffer length is not valid |
| -100 | Error DH file content | -1547 | Invalid GM/T 0004-2012 application |
| -101 | Error DH date content | -1548 | Invalid time step for GM/T 0004-2012 algorithm |
| -102 | Error DH version content | -1549 | Invalid unlock type for AES HSM encryption |
| -103 | Error DH created by content | -1550 | Invalid application key type for AES HSM encryption |
| -200 | Error DC HSH content | -2000 | Error t300 sernumber |
| -201 | Error DC DEL content | -2001 | Error t300 fabsecret |
| -202 | Error HSH value | -2002 | Error t300 unl64key |
| -203 | Error DEL value | -2003 | Error t300 codeword |
| -300 | Error DF field name | -2004 | Error t300 des64key |
| -301 | Error DF descriptor | -2005 | Error t300 tdes64key |
| -400 | Error DA record | -2006 | Error t300 offset |
| -401 | Error DA field | -2007 | Error t300 ivright |
| -500 | Error Digipass field value | -2008 | Error t300 ivleft |
| -501 | Error Digipass descriptor | -2009 | Error t300 root |
| -502 | Error Digipass unknown descriptor | -2010 | Error t300 today |
| -503 | Error Digipass record redefinition | -2011 | Error t300 tomorrow |
| -504 | Error Digipass record overflow | -2012 | Error t300 daycut |
| -800 | Error CT field type | -2020 | Error t500 sernumber |
| -801 | Error CT name redefinition | -2021 | Error t500 fabsecret |
| -802 | Error CT field length | -2022 | Error t500 ipin |
| -803 | Error CT field name | -2023 | Error t500 codeword |
| -804 | Error CT too many entries | -2024 | Error t500 des64key |
| -900 | Error DE DEF records content | -2040 | Error t700 sernumber |
| -901 | Error DE data records content | -2041 | Error t700 fabsecret |
| -902 | Error DE tokens content | -2042 | Error t700 unl64key |
| -1500 | Cannot allocate memory | -2043 | Error t700 codeword |
| -1501 | Handle pointer is null | -2044 | Error t700 des64key |
| -1502 | Handle context is pointer null | -2045 | Error t700 tdes64key |
| -1503 | Handle key is pointer null | | |