Msv1_0SubAuthenticationFilter function (subauth.h)

The Msv1_0SubAuthenticationFilter function performs user logon authentication that is specific to domain controllers.

The function receives the user's logon data and all information found for the user in the domain controller's Security Accounts Manager (SAM) database.

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

Syntax

NTSTATUS Msv1_0SubAuthenticationFilter(
  [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

[in] LogonLevel

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

[in] LogonInformation

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 is ignored.

[in] Flags

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

[in] UserAll

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

[out] WhichFields

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_0SubAuthenticationFilter returns success. Only the following value is valid.

[out] UserFlags

Values to be returned from the LsaLogonUser function in that function's ProfileBuffer parameter. This parameter can be one of the following values.

[out] Authoritative

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 value returned 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. This parameter is not used with the Kerberos authentication package.

[out] LogoffTime

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 Windows system time.

[out] KickoffTime

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 automatically logged off, specify a large positive value, as follows:

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

Return value

This function must return one of the following values.

When the Msv1_0SubAuthenticationFilter function is used with the Kerberos authentication package, if the function call returns STATUS_SUCCESS and one of the two parameters LogoffTime or KickoffTime has a nonzero value, this value is used as the ticket lifetime. If, on the other hand, the values of both parameters are nonzero, the smaller of these two values is used.

If the value that is used for the ticket lifetime (the sooner of LogoffTime and KickoffTime) is greater than the default ticket lifetime, then that value will be used as the maximum renewal time for the ticket. Conversely, if the larger of the two values (the later of LogoffTime and KickoffTime) is less than the default ticket lifetime, this value will be used as the ticket lifetime. For more information, see Microsoft Kerberos.

When used with the Kerberos authentication package, if this function returns an error, the Key Distribution Center (KDC) will return the Kerberos error KDC_ERR_POLICY, with the status value as the extended error code.

Remarks

Implementations of this function should not execute any operations that cause Lightweight Directory Access Protocol (LDAP) traffic. For example, do not connect to and query the Active Directory database.

After the MSV1_0 or Kerberos authentication package has validated a logon, the Msv1_0SubAuthenticationFilter function can perform additional validation to determine whether a user can log on to a network account. This function is called if the subauthentication package DLL is properly registered as 'Auth0' in the domain controller's registry. The registry path is different depending on whether the function is in a MSV1_0 or Kerberos Subauthentication package DLL.

This filter routine may return STATUS_SUCCESS, which indicates that the logon should proceed, or a failure code, which indicates that the additional validation failed.

Requirements