3.2.4.20 NetrSetPrimaryComputerName (Opnum 29)

  • Article

The NetrSetPrimaryComputerName method sets the primary computer name for a specified server (2).<113>

 unsigned long NetrSetPrimaryComputerName(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string, unique] wchar_t* PrimaryName,
   [in, string, unique] wchar_t* DomainAccount,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD EncryptedPassword,
   [in] unsigned long Reserved
 );

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 MUST ignore this parameter.

PrimaryName: A pointer to a string that specifies the primary computer name to set. The name MUST be a valid DNS host name [RFC1035].

DomainAccount: A pointer to a string that specifies the 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 MUST be used. This parameter is not used if the server is not joined to a domain.

  • <NetBIOSDomainName>\<UserName>

  • <FullyQualifiedDNSDomainName>\<UserName>

  • <UserName>@<FullyQualifiedDNSDomainName>

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

Reserved: A 32-bit bitfield that SHOULD be set to zero.


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

0

0

0

IU

Where the bits are defined as:

Value

Meaning

IU

NET_IGNORE_UNSUPPORTED_FLAGS

If 1, the server MUST ignore the values of the other bits in this field.

If 0, the values of the other bits in this field MUST be 0; otherwise, the server MUST return ERROR_INVALID_FLAGS.<114>

Return Values: When the message processing result matches 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

This method is not supported by this server.

ERROR_INVALID_PASSWORD

0x00000056

The specified network password is incorrect.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect.

0x0000007B

ERROR_INVALID_NAME

An invalid name parameter is specified.

ERROR_INVALID_FLAGS

0x000003EC

Reserved contains an invalid value.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

RPC_S_CALL_IN_PROGRESS

0x000006FF

A remote procedure call is already in progress.<115>

NERR_DefaultJoinRequired

0x00000A86

The destination domain controller does not support creating machine accounts in OUs.

DNS_ERROR_INVALID_NAME_CHAR

0x00002558

The Internet host name contains an invalid character.

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.<116>

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

  • OldAlternateNames: MUST be a tuple entry for alternate-computer-names (section 3.2.1.2).

  • NewAlternateNames: MUST be a new tuple entry for alternate-computer-names.

  • NetBIOSNameString: A Unicode UTF-8 string containing the value of PrimaryName converted to a NetBIOS name.

  • I: Unsigned integer used for indexing alternate-computer-names.

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

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

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

  • WritableDomainControllerDN: A UTF-8 string that contains the DN of the nTDSDSA object ([MS-ADTS] section 6.1.1.2.2.1.2.1.1) for the domain controller named in DomainControllerString.

  • ReadOnlyDomainControllerConnection: An ADConnection ([MS-ADTS] section 7.3) to a read-only domain controller.

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

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

  • ComputerAccountExtendedDN: A UTF-8 string that contains the extended DN ([MS-ADTS] section 3.1.1.3.4.1.5) of the computer account.

  • ServerObjectDN: A UTF-8 string that contains the DN of the nTDSDSA object ([MS-ADTS] section 6.1.1.2.2.1.2.1.1) for the server when the server is an RODC.

  • IsRODC: A Boolean that is TRUE if the server is a read-only domain controller ([MS-DRSR] section 5.7), and FALSE otherwise.

The following statements define the sequence of message processing operations.

  1. The server 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.<117>

  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 SHOULD<118> return ERROR_NOT_SUPPORTED if the server is a client SKU configuration.

  4. The server invokes AmIRODC ([MS-DRSR] section 5.7), storing the result in IsRODC.

  5. If EncryptedPassword is NULL or DomainAccount is NULL, PasswordString MUST be NULL. Otherwise, the server MUST decrypt and decode the EncryptedPassword (section 2.2.5.18). PasswordString MUST equal 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.

  6. The server MUST validate PrimaryName. The validation [RFC1035] is performed in the following order. Specifically, the name MUST NOT:

    • Be longer than 255 octets.

    • Contain a label longer than 63 octets.

    • Contain two or more consecutive dots.

    • Begin with a dot.

  7. ERROR_INVALID_NAME MUST be returned if any condition in the preceding group is violated. Otherwise, PrimaryName validation continues. The name MUST NOT:

    • Contain a space.

    • Contain any of the following characters:

       { | } ~ [ \ ] ^ ' : ; < = > ? @ ! " # $ % ^ ` ( ) + / , *

  8. DNS_ERROR_INVALID_NAME_CHAR MUST be returned if any condition in the preceding group is violated. Otherwise, processing continues.

  9. The server MUST convert  the name in the PrimaryName parameter to a string NetBIOS name.<119> This conversion MUST match the conversion used in [MS-NRPC]. NetBIOSNameString MUST be equal to this converted value.

  10. The server MUST locate the tuple in the list of alternate-computer-names, where alternate-computer-names[I].FQDN is equal to PrimaryName and alternate-computer-names[I].NetBIOS MUST be equal to NetBIOSNameString. OldAlternateNames MUST be equal to the tuple identified.

  11. 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.

  12. The server MUST remove the tuple located above from the list in alternate-computer-names persisted locally.

  13. NewAlternateNames.FQDN MUST be equal to the current ComputerNameFQDN (section 3.2.1.5).

  14. NewAlternateNames.NetBIOS MUST be equal to the current ComputerNameNetBIOS (section 3.2.1.5).

  15. NewAlternateNames MUST be appended to the list in alternate-computer-names persisted locally.

  16. The server MUST set ComputerNameNetBIOS to equal NetBIOSNameString.

  17. The server MUST set ComputerNameFQDN to equal PrimaryName.

  18. The server MUST store the values ComputerName.NetBIOS, ComputerName.FQDN, and names in alternate-computer-names locally so that the set of NetBIOS and Internet host names currently assigned to this computer can be resolved on the network ([RFC1001] and [NIS]). If an error occurs while storing the values, steps 19 through 31 are not processed and the server MUST return the error after processing steps 32 through 34.

  19. If the server is not joined to a domain ([MS-ADTS] section 6.4), proceed to step 32. Otherwise, the server MUST make the following updates in the domain.

  20. The server MUST stop the Netlogon Remote Protocol ([MS-NRPC]) if it is running. If an error occurs in this operation, steps 21 through 31 are not processed, and the server MUST return the error after processing steps 32 through 34.

  21. The server MUST locate a writable domain controller 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 a domain controller cannot be located, steps 22 through 31 are not processed and the server MUST return the error after processing steps 32 through 34.

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

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

    • DomainControllerBindTarget: DomainControllerString

    • AccountNameForBind: AccountName

    • PasswordForBind: PasswordString

    • Encrypt: FALSE

    • DisallowReferrals: TRUE

      The result is stored in DomainControllerConnection. If the LDAP bind returns an error, steps 23 through 31 are not processed and the server MUST return the error after processing steps 32 through 34.

  23. If IsRODC is TRUE, the server invokes LDAP Bind with the following parameters:

    • DomainControllerBindTarget: ComputerNameNetBIOS

    • AccountNameForBind: AccountName

    • PasswordForBind: PasswordString

    • Encrypt: FALSE

    • DisallowReferrals: TRUE

      The result is stored in ReadOnlyDomainControllerConnection. If the LDAP bind returns an error, steps 24 through 30 are not processed and the server MUST return the error after processing steps 31 through 34.

  24. 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. If the query returns an error, steps 25 through 29 are not processed and the server MUST return the error after processing steps 30 through 34.

  25. 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 three list entries, set as follows:

        • First list entry

          • operation: replace

          • modification:

            • type: DnsHostName

            • vals: ComputerNameFQDN

        • Second list entry

          • operation: add

          • modification:

            • type: msDS-AdditionalDnsHostName

            • vals: NewAlternateNames.FQDN

        • Third list entry

          • operation: delete

          • modification:

            • type: msDS-AdditionalDnsHostName

            • vals: OldAlternateNames.FQDN

      • controls: Sequence of one Control structure, as follows:

        • controlType: LDAP_SERVER_PERMISSIVE_MODIFY_OID ([MS-ADTS] section 3.1.1.3.4.1.8)

        • criticality: FALSE

    • TaskOutputResultMessages: LDAPResultMessages

      If the LDAP operation returns an error, steps 26 through 29 are not processed and the server MUST return the error after processing steps 30 through 34.

  26. If IsRODC is TRUE, 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 SearchRequest message ([RFC2251] section 4.5.1) as follows:

      • baseObject: DN of the rootDSE (empty string)

      • scope: base

      • filter: ObjectClass=*

      • attributes: dsServiceName

      • derefAliases: neverDerefAliases

      • typesOnly: FALSE

    • TaskOutputResultMessages: LDAPResultMessages

      The server MUST process the results returned from the DC in LDAPResultMessages. For the entry (SearchResultEntry, [RFC2251] section 4.5.2) returned by the search in LDAPResultMessages, WritableDomainControllerDN MUST equal the value of the attribute dsServiceName. If the LDAP operation returns an error, steps 27 through 29 are not processed and processing continues at step 30.

  27. If IsRODC is TRUE, 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 SearchRequest message ([RFC2251] section 4.5.1) as follows:

      • baseObject: ComputerAccountDN

      • scope: base

      • filter: ObjectClass=*

      • attributes: distinguishedName, serverReferenceBL

      • derefAliases: neverDerefAliases

      • typesOnly: FALSE

      • controls: Sequence of one Control structure, as follows:

        • controlType: LDAP_SERVER_EXTENDED_DN_OID

        • criticality: TRUE

    • TaskOutputResultMessages: LDAPResultMessages

      The server MUST process the results returned from the DC in LDAPResultMessages. For the entry (SearchResultEntry, [RFC2251] section 4.5.2) returned by the search in LDAPResultMessages, ComputerAccountExtendedDN MUST equal the value of the attribute distinguishedName and ServerObjectDN MUST equal the value of the attribute serverReferenceBL, except in cases where the character ';' is present in the attribute. If ';' is present in distinguishedName, ComputerAccountExtendedDN MUST equal distinguishedName truncated at the first occurrence of the character ';', exclusive of the ';' itself. If ';' is present in serverReferenceBL, ServerObjectDN MUST equal serverReferenceBL truncated at the first occurrence of the character ';', exclusive of the ';' itself. If the LDAP operation returns an error, steps 28 and 29 are not processed and processing continues at step 30.

  28. If IsRODC is TRUE, 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: ReadOnlyDomainControllerConnection

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

      • Object: DN of the rootDSE (empty string)

      • The modification sequence has one list entry, set as follows:

        • First list entry

          • operation: replace

          • modification:

            • type: replicateSingleObject ([MS-ADTS] section 3.1.1.3.3.18)

            • vals: WritableDomainControllerDN:ComputerAccountExtendedDN

    • TaskOutputResultMessages: LDAPResultMessages

      If the LDAP operation returns an error, step 29 is not processed and processing continues at step 30.

  29. If IsRODC is TRUE, 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: ReadOnlyDomainControllerConnection

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

      • Object: DN of the rootDSE (empty string)

      • The modification sequence has one list entry, set as follows:

        • First list entry

          • operation: replace

          • modification:

            • type: replicateSingleObject ([MS-ADTS] section 3.1.1.3.3.18)

            • vals: WritableDomainControllerDN:ServerObjectDN

    • TaskOutputResultMessages: LDAPResultMessages

      If the LDAP operation returns an error, processing continues as if it had succeeded.

  30. If IsRODC is TRUE, the server invokes LDAP Unbind (section 3.2.4.29.3) with ADConnectionToUnbind set to ReadOnlyDomainControllerConnection.

  31. The server invokes LDAP Unbind with ADConnectionToUnbind set to DomainControllerConnection.

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

  33. If an error occurred while processing steps 18 through 24, the server:

    • Removes NewAlternateNames from the list in alternate-computer-names persisted locally.

    • Sets ComputerNameFQDN to OldAlternateNames.FQDN.

    • Sets ComputerNameNetBIOS to OldAlternateNames.NetBIOS.

    • Appends OldAlternateNames to the list in alternate-computer-names persisted locally.

    • Stores the values ComputerName.NetBIOS, ComputerName.FQDN, and names in alternate-computer-names locally so that the set of NetBIOS and Internet host names currently assigned to this computer can be resolved on the network ([RFC1001] and [NIS]).

    • Invokes the Computer Account Update over SAMR task (section 3.2.4.29.4), specifying the following parameters:

      • DomainController = DomainControllerString

      • CurrentSamAccountName = PrimaryName

      • NewSamAccountName = ComputerNameNetBIOS

      • DomainAccount = DomainAccount

      • DomainAccountPassword = PasswordString

  34. The server MUST start the Netlogon Remote Protocol ([MS-NRPC]) if it was stopped in step 20.

If no errors occur, the server MUST return NERR_Success.