AAL2VerifyWin

Function prototype

aat_int32 AAL2VerifyWin (TDigipassBlob*     DPData,
                         TKernelParms*      CallParms,
                         aat_ascii*         Challenge,
                         TAuthParms*        WinParms);

Description

This function authenticates a Digipass owner by verifying whether an authentication response based on a standard protocol and a given Digipass dynamic password is valid for a specified authenticator application described by its authenticator application BLOB. Optionally, a previously generated challenge is also passed to this function.

AAL2VerifyWIN can be used for controlling LANMAN, NTLMv1, NTLMv2, CHAP, and MSCHAPv2 authentication responses, which are part of a LANMAN, NTLM (v1 or v2), CHAP, and MSCHAP (v1 or v2) authentication message.

In input, the TAuthParms structure may contain the response, the challenges, and user fields required to perform the validation. In output, the structure can contain the given dynamic password and its NT or LM hash. For MSCHAPv2 response validation, it can also contain the MSCHAPv2 authenticator response allowing the back-authentication of the server.

Virtual Mobile Authenticator

If Virtual Mobile Authenticator is supported for the given authenticator application BLOB, this function can be used to validate protocol-dependent authentication responses based on Virtual DIGIPASS one-time passwords.

If both backup authenticator and primary authenticator are activated, Authentication Suite Server SDK will automatically detect whether the given dynamic password is from the backup or primary Digipass authenticator.

Parameters

Table: Parameters (AAL2VerifyWin)
Type	Name	Use	Description
TDigipassBlob *	DPData	I/O	authenticator application BLOB. 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 *	Challenge	I	String of up to 17 numeric characters, left-justified, null-terminated or right-padded with spaces. This parameter holds the challenge that was proposed to the user to generate the Digipass dynamic password. This challenge can be generated by AAL2GenerateChallenge. If no challenge was generated, this parameter should be NULL.
TAuthParms *	WinParms	I/O	Structure of authentication parameters containing protocol-dependent challenges and responses. Upon return from the function call, this parameter may contain authenticator responses allowing the back-authentication of the server.

The TAuthParms structure contains the following information:

Table: Authentication parameters
Name	Description
Challenges	Number of TData structures containing authentication challenges.
Challenge	One or more TData structures containing the type, the value, and the length of the challenge.
Responses	Number of TData structures containing authentication responses (should be one).
Response	TData structure containing the type, the value, and the length of the response.
Hashes	Number of TData structure set for receiving hash return values.
Hash	Optional TData structures containing allocated space and length for receiving hash or authenticator response return values.

Table: Challenge types
Name	Value	Size	Description
LANMAN	1	8 bytes	Challenge used for LANMAN response validation.
NTLM	2	8 bytes	Challenge used for NTLMv1 response validation.
NTLM2	4	8 bytes	Challenge used for NTLMv2 response validation.
NTLM2USER	8	Up to 512 bytes	User name used for NTLMv2 response validation.
NTLM2DOMAIN	16	Up to 512 bytes	Domain name used for NTLMv2 response validation.
CHAP	128	Up to 255 bytes	Challenge used for CHAP response validation.
MSCHAP2	256	Up to 255 bytes	User name used for MSCHAPv2 response validation.

Table: Response types
Name	Value	Size	Description
LANMAN	1	24 bytes	LANMAN response used with the LANMAM, NTLM, or MSCHAPv1 authentication protocol.
NTLM	2	24 bytes	NTLMv1 response used with the NTLM or MSCHAPv1 authentication protocol.
NTLM2	4	24 bytes	NTLMv2 response used with the NTLM authentication protocol.
CHAP	128	17 bytes	CHAP ID + CHAP response used with the CHAP protocol.
MSCHAP2	256	56 bytes	Authentication challenge + peer challenge + MSCHAPv2 response used with the MSCHAPv2 protocol.

Table: Hash types
Name	Value	Allocated size	Description
LANMAN	1	16 bytes	Allocated space for accepting 16-byte LMHash.
NTLM	2	16 bytes	Allocated space for accepting 16-byte NTHash.
DPRSP	64	32 bytes	Allocated space for accepting 32-byte Digipass dynamic password.
MSCHAP2	256	43 bytes	Allocated space for accepting 43-byte string MSCHAPv2 authenticator response.

Table: Summary
Response type	Response	Nb of chall	Challenge type	Challenge
LANMAN	24-byte LM digest response	1	LANMAN	8-byte challenge
NTLM	24-byte NTLMv1 digest response	1	NTLM	8-byte challenge
NTLM2	24-byte NTLMv2 digest response	3	NTLM2	8-byte challenge
			NTLM2USER	User name
			NTLM2DOMAIN	Domain name
CHAP	1-byte CHAP id + 16-byte CHAP digest response	1	CHAP	Up to 255-byte challenge
MSCHAP2	16-byte authenticator challenge + 16 peer challenge + 24 MSCHAPv2 response	1	MSCHAP2	Up to 255-byte challenge

For LANMAN, NTLMv1, and NTLMv2, authentication responses may contain a concatenated challenge and response. In this case, the TData challenge structure could be NULL.

Return codes