Digipass unlocking

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

AAL2UnlockICSF

Function prototype (aal2sdk.h)

aat_int32 AAL2UnlockICSF (
                      TDigipassBlob*   DPBlob,
                      TKernelParms*    CallParms,
                      aat_ascii*       aStorageKeyNameIn,
                      aat_ascii*       aInitialVectorIn,
                      aat_ascii*       aRandomNumberIn,
                      aat_ascii*       aUnlockCode);

Description

If a user's Digipass authenticator is locked because of wrong PIN entries, the Digipass administrator will be able to unlock the Digipass authenticator using this function. It obtains the initialized unlock information of the user's Digipass authenticator from the authenticator application BLOB and performs the unlock code calculation.

This function generates an unlock code that the user enters in their Digipass authenticator in response to the currently displayed random number.

Parameters

The memory management of the output parameters must be performed by the calling function.

Table: Parameters (AAL2UnlockICSF)
Type	Name	Use	Description
TDigipassBlob *	DPBlob	I/O	authenticator application BLOB.
TKernelParms *	CallParms	I	Structure of run time parameters to use during the HSM unlock 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 HSM storage key used to encrypt the sensitive authenticator applicationBLOB 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 *	aRandomNumberIn	I	Up to 8 numeric characters, null terminated or padded with spaces. This parameter holds the random number that is generated and displayed by a Digipass authenticator when it gets locked - the Unlock challenge.
aat_ascii *	aUnlockCode	O	7 or 8 numeric characters, which the user will have to enter on the Digipass authenticator to unlock it.

COBOL calling convention

Entry point: AA2ULKIC
02   W-BLOB              PIC X(248).
02   W-KERNELPARMS.
     03   W-PARMCOUNT    PIC 9(8) USAGE BINARY.
     03   W-PARM01       PIC 9(8) USAGE BINARY.
     . . .
     03   W-PARM19       PIC 9(8) USAGE BINARY.
02   W-RANDOM-NBR        PIC X(9).
02   W-UNLOCK-CODE       PIC X(9).
02   W-STORAGEKEY        PIC X(65).
02   W-INITVECTOR        PIC X(17).
02   W-RETURN            PIC S9(8) USAGE BINARY.
02   W-API-NAME          PIC X(8) VALUE 'AA2ULKIC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-BLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY REFERENCE RANDOM-NBR
           BY REFERENCE UNLOCK-CODE
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2UnlockICSF)
Code	Meaning	Code	Meaning
0	Success	908	HSM key not found
133	Invalid RandomNumber pointer	951	Invalid HSM key type for HSM decryption
134	Invalid UnlockCode pointer	1000	Function does not support EMV-CAP
138	Unlock function not supported	1104	Virtual token is not a primary token
208	Application disabled	1116	Response check digit not allowed
209	Grace period expired	1117	Challenge check digit not allowed
210	Allowed use count reached	1118	Unsupported BLOB
211	Virtual token not supported	-101	Random number too small
412	Invalid checksum	-102	Random number too long
413	Invalid Base64 format	-103	Random number check digit wrong
414	Invalid checksum (HSM)	-104	Random number character not decimal
510	Invalid Digipass data pointer	-310	Invalid reserved parameter
900	Invalid session context handle	-1501	Memory allocation failed