Expand Minimize

Msv1_0SubAuthenticationRoutine function

The Msv1_0SubAuthenticationRoutine function performs client/server-specific authentication.

The security principal's credentials and information from the Security Accounts Manager (SAM) database are passed to this function for authentication.

This function is implemented by custom subauthentication package DLLs for use with the MSV1_0 authentication package.

The Msv1_0SubAuthenticationRoutine function is called only for a noninteractive authentication, only on the authenticating server where the account resides, and only if a subauthentication DLL is registered under the correct key in the registry.

Note  The Kerberos authentication package does not call this routine.

Syntax


NTSTATUS NTAPI Msv1_0SubAuthenticationRoutine(
  _In_   NETLOGON_LOGON_INFO_CLASS LogonLevel,
  _In_   PVOID LogonInformation,
  _In_   ULONG Flags,
  _In_   PUSER_ALL_INFORMATION UserAll,
  _Out_  PULONG WhichFields,
  _Out_  PULONG UserFlags,
  _Out_  PBOOLEAN Authoritative,
  _Out_  PLARGE_INTEGER LogoffTime,
  _Out_  PLARGE_INTEGER KickoffTime
);

Parameters

LogonLevel [in]

Specifies the level of information given in the LogonInformation parameter. This parameter is normally set to NetlogonInteractiveInformation.

LogonInformation [in]

A pointer to a NETLOGON_LOGON_IDENTITY_INFO structure. Members of this structure contain information about the user who is logging on. The LogonDomainName member of this structure is ignored.

Flags [in]

Optional. Contains flags that describe the circumstances of the logon. This parameter can be one of the following values.

ValueMeaning
MSV1_0_PASSTHRU

Pass-through authentication. The user is not connecting to this machine.

MSV1_0_GUEST_LOGON

This is a retry of the logon using the GUEST user account.

 

UserAll [in]

A pointer to a USER_ALL_INFORMATION structure that contains the description of the user as returned from the SAM database.

WhichFields [out]

Returns the members of the USER_ALL_INFORMATION structure that need to be written back to the SAM database. These members will be written only if Msv1_0SubAuthenticationRoutine returns success to the caller. Only the following value is valid.

ValueMeaning
USER_ALL_PARAMETERS

Write the data contained in the Parameters member of the UserAll structure back to the SAM database.

If the size of the Parameters member's UNICODE_STRING buffer is changed, Msv1_0SubAuthenticationRoutine must delete the buffer by using the MIDL_user_free function and reallocate it by using the MIDL_user_allocate function.

 

UserFlags [out]

Values to be returned from the LsaLogonUser function's ProfileBuffer parameter, when it contains a MSV1_0_LM20_LOGON_PROFILE structure. The following values are currently defined for the UserFlags member of the structure.

ValueMeaning
LOGON_GUEST

This is a guest logon.

LOGON_NOENCRYPTION

The caller did not specify encrypted credentials.

 

Note  By convention, subauthentication packages return bits in only the high order byte of UserFlags; however, this convention is not enforced.

Authoritative [out]

A pointer to a Boolean value that indicates whether the status returned is an authoritative status that should be returned to the original caller. If the returned value is FALSE, the logon request can be tried again on another domain controller. This parameter should return valid information regardless of the return value of the function call.

LogoffTime [out]

A pointer to a value that receives the time at which the user should log off the system. This time is used to control the logon lifetime and is specified as a GMT-relative system time.

KickoffTime [out]

A pointer to a value that receives the time at which the user should be logged off the system. This time is used to control the logon lifetime and is specified as a GMT-relative system time. If the user is not to be logged off, specify a large positive value, such as:


KickoffTime->HighPart = 0x7FFFFFFF;
KickoffTime->LowPart = 0xFFFFFFFF;


Return value

This function must return one of the following values.

Return codeDescription
STATUS_SUCCESS

There was no error.

STATUS_ACCOUNT_DISABLED

The account is disabled.

STATUS_ACCOUNT_EXPIRED

The account has expired.

STATUS_ACCOUNT_LOCKED_OUT

The account is locked out.

STATUS_INVALID_INFO_CLASS

LogonLevel is not valid.

STATUS_INVALID_LOGON_HOURS

The user is not authorized to log on at this time.

STATUS_INVALID_WORKSTATION

The user is not authorized to log on to the specified workstation.

STATUS_NO_SUCH_USER

The specified user has no account.

STATUS_PASSWORD_EXPIRED

The password is expired.

STATUS_PASSWORD_MUST_CHANGE

The account is marked to indicate that the password must be changed on the next logon.

STATUS_WRONG_PASSWORD

The password was not valid.

 

Remarks

This function is called by the MSV1_0 authentication package if part of the AuthenticationInformation parameter indicates that subauthentication is to be done and if a subauthentication DLL that exports the Msv1_0SubAuthenticationRoutine function is correctly registered on the workstation.

The MSV1_0 authentication package does not support subauthentication for interactive logons, which require the MSV1_0_INTERACTIVE_LOGON structure. Network logons, which require the MSV1_0_LM20_LOGON structure, can use subauthentication.

The Msv1_0SubAuthenticationRoutine function is called after the correct domain controller has been located and all information about the security principal to be authenticated has been retrieved from the SAM database. When subauthentication is used, authentication is the responsibility of the subauthentication DLL and must be done by the Msv1_0SubAuthenticationRoutine function exported by that DLL.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Subauth.h

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.