Function prototype (aal2sdk.h)
aat_int32 AAL2DPXInitHSM(
TDPXHandle* dpx_Handle,
aat_ascii* pFileName,
aat_ascii* TransportKey,
aat_int16* appl_count,
aat_ascii* appl_names,
aat_int16* token_count,
aat_ascii* HSMTransportKeyNames,
aat_ascii* HSMTransportKeyKCV);
Description
This function is used to initialize the import process of a DPX file when the optional DPX double encryption is used.
It opens the DPX file pointed to by pFileName, verifies the given software transport key, initalizes the handle pointed by dpx_Handle, and returns the number of applications contained in the DPX file, the list of these application names in appl_names, the total number of defined Digipass authenticators in token_count and the HSM transport key name and KCV used to perform the DPX double encryption. The HSM transport key name and KCV are expected by the AAL2MigrateBlobICSFEx to perform the encryption migration from the HSM transport key to the HSM storage key.
Parameters
The memory management of the output parameters must be performed by the calling function.
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 the AAL2DPXGetTokenBlobsEx2 and AAL2DPXClose functions. |
| aat_ascii * | pFileName | I | Path to the DPX file to open. |
| aat_ascii * | TransportKey | I | A string of 32 or 64 hexadecimal digits. This is the DPX software transport 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 * | HSMTransportKey Name | O | Points to a 64 + 1 bytes area where the function returns the HSM transport key name used to encrypt the DPX file. |
| aat_ascii * | HSMTransportKey KCV | O | Points to a 6 + 1 bytes area where the function returns the HSM transport key KCV that has been used to encrypt the DPX file. |
COBOL calling convention
Entry point: AA2VINCH
02 W-DPX-HANDLE.
03 W-POINTER1 PIC 9(8) USAGE BINARY.
03 W-POINTER2 PIC 9(8) USAGE BINARY.
02 W-RETURN PIC S9(8) USAGE BINARY.
02 W-FILENAME PIC X(20)
VALUE 'DD:DPXFILE'.
02 W-TRANSPORT-KEY PIC X(32)..
02 W-APPL-NAMES PIC X(12) OCCURS 8.
02 W-APPL-COUNT PIC 9(4) USAGE BINARY.
02 W-TOKEN-COUNT PIC 9(8) USAGE BINARY.
02 W-HSMTRANSPORT-KEY PIC X(65).
02 W-HSMTRANSPORT-KEYKCV PIC X(7).
02 W-API-NAME PIC X(8) VALUE 'AA2VINCH'.
. . .
CALL W-API-NAME USING
BY REFERENCE W-DPX-HANDLE
BY REFERENCE W-FILENAME
BY REFERENCE W-TRANSPORT-KEY
BY REFERENCE W-APPL-COUNT
BY REFERENCE W-APPL-NAMES
BY REFERENCE W-TOKEN-COUNT
BY REFERENCE W-HSMTRANSPORT-KEY
BY REFERENCE W-HSMTRANSPORT-KEYKCV
RETURNING W-RETURN
Return codes
Table: Return codes (AAL2DPXInitHSM) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | -102 | Error DH version content |
| -10 | Error null pointer | -103 | Error DH created by content |
| -11 | Error bad argument | -200 | Error DC HSH content |
| -12 | Error DPX clear failed | -201 | Error DC DEL content |
| -13 | Error DES calculation | -202 | Error HSH value |
| -14 | Error TransportKey length | -203 | Error DEL value |
| -15 | Error TransportKey value | -300 | Error DF field name |
| -20 | Error file open failed | -500 | Error Digipass field value |
| -21 | Error file close failed | -501 | Error Digipass descriptor |
| -22 | Error file rewind failed | -502 | Error Digipass unknown descriptor |
| -23 | Error file not open | -503 | Error Digipass record redefinition |
| -24 | Error file not closed | -504 | Error Digipass record overflow |
| -30 | Error fatal error | -800 | Error CT field type |
| -31 | Error file has errors | -801 | Error CT name redefinition |
| -32 | Error too many errors | -802 | Error CT field length |
| -33 | Error too much info | -803 | Error CT field name |
| -40 | Error void text | -804 | Error CT too many entries |
| -41 | Error truncated text | -900 | Error DE DEF records content |
| -42 | Error no DF records | -901 | Error DE data records content |
| -43 | Error unexpected record | -902 | Error DE tokens content |
| -44 | Error bad record type | -1500 | Cannot allocate memory |
| -45 | Error unexpected content | -1501 | Handle pointer is null |
| -46 | Error line exhausted | -1502 | Handle context is pointer null |
| -47 | Error missing quotes | -1503 | Handle key is pointer null |
| -48 | Error missing field name | -1504 | Invalid handle context eyecatcher |
| -49 | Error bad field name | -1505 | Invalid handle key eyecatcher |
| -50 | Error bad field type | -1506 | Invalid selected application |
| -51 | Error field size | -1507 | Selected application pointer is null |
| -52 | Error line size | -1508 | InitKey pointer is null |
| -100 | Error DH file content | -1509 | File name pointer is null |
| -101 | Error DH date content | -1510 | Invalid selected application |