Share via

3.2.4.25 NetrValidateName3 (Opnum 34)

  • Article

The NetrValidateName3 method verifies the validity of a computer, workgroup, or domain name.<151>

 unsigned long NetrValidateName3(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string] wchar_t* NameToValidate,
   [in, string, unique] wchar_t* AccountName,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD_AES Password,
   [in] NETSETUP_NAME_TYPE NameType
 );

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

NameToValidate: A pointer to a string that specifies the name to validate, according to its type.

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_AES structure (section 2.2.5.19) that specifies the encrypted password to use with the AccountName parameter. If this parameter is NULL, the caller's security context MUST be used.

NameType: Specifies the type of validation to perform (section 2.2.3.2).

Return Values: When the message processing result matches the description in column 2 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_DUP_NAME

0x00000034

The connection was denied because a duplicate name exists on the network.

ERROR_INVALID_PASSWORD

0x00000056

The specified network password is incorrect.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect.

ERROR_INVALID_NAME

0x0000007B

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

ERROR_INVALID_DOMAINNAME

0x000004BC

The format of the specified domain name is invalid.

ERROR_NO_SUCH_DOMAIN

0x0000054B

The specified domain either does not exist or could not be contacted.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

NERR_InvalidComputer

0x0000092F

This computer name is invalid.

NERR_InvalidWorkgroupName

0x00000A87

The specified workgroup name is invalid.

DNS_ERROR_NON_RFC_NAME

0x00002554

The Internet host name does not comply with RFC specifications.

DNS_ERROR_INVALID_NAME_CHAR

0x00002558

The Internet host name contains an invalid character.

RPC_E_REMOTE_DISABLED

0x8001011C

Remote calls are not allowed for this process.

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

The following definition is used in the specification of message processing that follows.

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

  2. The server SHOULD<153> stop message processing and return an implementation-specific error if the caller is not local. Specifications for determining if the caller is local are in [MS-RPCE].

  3. 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_QUERY; if not, the server MUST return ERROR_ACCESS_DENIED.

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

  5. If Password is NULL then PasswordString MUST be NULL. Otherwise, the server MUST decrypt and decode the Password (section 2.2.5.19). 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. If NameType is NetSetupUnknown the server MUST stop message processing and return ERROR_INVALID_PARAMETER.

  7. First, the method MUST perform syntactic validation of the name as follows. For all types of validation except the NetSetupDnsMachine type, the syntactic validation is performed on the name expressed in the OEM character set.

    NetSetupWorkgroup

    • The length of the name MUST NOT be less than 1 or greater than 15 characters, inclusive.

    • The name MUST NOT contain characters that have any one of the following octal values:

       001, 002, 003, 004, 005, 006, 007, 010, 011, 012, 013, 014, 
 015, 016, 017, 020, 021, 022, 023, 024, 025, 026, 027, 030, 
 031, 032, 033, 034, 035, 036, 037

    • The name MUST NOT contain any of the following characters:

       " / \ [ ] : | < > + = ; , ?

    • The name MUST NOT consist entirely of the dot and space characters.

    NERR_InvalidWorkgroupName MUST be returned if the check fails unless the conditions of this type are being checked as part of another type, which specifies alternate error return behavior.

    NetSetupMachine

    All conditions for the NetSetupWorkgroup type apply for this type. Additionally:

    • The name MUST NOT contain an asterisk (*).

    • The first character and the last character of the name MUST NOT be the space character.

      NERR_InvalidComputer MUST be returned if the check fails.

      NetSetupDomain

    • The name MUST NOT consist entirely of the dot and space characters.

      ERROR_INVALID_NAME MUST be returned if this condition is violated.

      All conditions for the NetSetupWorkgroup type apply for this type. If the checks for NetSetupWorkgroup fail, all conditions for the NetSetupDnsMachine apply for this type.

      NetSetupNonExistentDomain

      All conditions for the NetSetupDomain type apply for this type. Additionally:

    • The name MUST contain only characters ([RFC1035]).

      DNS_ERROR_NON_RFC_NAME MUST be returned if this restriction is violated.

      NetSetupDnsMachine

      The validation ([RFC1035]) is performed in the following order. Specifically, the name MUST NOT:

    • Contain characters that have any one of the following octal values:

       001, 002, 003, 004, 005, 006, 007, 010, 011, 012, 013, 014,
 015, 016, 017, 020, 021, 022, 023, 024, 025, 026, 027, 030,
 031, 032, 033, 034, 035, 036, 037
 

    • Be longer than 255 octets.

    • Contain a label longer than 63 octets.

    • Contain two or more consecutive dots.

    • Begin with a dot.

      ERROR_INVALID_NAME MUST be returned if any condition in this group is violated.

    • Contain a space.

    • Contain any of the following characters:

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

      DNS_ERROR_INVALID_NAME_CHAR MUST be returned if any condition in this group is violated.

  8. Second, after validating the name syntactically, the method MUST perform the following verification for the respective types of validation:

    NetSetupWorkgroup

    • The name MUST NOT be the name of the server receiving this call. NERR_InvalidWorkgroupName MUST be returned if this condition is violated.

    • The name MUST be valid for registration as a NetBIOS group name ([RFC1001]).<154> If the name is not valid then ERROR_INVALID_PARAMETER MUST be returned.

      NetSetupMachine

    • The name MUST be valid for registration as a NetBIOS unique name ([RFC1001]). Otherwise, the server MUST return NERR_InvalidComputer.

    • The name MUST NOT be in use by a computer accessible on the network except for the server receiving this call. ERROR_DUP_NAME MUST be returned if this condition is violated.<155>

      NetSetupDomain

    • The name MUST differ from the name of the built-in domain, "BUILTIN" (Builtin Domain Principal View, [MS-LSAT] section 3.1.1.1.3); the comparison MUST be case-insensitive. NERR_InvalidComputer MUST be returned if this condition is violated.

    • The name MUST be a name of an existing domain. ERROR_NO_SUCH_DOMAIN MUST be returned if this condition is not satisfied.<156>

      NetSetupNonExistentDomain

    • The name MUST differ from the name of the built-in domain, "BUILTIN" (Builtin Domain Principal View); the comparison MUST be case-insensitive. NERR_InvalidComputer MUST be returned if this condition is violated.

    • The name MUST NOT be a name of an existing domain accessible on the network. ERROR_DUP_NAME MUST be returned if this condition is not satisfied.<157>

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