3.5.4.5.1 NetrLogonSamLogonEx (Opnum 39)

  • Article

The NetrLogonSamLogonEx method SHOULD<201> provide an extension to NetrLogonSamLogon that accepts an extra flags parameter and uses Secure RPC ([MS-RPCE] section 3.3.1.5.2) instead of Netlogon authenticators. This method handles logon requests for the SAM accounts and allows for generic pass-through authentication, as specified in section 3.2.4.1. 

 NTSTATUS NetrLogonSamLogonEx(
   [in] handle_t ContextHandle,
   [in, unique, string] wchar_t* LogonServer,
   [in, unique, string] wchar_t* ComputerName,
   [in] NETLOGON_LOGON_INFO_CLASS LogonLevel,
   [in, switch_is(LogonLevel)] PNETLOGON_LEVEL LogonInformation,
   [in] NETLOGON_VALIDATION_INFO_CLASS ValidationLevel,
   [out, switch_is(ValidationLevel)] 
     PNETLOGON_VALIDATION ValidationInformation,
   [out] UCHAR * Authoritative,
   [in, out] ULONG * ExtraFlags
 );

ContextHandle: A primitive RPC handle that identifies a particular client/server binding, as specified in section 3.5.4.1.

LogonServer: The null-terminated Unicode string that contains the NetBIOS name of the server that will handle the logon request.

ComputerName: The null-terminated Unicode string that contains the NetBIOS name of the client computer sending the logon request.

LogonLevel: A NETLOGON_LOGON_INFO_CLASS enumerated type, as specified in section 2.2.1.4.16, that specifies the type of the logon information passed in the LogonInformation parameter.

LogonInformation: A pointer to a NETLOGON_LEVEL structure, as specified in section 2.2.1.4.6, that describes the logon request information.

ValidationLevel: A NETLOGON_VALIDATION_INFO_CLASS enumerated type, as specified in section 2.2.1.4.17, that contains the validation level requested by the client.

ValidationInformation: A pointer to a NETLOGON_VALIDATION structure, as specified in section 2.2.1.4.14, that describes the user validation information returned to the client. The type of the NETLOGON_VALIDATION used is determined by the value of the ValidationLevel parameter.

Authoritative: A pointer to a char value that represents a Boolean condition. FALSE is indicated by the value 0x00, and TRUE SHOULD<202> be indicated by the value 0x01 and MAY also be indicated by any nonzero value.

This Boolean value indicates whether the validation information is final. This field is necessary because the request might be forwarded through multiple servers. The value TRUE indicates that the validation information is an authoritative response and MUST remain unchanged. The value FALSE indicates that the validation information is not an authoritative response and that the client can resend the request to another server.

ExtraFlags: A pointer to a set of bit flags that specify delivery settings. A flag is TRUE (or set) if its value is equal to 1. Output flags MUST be the same as input. The value is constructed from zero or more bit flags from the following table.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

D

C

B

A

Where the bits SHOULD<203> be defined as:

Value

Description

A

Request MUST be passed to the domain controller at the root of the forest.

B

Request MUST be passed to the DC at the end of the first hop over a cross-forest trust.

C

Request was passed by an RODC to a DC in a different domain.

D

Request is an NTLM authentication package request passed by an RODC.

All other bits MUST be set to zero and ignored on receipt. Flags A, B, C, and D can be combined, and the server SHOULD honor the flags. Flags A and B require the server to take action to deliver the request, while flags C and D are informational and implementation specific.

Return Values: The method returns 0x00000000 on success; otherwise, it returns a nonzero error code.

On receiving this call, the server MUST perform the following validation steps:<204>

  • Apply Common Error Processing Rule A, specified in section 3.

  • The pointer contained in the LogonInformation parameter MUST NOT be NULL; otherwise, the server MUST return STATUS_INVALID_PARAMETER.

  • Verify that the caller is using Secure RPC ([MS-RPCE] section 3.3.1.5.2); otherwise, the server MUST return STATUS_ACCESS_DENIED.

  • Verify that if bit B in ExtraFlags is enabled, then the domain's TAFT bit in the trustAttributes structure ([MS-ADTS] section 6.1.6.7.9) is also enabled; otherwise, the server MUST return STATUS_NO_SUCH_USER.

  • Apply Common Error Processing Rule B, specified in section 3, to the LogonServer parameter.

  • If the LogonServer parameter is not NULL, it is compared against the server's computer name. If the LogonServer parameter does not match the server's computer name or is NULL, the server MUST return STATUS_INVALID_COMPUTER_NAME. If the LogonServer parameter matches the server's computer name, processing proceeds.

If the server cannot service the request due to an implementation-specific condition, the server returns STATUS_ACCESS_DENIED.

The server uses the server name passed in the LogonServer parameter to look up the domain that the server hosts. If the name is not found, the server MUST return STATUS_INVALID_COMPUTER_NAME.

The server MUST decrypt data protected in transport:

When the LogonLevel parameter is set to 4 (NetlogonGenericInformation), the call is for generic pass-through to authentication packages, and the ValidationLevel parameter MUST be 5 (NetlogonValidationGenericInfo2) or 4 (NetlogonValidationGenericInfo). If this is not true, the server MUST return STATUS_INVALID_INFO_CLASS.<208>

If LogonLevel is not set to 4 (NetlogonGenericInformation), the ValidationLevel parameter MUST be 6 (NetlogonValidationSamInfo4) or 3 (NetlogonValidationSamInfo2) or 2 (NetlogonValidationSamInfo). If this is not true, the server MUST return STATUS_INVALID_INFO_CLASS.<209> The data is opaque to Netlogon, and the parameters MUST be passed to NTLM ([MS-APDS] section 3.1).

If the request is not for the domain of which the server is a member and the server is a DC, then the server MUST perform external behavior consistent with locally invoking LsarQueryTrustedDomainInfoByName ([MS-LSAD] section 3.1.4.7.5), using the following parameters (policy handle is not needed locally):

  • Domain is set to the value of the TrustedDomainName parameter.

  • InformationClass is set to the value of TrustedDomainInformationEx.

The server MUST also verify that:

  • The securityIdentifier (Sid) field ([MS-ADTS] section 6.1.6.7.8) is not NULL,

  • The trustType field ([MS-ADTS] section 6.1.6.7.15) is 1 or 2, and

  • The trustAttributes field ([MS-ADTS] section 6.1.6.7.9) does not contain TRUST_ATTRIBUTE_UPLEVEL_ONLY

If LsarQueryTrustedDomainInfoByName succeeds and returns the domain information in TrustedDomainInformation, the server MUST check if it has established a secure channel with the domain. If there is not an established secure channel, then the server MUST return the error code STATUS_NO_SUCH_USER. If there is an established secure channel then the server MUST call NetrLogonSamLogonEx using LogonLevel, LogonInformation, ValidationLevel, ValidationInformation, and ExtraFlags (ExtraFlags can be updated by the server before passing it to NetrLogonSamLogonEx on the DC) to the DC with which it has an established secure channel.

If the server is a DC, the request uses NTLMv2, and LogonLevel is set to either NetlogonNetworkInformation or NetlogonNetworkTransitiveInformation, the server MUST perform target domain name validation as specified in section 3.5.4.5.1.1.<210>

If the server is a DC, the request uses NTLMv2, and the client is an RODC in the server’s domain, the server MUST perform RODC cachability validation as specified in section 3.5.4.5.1.2.<211>

If an error is returned from an authentication package (in the case of generic pass-through) or from NTLM (in the case of logon), the error code MUST be propagated to the caller of this method.

If the LogonLevel is NetlogonNetworkInformation or NetlogonNetworkTransitiveInformation, the server MUST encrypt the UserSessionKey and the first two elements of the ExpansionRoom array in the NETLOGON_VALIDATION_SAM_INFO (section 2.2.1.4.11) or in the NETLOGON_VALIDATION_SAM_INFO2 (section 2.2.1.4.12) structure.

This method SHOULD be called only by a machine that has established a secure channel with the server.

This is the only NetrLogonSamLogon family method that uses secure channel and does not use Netlogon authenticator parameters.