3.3.5.59.1 Receiving an NT_TRANSACT_CREATE Request

  • Article

This subcommand can be used by the client to create a new file, to open or truncate an existing file, or to create a directory. The semantics of this subcommand are similar to those of the SMB_COM_NT_CREATE_ANDX (section 2.2.4.64) SMB command, with the exception that NT_TRANSACT_CREATE (section 2.2.7.1) can be used to set security descriptors and/or extended attribute name/value pairs on the file.

If the MaxParameterCount field of the SMB_COM_NT_TRANSACT request contains a value that is less than the size of the NT_TRANSACT_CREATE Response as specified in section 2.2.7.1.2, the server MUST fail the request with STATUS_INVALID_SMB (ERRSRV/ERRerror).

Upon receipt of an NT_TRANSACT_CREATE subcommand request, the NT Trans subsystem MUST determine the pathname of the file or directory to open or create. This involves the interaction of three fields:

  • If the RootDirectoryFID is nonzero, it represents a directory within the share represented by the TID specified in the SMB Header (section 2.2.3.1). The Name MUST be evaluated relative to the directory specified by RootDirectoryFID.

  • If the RootDirectoryFID is zero, then the Name MUST be evaluated relative to the root of the share specified by the TID.

If Server.EnableOplock is TRUE, the Flags field in the subcommand request allows the client to ask for an exclusive or batch OpLock. The level of OpLock granted (if any) MUST be returned in the OpLockLevel field in the subcommand response. The Flags field also allows the user to request opening a directory. If the object opened is a directory, the Directory field of the response MUST be nonzero; a zero value (FALSE) indicates that the object is not a directory.

The DesiredAccess field is used to indicate the access modes that the client requests. If DesiredAccess is not granted in Share.FileSecurity for the user indicated by the UID, the server MUST fail the request with STATUS_ACCESS_DENIED. If the user's security context that is indicated by the UID does not have the appropriate privileges, the server SHOULD fail the request with STATUS_PRIVILEGE_NOT_HELD or STATUS_ACCESS_DENIED (ERRDOS/ERRnoaccess).<347> If no access is granted for the client on this file, the server MUST increase Server.Statistics.sts0_permerrors by 1 and MUST fail the open with STATUS_ACCESS_DENIED (ERRDOS/ERRnoaccess).

If the object is a regular file and it is being created or overwritten, the AllocationSize indicates the number of bytes to pre-allocate.

ShareAccess provides the set of sharing modes that the client requests. If any of these sharing modes is unavailable, the server MUST fail the open with STATUS_SHARING_VIOLATION (ERRDOS/ERRbadshare).

The CreateDisposition field is used to determine the action the server attempts if the object already exists:

  • FILE_SUPERSEDE, FILE_OVERWRITE, FILE_OVERWRITE_IF: Overwrite the file.

  • FILE_OPEN, FILE_OPEN_IF: Open the existing file or directory.

  • FILE_CREATE: Fail with STATUS_OBJECT_NAME_COLLISION (ERRDOS/ERRfilexists).

The CreateDisposition field is used to determine the action that the server attempts if the object does not already exist:

  • FILE_SUPERSEDE, FILE_CREATE, FILE_OPEN_IF, FILE_OVERWRITE_IF: Create the file or directory.

  • FILE_OPEN, FILE_OVERWRITE: Fail.

CreateOptions specifies the options that are to be used by the server when it attempts to open or create the object. If the object is being created, ExtFileAttributes represents a set of requested attributes to be assigned to the object. The set of attributes actually assigned is returned to the client in the ExtFileAttributes field of the response.

The server MUST include FILE_READ_ATTRIBUTES in the DesiredAccess field of the request.

If the open or create is successful, the server MUST apply the SecurityDescriptor provided in the NT_Trans_Data buffer of the NT_TRANSACT_CREATE Request (section 2.2.7.1.1). Likewise, the server MUST apply the set of Extended Attribute (EA) name/value pairs provided in the request. If an error is detected while applying the EAs, the server MUST return a complete NT_TRANSACT_CREATE Response (section 2.2.7.1.2) (not an SMB error response) and MUST set the Status field in the SMB Header with the implementation-specific error code.

Once the file has been successfully opened, and the SecurityDescriptor and EAs applied, the server MUST collect additional file attribute information, including:

  • The type of the object that has been opened.

  • The creation, last write, last change, and last access times of the object.

  • The file size and file allocation size, if the object is a file.

  • The named pipe state, if the object is a named pipe.

If the NT_TRANSACT_CREATE is successful, this information, along with the FID that is generated by the command, MUST be placed into an NT_TRANSACT_CREATE Response (section 2.2.7.1.2) subcommand message. A new Server.Open object with the PID, UID, TID from the request header, and the new FID MUST be entered into the Server.Connection.FileOpenTable, and Server.Statistics.sts0_fopens MUST be increased by 1. Server.Open.TreeConnect MUST be set to the TreeConnect on which the request was performed, and Server.Open.TreeConnect.OpenCount MUST be increased by 1. Server.Open.Session MUST be set to Server.Open.TreeConnect.Session. Server.Open.Connection MUST be set to the Server.Open.Session.Connection. Server.Open.Locks MUST be set to an empty list. Server.Open.PathName MUST be set to the Name field of the request. Server.Open.GrantedAccess MUST be set to the DesiredAccess field of the request.

The server MUST register the new FID by invoking the event Server Registers a New Open ([MS-SRVS] section 3.1.6.4) and MUST assign the return value to FileGlobalId.

If an error is generated, other than an Extended Attribute error as specified preceding, an error response MUST be generated. The NT Trans subsystem MUST return the NT transaction response to the CIFS server for transmission to the client.<348>