3.2.4.26 NetrAddAlternateComputerName2 (Opnum 35)

  • Article

The NetrAddAlternateComputerName method adds an alternate name for a specified server.<158>

 unsigned long NetrAddAlternateComputerName2(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string, unique] wchar_t* AlternateName,
   [in, string, unique] wchar_t* DomainAccount,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD_AES 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.

AlternateName: A pointer to a string that specifies the new alternate name to add. The name MUST be a valid DNS host name ([RFC1035]).

DomainAccount: A pointer to a string that specifies the account name in the 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. If this parameter is specified, the format MUST be one of the following:

  • <NetBIOSDomainName>\<UserName>

  • <FullyQualifiedDNSDomainName>\<UserName>

  • <UserName>@<FullyQualifiedDNSDomainName>

EncryptedPassword: An optional pointer to a JOINPR_ENCRYPTED_USER_PASSWORD_AES structure (section 2.2.5.19) 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.<159>

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

One of the function parameters is not valid.

ERROR_INVALID_NAME

0x0000007B

The file name, directory name, or volume label syntax is incorrect.

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

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, it SHOULD revert any state changes made, MUST stop message processing, and MUST return the error to the caller.<161>

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

  • NewAlternateNames: A new tuple entry for alternate-computer-names (section 3.2.1.2).

  • 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 ([MS-ADTS] section 7.3) 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.2) 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.

  • 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.<162>

  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<163> stop message processing and return ERROR_NOT_SUPPORTED if the server is a client Stock Keeping Unit (SKU). Otherwise, message processing continues.

  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.19). 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.

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

  7. The server MUST validate AlternateName. 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.

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

    • Contain a space.

    • Contain any of the following characters:

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

  9. DNS_ERROR_INVALID_NAME_CHAR MUST be returned if any condition in the preceding group is violated. Otherwise, AlternateName validation continues.

    • NewAlternateNames.FQDN MUST be equal to AlternateName.

    • NewAlternateNames.NetBIOS MUST be equal to NewAlternateNames.FQDN converted to a NetBIOS.<164>

  10. NewAlternateNames MUST be appended to the list in alternate-computer-names persisted locally such that the set of NetBIOS and Internet host name currently assigned to this computer can be resolved on the network ([RFC1001] and [NIS]). If the append is not successful, steps 11 through 21 are not processed and the server MUST return an error after processing steps 22 and 23.

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

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

    • ComputerName = NULL

    • AccountName = ComputerNameNetBIOS (section 3.2.1.5)

    • 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 13 through 21 are not processed and the server MUST return an error after processing steps 22 and 23.

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

  13. 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 14 through 21 are not processed and the server MUST return the error after processing steps 22 and 23.

  14. 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 15 through 19 are not processed and the server MUST return the error after processing steps 20 and 21.

  15. 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 16 through 21 are not processed and the server MUST return the error after processing steps 22 and 23.

  16. 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 one list entry, set as follows:

        • First list entry

          • operation: replace

          • modification:

            • type: msDS-AdditionalDnsHostName

            • vals: NewAlternateNames.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 17 through 21 are not processed and the server MUST return the error after processing steps 22 and 23.

  17. 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 is not successful, steps 18 and 19 are not processed and processing continues at step 20.

  18. 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 ([MS-ADTS] section 3.1.1.3.4.1.5)

        • 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 unless distinguishedName contains the character ';'.  If ';' is present, ComputerAccountExtendedDN MUST equal distinguishedName truncated at the first occurrence of the character ';', exclusive of the ';' itself. If the LDAP operation returns an error, step 19 is not processed and processing continues at step 20.

  19. 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, processing continues as if it had succeeded.

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

  21. If IsRODC is TRUE, the server invokes LDAP Unbind with ADConnectionToUnbind set to ReadOnlyDomainControllerConnection.

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

  23. If an error occurred while processing steps 12 through 16, the server removes NewAlternateNames from the list in alternate-computer-names persisted locally.

If no errors occur, the server MUST return NERR_Success.