3.5.4.9.1 NetrLogonControl2Ex (Opnum 18)

  • Article

The NetrLogonControl2Ex method SHOULD<245> execute administrative actions that pertain to the Netlogon server operation. It is used to query the status and control the actions of the Netlogon server. 

 NET_API_STATUS NetrLogonControl2Ex(
   [in, unique, string] LOGONSRV_HANDLE ServerName,
   [in] DWORD FunctionCode,
   [in] DWORD QueryLevel,
   [in, switch_is(FunctionCode)] PNETLOGON_CONTROL_DATA_INFORMATION Data,
   [out, switch_is(QueryLevel)] PNETLOGON_CONTROL_QUERY_INFORMATION Buffer
 );

ServerName: The custom binding handle, as defined in section 3.5.4.1.

FunctionCode: The control operation to be performed; it SHOULD<246> be one of the following values:

Value

Meaning

NETLOGON_CONTROL_QUERY

0x00000001

No operation, only the requested information is returned.

NETLOGON_CONTROL_REPLICATE

0x00000002

Forces a backup domain controller (BDC) to perform an immediate partial synchronization of all databases, as detailed in section 3.6.5.2.2.<247>

NETLOGON_CONTROL_SYNCHRONIZE

0x00000003

Forces a BDC to perform an immediate full synchronization of all databases.<248>

NETLOGON_CONTROL_PDC_REPLICATE

0x00000004

Forces a PDC to immediately send announcement messages to ask each BDC to replicate the database for details (see section 3.6).

NETLOGON_CONTROL_REDISCOVER

0x00000005

Forces the server to rediscover a domain controller in the specified domain and to set up a secure channel to the discovered DC.

NETLOGON_CONTROL_TC_QUERY

0x00000006

Queries the status of the last usage of the secure channel to the DC.

NETLOGON_CONTROL_TRANSPORT_NOTIFY

0x00000007

Notifies the Netlogon server that a new network connection has been added and causes the server to flush any DC cache.

NETLOGON_CONTROL_FIND_USER

0x00000008

Queries the name of a trusted domain that contains an account for a user.

NETLOGON_CONTROL_CHANGE_PASSWORD

0x00000009

Causes the server to generate a new shared secret and to set it on the account used by the DC for setting up the secure channel from the server.

NETLOGON_CONTROL_TC_VERIFY

0x0000000A

Verifies the current status of the server's secure channel to a DC in the specified domain.

NETLOGON_CONTROL_FORCE_DNS_REG

0x0000000B

Triggers the non-timer event, Force Register DNS Records, defined in [MS-ADTS] section 6.3.2.2.1.

NETLOGON_CONTROL_QUERY_DNS_REG

0x0000000C

SHOULD<249> query the status of DNS updates performed by the Netlogon server, as specified in [MS-ADTS] section 6.3.2.

NETLOGON_CONTROL_BACKUP_CHANGE_LOG

0x0000FFFC

Used for debugging purposes and does not affect the Netlogon protocol behavior.<250>

NETLOGON_CONTROL_TRUNCATE_LOG

0x0000FFFD

Used for debugging purposes and does not affect the Netlogon protocol behavior.<251>

NETLOGON_CONTROL_SET_DBFLAG

0x0000FFFE

Used for debugging purposes and does not affect the Netlogon protocol behavior.<252>

NETLOGON_CONTROL_BREAKPOINT

0x0000FFFF

Used for debugging purposes and SHOULD<253> be used only with checked builds. Calling NetrLogonControl2Ex with this function code does not affect the Netlogon protocol behavior.<254>

QueryLevel: Information query level requested by the client. The buffer returned in the Buffer parameter contains one of the following structures, based on the value of this field.

Value

Buffer Contents

0x00000001

A NETLOGON_INFO_1 structure is returned.

0x00000002

A NETLOGON_INFO_2 structure is returned.

0x00000003

A NETLOGON_INFO_3 structure is returned.

0x00000004

A NETLOGON_INFO_4 structure is returned.<255>

Data: A NETLOGON_CONTROL_DATA_INFORMATION structure, as specified in section 2.2.1.7.1, that contains specific data required by the query.

Buffer: A NETLOGON_CONTROL_QUERY_INFORMATION structure, as specified in section 2.2.1.7.6, that contains the specific query results, with a level of verbosity as specified in QueryLevel.

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:

  • The server uses the server name passed in the ServerName parameter to look up the domain for the request. If the name is not found, the server MUST return ERROR_INVALID_COMPUTERNAME.

  • If the client does not have sufficient privilege, the server MUST return ERROR_ACCESS_DENIED.

  • The QueryLevel parameter MUST contain a value between 1 and 4; otherwise, the server MUST return ERROR_INVALID_LEVEL.

    • When the QueryLevel parameter is set to 0x00000004, the FunctionCode parameter MUST be set to NETLOGON_CONTROL_FIND_USER (0x00000008); otherwise, the server MUST return ERROR_INVALID_PARAMETER.

    • When the QueryLevel parameter is set to 0x00000002, the FunctionCode parameter MUST be set to NETLOGON_CONTROL_REDISCOVER (0x00000005), NETLOGON_CONTROL_TC_QUERY (0x00000006), or NETLOGON_CONTROL_TC_VERIFY (0x0000000A); otherwise, the server MUST return ERROR_INVALID_PARAMETER.

  • When the FunctionCode parameter is set to:

    • NETLOGON_CONTROL_FIND_USER (0x00000008), the QueryLevel parameter MUST be set to 0x00000004; otherwise, the server MUST return ERROR_INVALID_PARAMETER.

    • NETLOGON_CONTROL_TC_VERIFY (0x0000000A), the QueryLevel parameter MUST be set to 0x00000002; otherwise, the server MUST return ERROR_INVALID_PARAMETER.

    • NETLOGON_CONTROL_QUERY_DNS_REG (0x0000000C), the QueryLevel parameter MUST be set to 0x00000001; otherwise, the server MUST return ERROR_INVALID_LEVEL.

  • The server MUST verify the Data parameter for the NETLOGON_CONTROL_REDISCOVER (0x00000005), NETLOGON_CONTROL_TC_QUERY (0x00000006), NETLOGON_CONTROL_FIND_USER (0x00000008), NETLOGON_CONTROL_CHANGE_PASSWORD (0x00000009), and NETLOGON_CONTROL_TC_VERIFY (0x0000000A) function codes:

    • If the parameter is NULL, the server MUST return ERROR_INVALID_PARAMETER.

    • For the NETLOGON_CONTROL_REDISCOVER (0x00000005), NETLOGON_CONTROL_TC_QUERY (0x00000006), NETLOGON_CONTROL_CHANGE_PASSWORD (0x00000009), and NETLOGON_CONTROL_TC_VERIFY (0x0000000A) function codes, if the parameter does not contain a valid domain name in the trust list, the server MUST return ERROR_NO_SUCH_DOMAIN.

    • For the NETLOGON_CONTROL_FIND_USER (0x00000008) function code, if the parameter does not contain a valid username, the server MUST return NERR_UserNotFound.

    For other function codes, the Data parameter is ignored.

Based on the FunctionCode parameter provided by the client, the server MUST complete the following before populating the return structure:

  • NETLOGON_CONTROL_QUERY: Nothing.

  • NETLOGON_CONTROL_REPLICATE: Return ERROR_NOT_SUPPORTED.<256>

  • NETLOGON_CONTROL_SYNCHRONIZE: Return ERROR_NOT_SUPPORTED.<257>

  • NETLOGON_CONTROL_PDC_REPLICATE: Return ERROR_NOT_SUPPORTED.<258>

  • NETLOGON_CONTROL_REDISCOVER: Force the server to rediscover DCs in the domain name provided in the TrustedDomainName field of the Data parameter and to set up a secure channel (section 3.1) to the discovered DC. DC rediscovery is the same as initial DC discovery (section 3.1.4.10). If a DC discovery and establishment of a secure channel to the DC fails, the error ERROR_NO_LOGON_SERVERS is returned.

  • NETLOGON_CONTROL_TC_QUERY: Provide return data based on the DC in the domain name provided in the TrustedDomainName field of the Data parameter.

  • NETLOGON_CONTROL_TRANSPORT_NOTIFY: To allow the server to immediately retry establishing a secure session over the new network connection that became available, the server sets the LastAuthenticationTry member of every entry in the ServerSessionInfo table maintained by the Netlogon client on the server's machine to zero, enumerating across every entry in the table. Also, if the server has a DC cache, the server flushes the LocatedDCsCache and FailedDiscoveryCache.

  • NETLOGON_CONTROL_FIND_USER: Query the name of a trusted domain that contains an account for a user with the username provided in the UserName field of the Data parameter. The server MUST be a DC; otherwise, return ERROR_NOT_SUPPORTED.

  • NETLOGON_CONTROL_CHANGE_PASSWORD: Generate a new shared secret for the domain name provided in the TrustedDomainName field of the Data parameter. The server MUST update the SharedSecret (section 3.1.1). If the TrustedDomainName field of the Data parameter is a trust name and the server is not a PDC ([MS-ADTS] section 6.1.5.3), the server MUST return ERROR_INVALID_DOMAIN_ROLE.

  • NETLOGON_CONTROL_TC_VERIFY: Call any Netlogon method that requires a secure channel (section 3.1.4.6) to the DC in the domain name provided in the TrustedDomainName field of the Data parameter.

  • NETLOGON_CONTROL_FORCE_DNS_REG: The DC SHOULD<259> re-register all of its DNS records ([MS-ADTS] section 6.3.2).

  • NETLOGON_CONTROL_QUERY_DNS_REG: Query the status of DNS updates performed by the Netlogon server.<260>

  • NETLOGON_CONTROL_BACKUP_CHANGE_LOG: Nothing.

  • NETLOGON_CONTROL_TRUNCATE_LOG: Nothing.

  • NETLOGON_CONTROL_SET_DBFLAG: Nothing.

  • NETLOGON_CONTROL_BREAKPOINT: Nothing.

The following describes the output generated in the Buffer parameter based on the FunctionCode and QueryLevel requested.

For QueryLevel 1, the return structure MUST be generated as follows:

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo1.netlog1_flags MUST be set to the netlog1_flags values that are applicable to the server. See NETLOGON_INFO_1 (section 2.2.1.7.2) for a description of the netlog1_flags field.

  • If the FunctionCode parameter has the value NETLOGON_CONTROL_QUERY_DNS_REG (0x0000000C), and any DNS registration or deregistration ([MS-ADTS] section 6.3.2) errors occurred on the last completed update, then the NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo1.netlog1_flags G bit MUST be set. Otherwise, the NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo1.netlog1_flags G bit MUST NOT be set.

  • If this is a non-PDC computer, NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo1.netlog1_pdc_connection_status MUST be set to the current connection status of the PDC, which is stored in the ConnectionStatus field of the ServerSessionInfo table. This field MUST be set to zero if this server is the PDC.

  • If FunctionCode NETLOGON_CONTROL_PDC_REPLICATE (0x00000004) is supported and ntMixedDomain is set to zero ([MS-ADTS] section 6.1.4.1), the server MUST return ERROR_NOT_SUPPORTED. Otherwise, the server returns ERROR_SUCCESS.

For QueryLevel 2, the return structure MUST be generated as follows:

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_flags MUST be set to the netlog2_flags values that are applicable to the server. For a description of the netlog2_flags member, see 2.2.1.7.3.

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set as follows.

    • Call NetrServerGetTrustInof to the DC with which it has an established secure channel for the domain specified in the Data.TrustedDomainName parameter received.

      • If the server returns STATUS_NOT_SUPPORTED, then NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to the value of the ConnectionStatus field from the ServerSessionInfo table.

      • If the server returns anything else and ServerSessionInfo.ConnectionStatus is not STATUS_SUCCESS, then NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to the value of ConnectionStatus field from the ServerSessionInfo table.

      • Otherwise, the ConnectionStatus field of the ServerSessionInfo table is STATUS_SUCCESS and the following rules apply:

        1. If the TrustInfo value returned by NetrServerGetTrustInfo is not NULL and the UlongEntryCount value is greater than 0, then process the first ULONG element in the UlongData array as follows:

          • If the TRUST_ATTRIBUTE_FOREST_TRANSITIVE (0x00000008) bit is set, and if the server processing the element is either of the following:

            • Workstation: NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to STATUS_DOMAIN_TRUST_INCONSISTENT.

            • Domain controller (DC): If the D flag is not set in the TrustedDomains.TrustAttributes for the domain specified in the Data.TrustedDomainName parameter received, then NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to STATUS_DOMAIN_TRUST_INCONSISTENT.

          • Otherwise, if the server processing the element is a domain controller and the D flag is set in the TrustedDomains.TrustAttributes for the domain specified in the Data.TrustedDomainName parameter received, then NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to STATUS_DOMAIN_TRUST_INCONSISTENT.

        2. Verify that the SharedSecret stored locally is the same as what was returned by NetrServerGetTrustInfo in EncryptedNewOwfPassword and EncryptedOldOwfPassword. If the SecureChannelType returned by NetrServerGetTrustInfo is TrustedDnsDomainSecureChannel or TrustedDomainSecureChannel, then verify using the local trust secrets. For all other types of SecureChannelType values, verify using the SharedSecret of the computer account. If verification fails, then NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status MUST be set to STATUS_WRONG_PASSWORD.

        3. If NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_pdc_connection_status has not been set, then it MUST be set to STATUS_SUCCESS.

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_trusted_dc_name MUST be set to the name of the DC with which the computer has a secure channel established, which is stored in the DomainName field of the ServerSessionInfo table.

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo2.netlog2_tc_connection_status MUST be set to the status of the secure channel, which is stored in the ConnectionStatus field of the ServerSessionInfo table.

For QueryLevel 3, the return structure MUST be generated as follows:

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo3.netlog3_flags MUST be set to zero.

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo3.netlog3_logon_attempts MUST be set to LogonAttempts.

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo3.netlog3_reserved1 through NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo3.netlog3_reserved5 MUST be set to zero.

For QueryLevel 4, the return structure MUST be generated as follows:

  • NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo4.netlog4_trusted_domain_name MUST be set to the trusted domain that the user was found in. NETLOGON_CONTROL_QUERY_INFORMATION.NetlogonInfo4.netlog4_trusted_dc_name MUST be set to the DC in the trusted domain.

    In addition, the returned Buffer structure contains undefined data of varied size at the end, which MUST be ignored.