This article describes the function(s) on which the Digipass data import functionality is based. It contains information about parameters and possible return codes, as well as a prototype for each function.
AAL2DPXInitHSM
Function prototype
aat_int32 AAL2DPXInitHSM( TDPXHandle *dpx_Handle,
aat_ascii *pFileName,
aat_ascii *InitKey,
aat_int16 *appl_count,
aat_ascii *appl_names,
aat_int32 *token_count,
aat_ascii *aTransportKeyName
aat_ascii *aTransportKeyKCV);
Description
This function is used to initialize the import process of a DIGIPASS export file (DPX) file, which involves the following steps:
- Opening the DPX file, using its name (pFileName)
- Verifying the key (InitKey)
- Initializing the handle dpx_Handle
- Returning the number of applications defined in the DPX file into appl_count, the list of application names into appl_names, and the total number of defined Digipass authenticators into token_count.
- If the DPX file is double-encrypted, also returning the HSM transport key name and the KCV of the HSM transport key double-encrypt the DPX file.
Parameters
Table: Parameters (AAL2DPXInitHSM) | Type | Name | Use | Description |
|---|
| TDPXHandle * | dpx_Handle | I/O | Handle pointer used during the DPX file import operation. This block must be acquired by the calling application, and will be initialized by this function. It must be passed to other functions working on the DPX file such as AAL2DPXGetToken or AAL2DPXClose. |
| aat_ascii * | pFileName | I | Path to the DPX file to open. Only characters of the 7-bit ASCII printable character set are supported. |
| aat_ascii * | InitKey | I | A string of 32 or 64 hexadecimal digits representing the DPX file encryption key. |
| aat_int16 * | appl_count | O | Points to a short integer where the function returns the number of applications described in the DPX file. The application names are listed in the appl_names parameter. |
| aat_ascii * | appl_names | O | Points to a 96 + 1-byte area where the function returns the list of available application names. Each application name has a fixed length of 12 characters, left-aligned and padded with spaces, if necessary. The list contains a maximum of 8 application names (recommended buffer size is 97 bytes). |
| aat_int16 * | token_count | O | Points to a short integer where the function returns the number of Digipass authenticators contained in this DPX file. |
| aat_ascii * | aTransportKeyName | O | Name of the HSM-level transport key used to double-encrypt the DPX file. Empty in case of single-encrypted DPX files (recommended buffer size is 129 bytes). |
| aat_ascii * | aTransportKeyKCV | O | KCV of the HSM-level transport key used to double-encrypt the DPX file. Empty in case of single-encrypted DPX files (recommended buffer size is 7 bytes). |
Return codes
Table: Return codes (AAL2DPXInitHSM) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | -301 | Error DF descriptor |
| -10 | Error null pointer | -400 | Error DA record |
| -11 | Error bad argument | -401 | Error DA field |
| -12 | Error DPX clear failed | -500 | Error Digipass field value |
| -13 | Error DES calculation | -501 | Error Digipass descriptor |
| -14 | Error InitKey length | -502 | Error Digipass unknown descriptor |
| -15 | Error InitKey value | -503 | Error Digipass record redefinition |
| -20 | Error file open failed | -504 | Error Digipass record overflow |
| -21 | Error file close failed | -800 | Error CT field type |
| -22 | Error file rewind failed | -801 | Error CT name redefinition |
| -23 | Error file not open | -802 | Error CT field length |
| -24 | Error file not closed | -803 | Error CT field name |
| -30 | Error fatal error | -804 | Error CT too many entries |
| -31 | Error file has errors | -900 | Error DE DEF records content |
| -32 | Error too many errors | -901 | Error DE data records content |
| -33 | Error too much info | -902 | Error DE tokens content |
| -40 | Error void text | -1500 | Cannot allocate memory |
| -41 | Error truncated text | -1501 | Handle pointer is null |
| -42 | Error no DF records | -1502 | Handle context is pointer null |
| -43 | Error unexpected record | -1503 | Handle key is pointer null |
| -44 | Error bad record type | -1504 | Invalid handle context eyecatcher |
| -45 | Error unexpected content | -1505 | Invalid handle key eyecatcher |
| -46 | Error line exhausted | -1506 | Invalid selected application |
| -47 | Error missing quotes | -1507 | Selected application pointer is null |
| -48 | Error missing field name | -1508 | InitKey pointer is null |
| -49 | Error bad field name | -1509 | File name pointer is null |
| -50 | Error bad field type | -1510 | Invalid selected application |
| -51 | Error field size | -1511 | Application count pointer is null |
| -52 | Error line size | -1512 | Application name pointer is null |
| -100 | Error DH file content | -1513 | Token count pointer is null |
| -101 | Error DH date content | -1514 | Serial number pointer is null |
| -102 | Error DH version content | -1515 | Digipass type pointer is null |
| -103 | Error DH created by content | -1516 | Authentication mode pointer is null |
| -200 | Error DC HSH content | -1517 | Digipass data pointer is null |
| -201 | Error DC DEL content | -1518 | Key name pointer is null |
| -202 | Error HSH value | -1519 | Key KCV pointer is null |
| -203 | Error DEL value | -1533 | Invalid response or host code length in DPX |
| -300 | Error DF field name | | |