3.2.4.15 NetrRenameMachineInDomain2 (Opnum 24)

  • Article

The NetrRenameMachineInDomain2 method uses encrypted credentials to change the locally persisted variable ComputerNameNetBIOS (section 3.2.1.5) and to optionally rename the computer account for a server currently in a domain, without first removing the computer from the domain and then adding it back.<81>

 unsigned long NetrRenameMachineInDomain2(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string, unique] wchar_t* MachineName,
   [in, string, unique] wchar_t* AccountName,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD Password,
   [in] unsigned long Options
 );

RpcBindingHandle: An RPC binding handle [C706].

ServerName: This parameter has no effect on message processing in any environment. The client MUST set this parameter to a value that resolves to the IP protocol layer destination address of the RPC packets it transmits ([MS-RPCE] section 2.1.1.2). The server (2) MUST ignore this parameter.

MachineName: A pointer to a string that specifies the new computer name. This parameter is optional. If this parameter is NULL, the current machine name is used.

AccountName: A pointer to a string that specifies an account name in the joined domain to use when connecting to a domain controller. This parameter is optional. If this parameter is NULL, the caller's account name is used.

Password: An optional pointer to a JOINPR_ENCRYPTED_USER_PASSWORD structure (section 2.2.5.18) that specifies the encrypted password to use with the AccountName parameter. If this parameter is NULL, the caller's security context MUST be used.

Options: A 32-bit bitfield that specifies modifications to default server behavior in message processing.

Value/code

Meaning

NETSETUP_ACCT_CREATE

0x00000002

Renames the computer account in the domain. If this flag is not set, the computer name is changed locally but no changes are made to the computer account in the domain.

NETSETUP_DNS_NAME_CHANGES_ONLY

0x00001000

Limits any updates to DNS-based names only.

Return Values: When the message processing result meets the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_NOT_SUPPORTED

0x00000032

The request is not supported.

ERROR_INVALID_PASSWORD

0x00000056

The specified network password is not correct.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

NERR_SetupNotJoined

0x00000A84

This computer is not currently joined to a domain.

NERR_SetupDomainController

0x00000A85

This computer is a domain controller and cannot be renamed.<82>

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

Unless otherwise noted, if the server encounters an error during message processing, the server SHOULD revert any state changes made, MUST stop message processing, and MUST return the error to the caller.<83>

The following definitions are used in the specification of message processing that follows:

  • DomainControllerString: A UTF-8 string that contains the name of a domain controller in the domain to which the server is joined.

  • NewComputerAccountString: A UTF-8 string that contains the value to be stored in the samAccountName attribute of the server's computer account in the domain database.

  • ComputerNameString: A UTF-8 string that contains the new NetBIOS name of the server.

  • DNSComputerNameString: A UTF-8 string that contains the new Internet host name of the server.

  • Spn1: A UTF-8 string.

  • Spn2: A UTF-8 string.

  • PasswordString: A UTF-8 string that contains a password in cleartext.

  • DomainControllerConnection: An ADCONNECTION_HANDLE ([MS-DTYP] section 2.2.2) to a domain controller.

  • LdapResultMessages: A list of LDAPMessage ([RFC2251]) containing results from an operation performed on DomainControllerConnection.

  • ComputerAccountDN: A UTF-8 string that contains the distinguished name (DN) of the computer account.

The following statements define the sequence of message processing operations.

  1. The server (2) MUST retrieve the RPC protocol sequence used for the current call ([MS-RPCE] section 3.1.3.4.1) specifying the server binding handle maintained by the RPC runtime ([C706] section 6.2.1). If that RPC protocol sequence is not NCACN_NP, the server SHOULD return RPC_S_PROTSEQ_NOT_SUPPORTED.<84>

  2. The server MUST check that the caller has been granted access rights using the algorithm in the Access Control Abstract Data Model (section 3.2.1.1), with Access Request mask initialized to WKSTA_NETAPI_CHANGE_CONFIG; if not, the server MUST return ERROR_ACCESS_DENIED.

  3. The server MUST impersonate the client by invoking the StartImpersonatingClient task (section 3.2.4.29.6). If this operation fails, the server MUST return an error.

  4. If Password is NULL then PasswordString MUST be NULL. Otherwise, the server MUST decrypt and decode the Password (section 2.2.5.18). PasswordString MUST be equal to the decrypted and decoded value. The decrypted buffer is represented as a JOINPR_USER_PASSWORD structure (section 2.2.5.17). The value of the Length member MUST be less than 513; otherwise, message processing is stopped, and the server MUST return ERROR_INVALID_PASSWORD.

  5. If the server is not a domain controller, or is not a member of a domain, the server MUST fail the call with NERR_SetupNotJoined. Otherwise, message processing continues.

  6. If the server is an RODC ([MS-DRSR] section 5.7), the server MUST fail the call with ERROR_NOT_SUPPORTED. Otherwise, message processing continues.

  7. If the Options parameter does not contain NETSETUP_ACCT_CREATE, the server MUST apply the new name locally, updating ComputerNameNetBIOS so that other protocols on the server can operate using the new name. If this operation fails, the server MUST return an implementation-specific error and stop message processing. If the operation is successful, the server MUST stop message processing and return successfully.

  8. If the Options parameter contains NETSETUP_ACCT_CREATE, the server MUST continue message processing.

  9. The server MUST convert<85> the name in the MachineName parameter to a string NetBIOS name. This conversion MUST match with the conversion used in Netlogon Remote Protocol. ComputerNameString MUST equal the resulting value. NewComputerAccountString MUST equal the resulting value concatenated with the "$" character.

  10. The server MUST use the security context associated with the credentials provided in the AccountName and Password parameters to perform the rest of the remote operations.

  11. The server MUST locate a writable domain controller for the domain to which the server is joined, by invoking the DsrGetDcNameEx2 method on the local [MS-NRPC] server specifying the following parameters:

    • ComputerName = NULL

    • AccountName = ComputerNameNetBIOS

    • AllowableAccountControlBits = ADS_UF_WORKSTATION_TRUST_ACCOUNT | ADS_UF_SERVER_TRUST_ACCOUNT ([MS-ADTS] section 2.2.16)

    • DomainName = DomainNameFQDN (section 3.2.1.5)

    • DomainGuid = NULL

    • SiteName = NULL

    • Flags = (J | B) ([MS-NRPC] section 3.5.4.3.1)

      If the DsrGetDcNameEx2 method fails, the server MUST retry the call specifying the following parameters:

    • ComputerName = NULL

    • AccountName = NULL

    • AllowableAccountControlBits = 0

    • DomainName = DomainNameFQDN

    • DomainGuid = NULL

    • SiteName = NULL

    • Flags = (J | B) ([MS-NRPC] section 3.5.4.3.1)

      If both calls fail, the method MUST fail.

      Otherwise, DomainControllerString MUST equal the string name of the returned writable domain controller.

  12. If the NETSETUP_DNS_NAME_CHANGES_ONLY bit is not set in Options, the server MUST make the following attribute update:

    • samAccountName updated to equal NewComputerAccountString.

  13. DNSComputerNameString is the concatenation of ComputerNameString and the DNS suffix on the server.<86>

  14. Spn1 is the concatenation of "HOST/" with DNSComputerNameString.

  15. Spn2 is the concatenation of "HOST/" with ComputerNameString.

  16. The server invokes LDAP Bind (section 3.2.4.29.2) with the following parameters:

    • DomainControllerBindTarget: DomainControllerString

    • AccountNameForBind: AccountName

    • PasswordForBind: PasswordString

    • Encrypt: FALSE

    • DisallowReferrals: FALSE

      The result is stored in DomainControllerConnection.

  17. The server invokes Query Computer Account DN for the Local Machine (section 3.2.4.29.1), specifying DomainControllerString for the DomainControllerQueryTarget parameter, storing the result in ComputerAccountDN.

  18. The server invokes the "Performing an LDAP Operation on an ADConnection" task of [MS-ADTS] section 7.6.1.6 with the following parameters:

    • TaskInputADConnection: DomainControllerConnection

    • TaskInputRequestMessage: LDAP modifyRequest message [RFC2251] section 4.6 as follows:

      • Object: ComputerAccountDN

      • The modification sequence has two list entries, set as follows:

        • First list entry

          • operation: replace

          • modification:

            • type: DnsHostName

            • vals: DNSComputerNameString

        • Second list entry

          • operation: replace

          • modification:

            • type: ServicePrincipalName

            • vals: Spn1 and Spn2

    • TaskOutputResultMessages: LDAPResultMessages

  19. The server invokes LDAP Unbind (section 3.2.4.29.3), with ADConnectionToUnbind set to DomainControllerConnection.

  20. If any of these updates fail, the server MUST fail the request and return the error from the writable domain controller.

  21. The server MUST invoke "Update Display Name using SAMR" (section 3.2.4.29.5), specifying the following parameters:

    • DomainController: DomainControllerString

    • MachineName: NewComputerNameString

      The result of this operation MUST be ignored.

  22. The server MUST apply the new name locally, updating ComputerNameNetBIOS so that other protocols on the server can operate using the new name.

  23. The server MUST stop impersonating the client by invoking the StopImpersonatingClient task (section 3.2.4.29.7).

If no errors occur, the server MUST return NERR_Success.