Device code validation

This article describes the function(s) on which the device code validation functionality is based. It contains information about parameters and possible return codes, as well as a prototype for each function.

The device code validation functionality is only applicable to hardware or software Digipass authenticators compliant with the multi-device two-step activation (in the context of multi-device licensing). For more information, refer to the Authentication Suite Server SDK Product Guide.

AAL2VerifyDeviceCodeICSF

Function prototype

aat_int32 AAL2VerifyDeviceCodeICSF (
                                TDigipassBlob    *DPMAData,
                                TKernelParms     *CallParms,
                                aat_ascii        *aStorageKeyNameIn,
                                aat_ascii        *aInitialVectorIn,
                                aat_ascii        *Challenge,
                                aat_ascii        *DeviceCode,
                                aat_ascii        *DeviceID,
                                aat_int32        *DeviceIDLength,
                                aat_int32        *pDeviceType);

Description

This function verifies the device code provided by the Digipass device using the master activation application data. It also extracts in case of SUCCESS:

Digipass device ID
Digipass device type

It is only applicable to hardware or software Digipass authenticators compliant with the multi-device two-step activation (in the context of multi-device licensing). For more information, refer to the Authentication Suite Server SDK Product Guide.

If a challenge has been used to generate the Activation Message 1 (AALGenMessageActivation1) received by the Digipass device, the same challenge is necessary to validate the device code.

Score-based Digipass

For Digipass devices that integrate the score-based algorithm, Authentication Suite Server SDK performs a score-based authentication to validate the device code. This allows retrieving the Digipass scoring value. Once Authentication Suite Server SDK has successfully validated the device code, it returns either SUCCESS or SUCCESS with the relevant scoring warning code.. See the list of return codes in Table: Return codes (AAL2VerifyDeviceCodeICSF) for more details.

Parameters

Table: Parameters (AAL2VerifyDeviceCodeICSF)
Type	Name	Use	Description
TDigipassBlob	DPMAData	I/O	Digipass master activation application BLOB of the Digipass serial number license that will be used for the activation. Upon return from the function call, this BLOB must be rewritten to the application database to reflect changes.
TKernelParms *	CallParms	I	Structure of runtime parameters to use during this function call.
aat_ascii *	aStorageKeyNameIn	I	String of up to 64+1 characters, left-justified, null-terminated, or right-padded with spaces. This is the label of the ICSF storage key used to encrypt the sensitive Digipass application BLOB data.
aat_ascii *	aInitialVectorIn	I	String of 16 or 32 hexadecimal characters, left-justified, null-terminated. This is the initial vector used to encrypt the sensitive authenticator application BLOB data.
aat_ascii *	Challenge	I	Optional string of 16 numeric or hexadecimal characters, left-justified, null-terminated, or right-padded with spaces. This parameter must hold the challenge that was used initially to generate Activation Message 1. If no challenge was used to generate Activation Message 1, this parameter must be NULL.
aat_ascii *	DeviceCode	I	String of up to 26+1 characters, null-terminated. It contains the device code generated by the Digipass device.
aat_ascii *	DeviceID	O	Output string of 8+1 hexadecimal characters, null-terminated. If the device code has been successfully verified, this parameter contains the value of the Digipass device ID.
aat_int32 *	DeviceIDLength	I/O	In input, this parameter must indicate the size of the allocated buffer for the DeviceID parameter (recommended 9 bytes). In output, this parameter indicates the length of the DeviceID string (without the null-terminated character).
aat_int32 *	pDeviceType	O	In output, this parameter contains the Digipass device type if the device code has been successfully verified (from 0 to 31).

COBOL calling convention

Entry point: AA2VDCIC
02   W-MA-BLOB             PIC X(248).
02   W-KERNELPARMS.
     03  W-PARMCOUNT      PIC 9(8) USAGE BINARY.
     03   W-PARM0         PIC 9(8) USAGE BINARY.
     . . .
     03  W-PARM19         PIC 9(8) USAGE BINARY.
02   W-CHALLENGE          PIC X(17).
02   W-DEVICE-CODE        PIC X(27).
02   W-DEVICE-ID          PIC X(9).
02   W-DEVICE-ID-LENGTH   PIC 9(8) USAGE BINARY VALUE 9.
02   W-DEVICE-TYPE        PIC S9(8) USAGE BINARY.
02   W-RETURN             PIC S9(8) USAGE BINARY.
02   W-STORAGEKEY         PIC X(65).
02   W-INITVECTOR         PIC X(17).
02   W-API-NAME            PIC X(8) VALUE 'AA2VDCIC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-MA-BLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY REFERENCE W-CHALLENGE
           BY REFERENCE W-DEVICE-CODE
           BY REFERENCE W-DEVICE-ID
           BY REFERENCE W-DEVICE-ID-LENGTH
           BY REFERENCE W-DEVICE-TYPE
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2VerifyDeviceCodeICSF)
Code	Meaning	Code	Meaning
0	Success	1040	Invalid host code length with DP algorithm
10001	Success with context warning[1]	1103	Unlock Version 2 not supported
10002	Success with user warning[1]	1116	Response check digit not allowed
10003	Success with user & context warning[1]	1117	Challenge check digit not allowed
10004	Success with platform warning[1]	1118	Unsupported BLOB
10005	Success with platform & context warning[1]	1263	Device ID buffer too small
10006	Success with platform & user warning[1]	1264	Invalid master application
10007	Success with platform & user & context warning[1]	1265	Invalid master application data pointer
1	Code not verified	1276	Invalid device code pointer
130	Invalid response pointer	1277	Invalid device ID pointer
140	Challenge corrupted	1278	Invalid device ID length pointer
201	Code replay attempt	1280	Invalid device type pointer
202	Identification error threshold reached	1281	Invalid device code length
205	Inactive days reached	1282	Invalid device code check digit
208	Application disabled	1283	Invalid device code character
412	Invalid checksum (software)	1284	Invalid device code
413	Invalid Base64 format	1285	Master key derivation failed
414	Invalid checksum (HSM)	-102	Challenge too long
600	Invalid Gordian root information	-103	Challenge check digit wrong
601	Invalid Gordian today information	-105	Challenge minimum length not allowed
602	Invalid Gordian tomorrow information	-106	Challenge maximum length not allowed
603	Invalid Gordian stimulus information	-107	Challenge number wrong
900	Invalid session context handle	-108	Challenge character invalid
908	HSM key not found	-201	Response length out of bounds
951	Invalid HSM key type for HSM decryption	-205	Response character not decimal
1000	Function does not support EMV-CAP	-206	Response character not hexadecimal
1025	Buffer too small	-207	Response character set not specified
1039	Invalid response length with DP algorithm

Specific score-based authentication code (see Score-based DIGIPASS)