3.2.4.7 NetrUseAdd (Opnum 8)

  • Article

The NetrUseAdd method establishes a connection between the workstation server and an SMB server. Workstation servers SHOULD NOT allow this method to be invoked remotely<45> and SHOULD return ERROR_CALL_NOT_IMPLEMENTED.

 unsigned long NetrUseAdd(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in] unsigned long Level,
   [in, switch_is(Level)] LPUSE_INFO InfoStruct,
   [in, out, unique] unsigned long* ErrorParameter
 );

ServerName: A WKSSVC_IMPERSONATE_HANDLE structure (section 2.2.2.2) that identifies the server (2). The client MUST map this structure to an RPC binding handle ([C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

Level: A value that specifies the information level of the data. This parameter MUST be one of the following values; otherwise, the server MUST fail the call with an ERROR_INVALID_LEVEL code.

Value

Meaning

0x00000000

The buffer is a USE_INFO_0 structure (section 2.2.5.22).

0x00000001

The buffer is a USE_INFO_1 structure (section 2.2.5.23).

0x00000002

The buffer is a USE_INFO_2 structure (section 2.2.5.24).

0x00000003

The buffer is a USE_INFO_3 structure (section 2.2.5.25).

InfoStruct: A pointer to the buffer that specifies the data. The format of this data depends on the value of the Level parameter.

ErrorParameter: A pointer to a value that receives an unsigned 32-bit integer. This parameter is meaningful only if the method returns ERROR_INVALID_PARAMETER.

Return Values: When the message processing result meets the description in the right-hand column 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_INVALID_PARAMETER

0x00000057

One of the function parameters is not valid.

ERROR_INVALID_LEVEL

0x0000007C

The information level is invalid.

ERROR_CALL_NOT_IMPLEMENTED

0x00000078

This function is not supported on this system.

The server SHOULD<46> enforce security measures to verify that the caller has the required permissions to execute this routine. If the server enforces security measures and the caller does not have the required credentials, the server SHOULD fail the call with ERROR_ACCESS_DENIED. Specifications for determining the identity of the caller for the purpose of performing an access check are in [MS-RPCE] section 3.3.3.1.3.

The Level parameter determines the type of structure that the client has used to specify details about the new connection. The value MUST be 0, 1, 2, or 3. If the Level parameter is not equal to one of the valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

  • If the Level parameter is 0x00000000, the Buffer parameter points to a USE_INFO_0 structure.

  • If the Level parameter is 0x00000001, the Buffer parameter points to a USE_INFO_1 structure.

  • If the Level parameter is 0x00000002, the Buffer parameter points to a USE_INFO_2 structure.

  • If the Level parameter is 0x00000003, the Buffer parameter points to a USE_INFO_3 structure.

The server MUST verify the InfoStruct elements as follows:

  • If ui*_remote is not a UNC path format, the server MUST fail the call with ERROR_INVALID_PARAMETER. If ui*_remote is a UNC path format, it MUST canonicalize the ui*_remote path ([MS-SRVS] section 3.1.4.33).

  • If ui*_local is not NULL, the server MUST canonicalize ui*_local and verify the device name format based on ui*_asg_type.

    • If ui*_asg_type is USE_WILDCARD or USE_IPC, the server MUST fail the call with ERROR_INVALID_PARAMETER.

    • If ui*_asg_type is USE_DISKDEV, ui*_local MUST be in the form "<drive name>:". Otherwise, the server MUST fail the call with ERROR_INVALID_PARAMETER.

    • If ui*_asg_type is USE_SPOOLDEV, ui*_local MUST be in the form "LPTn:" or "PRN:". Otherwise, the server MUST fail the call with ERROR_INVALID_PARAMETER.

    • If ui*_asg_type is USE_CHARDEV, ui*_local MUST be in the form "COMn:" or "AUX:". Otherwise, the server MUST fail the call with ERROR_INVALID_PARAMETER.

  • If the Level parameter value is greater than or equal to 2 and ui*_username, ui*_password, and ui*_domainname are NULL, the server MUST attempt to establish a null session ([MS-CIFS] section 3.2.4.2.4). If the Level parameter value is greater than or equal to 2 and ui*_username, ui*_password, and ui*_domainname are not NULL, the server MUST canonicalize the user name, password, and domain name ([MS-SRVS] section 3.1.4.33).

  • If the length of ui*_password is greater than 65, the server MUST fail the call with ERROR_INVALID_PARAMETER.

The server MUST ensure that the remaining steps are executed atomically with respect to other callers performing queries or updates to the UseTable and Connection tables.

If IsWorkstationPaused is TRUE, the server MUST verify the format of ui*_local. If ui*_local is prefixed with "PRN" or "COM", the server MUST fail the call with an ERROR_REDIR_PAUSED error code. Otherwise, the server MUST invoke the events specified in [MS-CIFS] section 3.4.4.10, passing the following as the parameters: name of the server in the ui*_remote field, name of the share in ui*_remote, and user credentials associated with ui*_username constructed from ui*_username, ui*_domainname, and ui*_password.

If the CIFS server returns STATUS_SUCCESS, the server MUST verify the remote resource type and local device type.

If the CIFS server returns the remote resource type "unknown" and ui*_remote is in the form "\\server\IPC$" or "\\server\pipe", the server MUST treat the remote resource type as a "named pipe". If the CIFS server returns the remote resource type "unknown" and ui*_remote is NOT of the form "\\server\IPC$" or "\\server\pipe", the server MUST treat the remote resource type as a "disk share".

If the remote resource type does not match a local device type, the server MUST fail the call with ERROR_INVALID_PARAMETER. If the remote resource type matches a local device type, the server MUST initialize a new connection and add it to the Connection table. The connection MUST be initialized as follows:

  • Connection.local is set to the canonicalized ui*_local name.

  • Connection.remote is set to the canonicalized ui*_remote path name.

  • Connection.status is set to the caller-supplied ui*_status.

  • Connection.asgtype is set to the caller-supplied ui*_asg_type.

  • Connection.refcount is set to the caller-supplied ui*_refcount.

  • Connection.username is set to ui*_username.

  • Connection.usecount is set to ui*_usecount.

  • Connection.domain is set to ui*_domainname.

  • Connection.context is set to the ClientGenericContext structure returned by the CIFS server ([MS-CIFS] section 3.4.4.10).

The server MUST invoke the event to impersonate the client ([MS-RPCE] section 3.3.3.4.3.1), passing NULL as input parameter. If this event fails, the server MUST return an error. If the event returns UserToken, the server MUST look in UseTable for an entry where UserToken matches UseEntry.UserToken. If no entry is found, the server MUST create a new entry in UseTable and insert a new connection entry in UseEntry.ConnectionTable. The server MUST invoke the event to end the client impersonation ([MS-RPCE] section 3.3.3.4.3.3) and return NERR_Success to the caller.

If the CIFS server returns a failure, the server MUST invoke the event to end the client impersonation ([MS-RPCE] section 3.3.3.4.3.3) and fail the call with the status code received from the event.