3.3.5.7 Receiving an SMB2 TREE_CONNECT Request
When the server receives a request with an SMB2 header with a Command value equal to SMB2 TREE_CONNECT, message handling proceeds as follows:
The server MUST locate the authenticated session, as specified in section 3.3.5.2.9.
If Connection.Dialect is "3.1.1" and Session.IsAnonymous and Session.IsGuest are set to FALSE and the request is not signed or not encrypted, then the server MUST disconnect the connection.
The server MUST parse the Unicode string in the Buffer field, specified by PathOffset and PathLength fields, to extract the hostname and sharename components, as specified in [MS-DTYP] section 2.2.49. If the Buffer field is not in the format specified in section 2.2.9, the server MUST fail the request with STATUS_INVALID_PARAMETER. Otherwise, the server MUST provide the tuple <hostname, sharename> parsed from the request message to invoke the event specified in [MS-SRVS] section 3.1.6.8, to normalize the hostname by resolving server aliases and evaluating share scope. The server MUST use <normalized hostname, sharename> to look up the Share in ShareList. If no share with a matching share name and server name is found, the server MUST fail the request with STATUS_BAD_NETWORK_NAME. If a share is found, the server MUST do the following:
If Share.Type is STYPE_CLUSTER_FS, STYPE_CLUSTER_SOFS, or STYPE_CLUSTER_DFS as specified in [MS-SRVS] section 2.2.2.4 and Connection.Dialect is greater than MaxClusterDialect and SMB2_TREE_CONNECT_FLAG_CLUSTER_RECONNECT is not set in Flags/Reserved field, the server MUST fail the request with STATUS_SMB_BAD_CLUSTER_DIALECT (0xC05D0001) and if Connection.Dialect is SMB 3.1.1, the server MUST return error data as specified in section 2.2.2 with ByteCount set to 10, ErrorContextCount set to 1, and ErrorData set to SMB2 ERROR Context response formatted as ErrorDataLength set to 2, ErrorId set to 0, and ErrorData set to MaxClusterDialect; otherwise, the server MUST return error data as specified in section 2.2.2 with ByteCount set to 2 and ErrorContextData set to MaxClusterDialect.
If the server implements the SMB 3.x dialect family, EncryptData or Share.EncryptData is TRUE, RejectUnencryptedAccess is TRUE, and Connection.ServerCapabilities does not include SMB2_GLOBAL_CAP_ENCRYPTION, the server MUST fail the request with STATUS_ACCESS_DENIED.
If Connection.Dialect belongs to the SMB 3.x dialect family, Share.EncryptData is TRUE, RejectUnencryptedAccess is TRUE, and Connection.ClientCapabilities does not include the SMB2_GLOBAL_CAP_ENCRYPTION bit, the server MUST fail the request with STATUS_ACCESS_DENIED.
The server MUST determine whether the user represented by Session.SecurityContext is granted access based on the authorization policy specified in Share.ConnectSecurity. If the server determines that it does not grant access, the server MUST fail the request with STATUS_ACCESS_DENIED.
The server MUST provide the tuple <hostname, sharename> to invoke the event specified in [MS-SRVS] section 3.1.6.15 to get the total number of current uses of the share. If the total number of current uses is equal to or greater than Share.MaxUses, the server MUST fail the request with STATUS_REQUEST_NOT_ACCEPTED.
If TreeConnect.Share.Type is STYPE_CLUSTER_SOFS as specified in [MS-SRVS] section 2.2.2.4, Connection.Dialect is "3.1.1" and the SMB2_TREE_CONNECT_FLAG_REDIRECT_TO_OWNER bit is set in the Flags field of the SMB2 TREE_CONNECT request, the server MUST query the underlying object store in an implementation-specific manner to determine whether the share is hosted on this node. If not, the server MUST fail the tree connect request by setting the Status field in SMB2 header to STATUS_BAD_NETWORK_NAME, return error data as specified in section 2.2.2 with ErrorData set to SMB2 ERROR Context response formatted as ErrorId set to SMB2_ERROR_ID_SHARE_REDIRECT, and ErrorContextData set to the Share Redirect error context data as specified in section 2.2.2.2.2 with IPAddrMoveList set to the list of IP addresses determined for where to access the share.
If Connection.Dialect is "3.1.1", Server.SupportsTreeConnectExtn is TRUE, and the SMB2_TREE_CONNECT_FLAG_EXTENSION_PRESENT bit is set in the Flags field of the SMB2 TREE_CONNECT request, the server MUST process the SMB2 tree connect contexts described in section 2.2.9.1. If an SMB2_REMOTED_IDENTITY_TREE_CONNECT context is present and Share.SupportsIdentityRemoting is set, the server MUST perform the following:
If the TicketType is not 0x0001, ignore the context and continue tree connect processing.
Otherwise, the server MUST obtain User, UserName, Domain, Groups, RestrictedGroups, Privileges, PrimaryGroup, Owner, DefaultDacl, DeviceGroups, UserClaims, and DeviceClaims from the SMB2_REMOTED_IDENTITY_TREE_CONNECT context, and use them to impersonate the remoted identity as specified in [MS-DTYP] section 2.7.1. If successful, set TreeConnect.RemotedIdentitySecurityContext to the impersonated security context.
The server MUST allocate a tree connect object and insert it into Session.TreeConnectTable. The server MUST provide the tuple <hostname, sharename> and MUST register TreeConnect by invoking the event specified in [MS-SRVS] section 3.1.6.6 and assign the return value to TreeConnect.TreeGlobalId. The other initial values MUST be set as follows:
TreeConnect.TreeId MUST be set to a value generated to uniquely identify this tree connect in the Session.TreeConnectTable. The SMB2 server MUST reserve -1 for invalid TreeId.
TreeConnect.Session MUST be set to the session found on the SessionId lookup.
TreeConnect.Share MUST be set to the share found on the lookup.
TreeConnect.OpenCount MUST be set to 0.
TreeConnect.CreationTime MUST be set to current time.
TreeConnect.Share.CurrentUses MUST be increased by 1.
The SMB2 TREE_CONNECT response MUST be constructed following the syntax specified in section 2.2.10, as described here:
ShareFlags MUST be set based on the individual share properties (Share.CscFlags, Share.DoAccessBasedDirectoryEnumeration, Share.AllowNamespaceCaching, Share.ForceSharedDelete, Share.RestrictExclusiveOpens, Share.HashEnabled, Share.ForceLevel2Oplock, Share.IsDfs, Share.EncryptData.)
The server MUST set all flags contained in Share.CscFlags.
The server SHOULD<295> set the SMB2_SHAREFLAG_DFS bit if the per-share property Share.IsDfs is TRUE, indicating that the share is part of a DFS namespace.
The server SHOULD<296> set the SMB2_SHAREFLAG_DFS_ROOT bit if the per-share property Share.IsDfs is TRUE, indicating that the share is part of a DFS namespace.
The server MUST set the SMB2_SHAREFLAG_ACCESS_BASED_DIRECTORY_ENUM bit if Share.DoAccessBasedDirectoryEnumeration is TRUE and ServerHashLevel is not HashDisableAll.
The server MUST set the SMB2_SHAREFLAG_ALLOW_NAMESPACE_CACHING bit if Share.AllowNamespaceCaching is TRUE.
The server MUST set the SMB2_SHAREFLAG_FORCE_SHARED_DELETE bit if Share.ForceSharedDelete is TRUE.
The server MUST set the SMB2_SHAREFLAG_RESTRICT_EXCLUSIVE_OPENS bit if Share.RestrictExclusiveOpens is TRUE.
If Connection.Dialect belongs to the SMB 3.x dialect family, and Share.EncryptData is TRUE, the server MUST do the following:
Set the SMB2_SHAREFLAG_ENCRYPT_DATA bit.
If Share.HashEnabled is TRUE and ServerHashLevel is not HashDisableAll.
The server MUST set the SMB2_SHAREFLAG_FORCE_LEVELII_OPLOCK bit if Share.ForceLevel2Oplock is TRUE.
ShareType MUST be set based on the resource being shared, as indicated by Share.Type:
If this share provides access to named pipes, as indicated by resource type STYPE_IPC as specified in [MS-SRVS] section 2.2.2.4, ShareType MUST be set to SMB2_SHARE_TYPE_PIPE.
If this share provides access to a printer, as indicated by the resource type STYPE_PRINTQ as specified in [MS-SRVS] section 2.2.2.4, ShareType MUST be set to SMB2_SHARE_TYPE_PRINT.
Otherwise, ShareType MUST be set to SMB2_SHARE_TYPE_DISK.
If Share.IsDfs is TRUE, the server MUST set the SMB2_SHARE_CAP_DFS bit in the Capabilities field.
If Connection.Dialect belongs to the SMB 3.x dialect family and Share.IsCA is TRUE, the server MUST set the SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY bit in the Capabilities field.
If Connection.Dialect belongs to the SMB 3.x dialect family and TreeConnect.Share.Type is STYPE_CLUSTER_SOFS as specified in [MS-SRVS] section 2.2.2.4, the server MUST set the SMB2_SHARE_CAP_SCALEOUT bit in the Capabilities field.
If Connection.Dialect belongs to the SMB 3.x dialect family and TreeConnect.Share.Type is STYPE_CLUSTER_FS, STYPE_CLUSTER_SOFS, or STYPE_CLUSTER_DFS as specified in [MS-SRVS] section 2.2.2.4, the server MUST set the SMB2_SHARE_CAP_CLUSTER bit in the Capabilities field.
If Connection.Dialect is "3.0.2" or "3.1.1", TreeConnect.Share.Type is STYPE_CLUSTER_SOFS as specified in [MS-SRVS] section 2.2.2.4, and TreeConnect.Share is asymmetric, the server MUST set the SMB2_SHARE_CAP_ASYMMETRIC bit in the Capabilities field.
If Connection.Dialect is "3.1.1" and TreeConnect.Share.SupportsIdentityRemoting is set, the server MUST set the SMB2_SHAREFLAG_IDENTITY_REMOTING bit in the ShareFlags field of the SMB2 TREE_CONNECT response.
If Connection.Dialect is "3.1.1", TreeConnect.Share.Type is STYPE_CLUSTER_SOFS as specified in [MS-SRVS] section 2.2.2.4, and the SMB2_TREE_CONNECT_FLAG_REDIRECT_TO_OWNER bit is set in the Flags field of the SMB2 TREE_CONNECT request and the SMB2_SHARE_CAP_ASYMMETRIC bit is set in the Capabilities field, the server SHOULD<299> set the SMB2_SHARE_CAP_REDIRECT_TO_OWNER bit in the Capabilities field.
MaximalAccess MUST be set to the highest access the user described by Session.SecurityContext would have when accessing resources underneath the security descriptor Share.FileSecurity. The server MUST set TreeConnect.MaximalAccess to MaximalAccess.
The response MUST then be sent to the client.
The status code returned by this operation MUST be one of those defined in [MS-ERREF]. Common status codes returned by this operation include:
STATUS_SUCCESS
STATUS_ACCESS_DENIED
STATUS_INSUFFICIENT_RESOURCES
STATUS_BAD_NETWORK_NAME
STATUS_INVALID_PARAMETER
STATUS_USER_SESSION_DELETED
STATUS_NETWORK_SESSION_EXPIRED
STATUS_SERVER_UNAVAILABLE