2.2.13 SMB2 CREATE Request

The SMB2 CREATE Request packet is sent by a client to request either creation of or access to a file. In case of a named pipe or printer, the server MUST create a new file.

This request is composed of an SMB2 Packet Header, as specified in section 2.2.1, that is followed by this request structure.


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

StructureSize

SecurityFlags

RequestedOplockLevel

ImpersonationLevel

SmbCreateFlags

...

Reserved

...

DesiredAccess

FileAttributes

ShareAccess

CreateDisposition

CreateOptions

NameOffset

NameLength

CreateContextsOffset

CreateContextsLength

Buffer (variable)

...

StructureSize (2 bytes): The client MUST set this field to 57, indicating the size of the request structure, not including the header. The client MUST set it to this value regardless of how long Buffer[] actually is in the request being sent.

SecurityFlags (1 byte): This field MUST NOT be used and MUST be reserved. The client MUST set this to 0, and the server MUST ignore it.

RequestedOplockLevel (1 byte): The requested oplock level. This field MUST contain one of the following values.<28> For named pipes, the server MUST always revert to SMB2_OPLOCK_LEVEL_NONE irrespective of the value of this field.

Value

Meaning

SMB2_OPLOCK_LEVEL_NONE

0x00

No oplock is requested.

SMB2_OPLOCK_LEVEL_II

0x01

A level II oplock is requested.

SMB2_OPLOCK_LEVEL_EXCLUSIVE

0x08

An exclusive oplock is requested.

SMB2_OPLOCK_LEVEL_BATCH

0x09

A batch oplock is requested.

SMB2_OPLOCK_LEVEL_LEASE

0xFF

A lease is requested. If set, the request packet MUST contain an SMB2_CREATE_REQUEST_LEASE (section 2.2.13.2.8) create context. This value is not valid for the SMB 2.0.2 dialect.

ImpersonationLevel (4 bytes): This field specifies the impersonation level requested by the application that is issuing the create request, and MUST contain one of the following values. The server MUST validate this field, but otherwise ignore it.

Value

Meaning

Anonymous

0x00000000

The application-requested impersonation level is Anonymous.

Identification

0x00000001

The application-requested impersonation level is Identification.

Impersonation

0x00000002

 The application-requested impersonation level is Impersonation.

Delegate

0x00000003

The application-requested impersonation level is Delegate.

Impersonation is specified in [MS-WPO] section 9.7; for more information about impersonation, see [MSDN-IMPERS].

SmbCreateFlags (8 bytes): This field MUST NOT be used and MUST be reserved. The client SHOULD set this field to zero, and the server MUST ignore it on receipt.

Reserved (8 bytes): This field MUST NOT be used and MUST be reserved. The client sets this to any value, and the server MUST ignore it on receipt.

DesiredAccess (4 bytes): The level of access that is required, as specified in section 2.2.13.1.

FileAttributes (4 bytes): This field MUST be a combination of the values specified in [MS-FSCC] section 2.6, and MUST NOT include any values other than those specified in that section.

ShareAccess (4 bytes): Specifies the sharing mode for the open. If ShareAccess values of FILE_SHARE_READ, FILE_SHARE_WRITE and FILE_SHARE_DELETE are set for a printer file or a named pipe, the server SHOULD<29> ignore these values. The field MUST be constructed using a combination of zero or more of the following bit values.

Value

Meaning

FILE_SHARE_READ

0x00000001

 When set, indicates that other opens are allowed to read this file while this open is present. This bit MUST NOT be set for a named pipe or a printer file. Each open creates a new instance of a named pipe. Likewise, opening a printer file always creates a new file.

FILE_SHARE_WRITE

0x00000002

 When set, indicates that other opens are allowed to write this file while this open is present. This bit MUST NOT be set for a named pipe or a printer file. Each open creates a new instance of a named pipe. Likewise, opening a printer file always creates a new file.

FILE_SHARE_DELETE

0x00000004

When set, indicates that other opens are allowed to delete or rename this file while this open is present. This bit MUST NOT be set for a named pipe or a printer file. Each open creates a new instance of a named pipe. Likewise, opening a printer file always creates a new file.

CreateDisposition (4 bytes): Defines the action the server MUST take if the file that is specified in the name field already exists. For opening named pipes, this field can be set to any value by the client and MUST be ignored by the server. For other files, this field MUST contain one of the following values.

Value

Meaning

FILE_SUPERSEDE

0x00000000

If the file already exists, supersede it. Otherwise, create the file. This value SHOULD NOT be used for a printer object.<30>

FILE_OPEN

0x00000001

If the file already exists, return success; otherwise, fail the operation. MUST NOT be used for a printer object.

FILE_CREATE

0x00000002

If the file already exists, fail the operation; otherwise, create the file.

FILE_OPEN_IF

0x00000003

Open the file if it already exists; otherwise, create the file. This value SHOULD NOT be used for a printer object.<31>

FILE_OVERWRITE

0x00000004

Overwrite the file if it already exists; otherwise, fail the operation. MUST NOT be used for a printer object.

FILE_OVERWRITE_IF

0x00000005

Overwrite the file if it already exists; otherwise, create the file. This value SHOULD NOT be used for a printer object.<32>

CreateOptions (4 bytes): Specifies the options to be applied when creating or opening the file. Combinations of the bit positions listed below are valid, unless otherwise noted. This field MUST be constructed using the following values.<33>

Value

Meaning

FILE_DIRECTORY_FILE

0x00000001

The file being created or opened is a directory file. With this flag, the CreateDisposition field MUST be set to FILE_CREATE, FILE_OPEN_IF, or FILE_OPEN. With this flag, only the following CreateOptions values are valid: FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, FILE_DELETE_ON_CLOSE, and FILE_OPEN_REPARSE_POINT. If the file being created or opened already exists and is not a directory file and FILE_CREATE is specified in the CreateDisposition field, then the server MUST fail the request with STATUS_OBJECT_NAME_COLLISION. If the file being created or opened already exists and is not a directory file and FILE_CREATE is not specified in the CreateDisposition field, then the server MUST fail the request with STATUS_NOT_A_DIRECTORY. The server MUST fail an invalid CreateDisposition field or an invalid combination of CreateOptions flags with STATUS_INVALID_PARAMETER.

FILE_WRITE_THROUGH

0x00000002

The server MUST propagate writes to this open to persistent storage before returning success to the client on write operations.

FILE_SEQUENTIAL_ONLY

0x00000004

This indicates that the application intends to read or write at sequential offsets using this handle, so the server SHOULD optimize for sequential access. However, the server MUST accept any access pattern. This flag value is incompatible with the FILE_RANDOM_ACCESS value.

FILE_NO_INTERMEDIATE_BUFFERING

0x00000008

The server or underlying object store SHOULD NOT cache data at intermediate layers and SHOULD allow it to flow through to persistent storage.

FILE_SYNCHRONOUS_IO_ALERT

0x00000010

This bit SHOULD be set to 0 and MUST be ignored by the server.<34>

FILE_SYNCHRONOUS_IO_NONALERT

0x00000020

This bit SHOULD be set to 0 and MUST be ignored by the server.<35>

FILE_NON_DIRECTORY_FILE

0x00000040

If the name of the file being created or opened matches with an existing directory file, the server MUST fail the request with STATUS_FILE_IS_A_DIRECTORY. This flag MUST NOT be used with FILE_DIRECTORY_FILE or the server MUST fail the request with STATUS_INVALID_PARAMETER.

FILE_COMPLETE_IF_OPLOCKED

0x00000100

This bit SHOULD be set to 0 and MUST be ignored by the server.<36>

FILE_NO_EA_KNOWLEDGE

0x00000200

The caller does not understand how to handle extended attributes. If the request includes an SMB2_CREATE_EA_BUFFER create context, then the server MUST fail this request with STATUS_ACCESS_DENIED. If extended attributes with the FILE_NEED_EA flag (see [MS-FSCC] section 2.4.15) set are associated with the file being opened, then the server MUST fail this request with STATUS_ACCESS_DENIED.

FILE_RANDOM_ACCESS

0x00000800

This indicates that the application intends to read or write at random offsets using this handle, so the server SHOULD optimize for random access. However, the server MUST accept any access pattern. This flag value is incompatible with the FILE_SEQUENTIAL_ONLY value. If both FILE_RANDOM_ACCESS and FILE_SEQUENTIAL_ONLY are set, then FILE_SEQUENTIAL_ONLY is ignored.

FILE_DELETE_ON_CLOSE

0x00001000

The file MUST be automatically deleted when the last open request on this file is closed. When this option is set, the DesiredAccess field MUST include the DELETE flag. This option is often used for temporary files.

FILE_OPEN_BY_FILE_ID

0x00002000

This bit SHOULD be set to 0 and the server MUST fail the request with a STATUS_NOT_SUPPORTED error if this bit is set.<37>

FILE_OPEN_FOR_BACKUP_INTENT

0x00004000

The file is being opened for backup intent. That is, it is being opened or created for the purposes of either a backup or a restore operation. The server can check to ensure that the caller is capable of overriding whatever security checks have been placed on the file to allow a backup or restore operation to occur. The server can check for access rights to the file before checking the DesiredAccess field.

FILE_NO_COMPRESSION

0x00008000

The file cannot be compressed. This bit is ignored when FILE_DIRECTORY_FILE is set in CreateOptions.

FILE_OPEN_REMOTE_INSTANCE

0x00000400

This bit SHOULD be set to 0 and MUST be ignored by the server.

FILE_OPEN_REQUIRING_OPLOCK

0x00010000

This bit SHOULD be set to 0 and MUST be ignored by the server.

FILE_DISALLOW_EXCLUSIVE

0x00020000

This bit SHOULD be set to 0 and MUST be ignored by the server.

FILE_RESERVE_OPFILTER

0x00100000

This bit SHOULD be set to 0 and the server MUST fail the request with a STATUS_NOT_SUPPORTED error if this bit is set.<38>

FILE_OPEN_REPARSE_POINT

0x00200000

If the file or directory being opened is a reparse point, open the reparse point itself rather than the target that the reparse point references.

FILE_OPEN_NO_RECALL

0x00400000

In an HSM (Hierarchical Storage Management) environment, this flag means the file SHOULD NOT be recalled from tertiary storage such as tape. The recall can take several minutes. The caller can specify this flag to avoid those delays.

FILE_OPEN_FOR_FREE_SPACE_QUERY

0x00800000

Open file to query for free space. The client SHOULD set this to 0 and the server MUST ignore it.<39>

NameOffset (2 bytes): The offset, in bytes, from the beginning of the SMB2 header to the 8-byte aligned file name. If SMB2_FLAGS_DFS_OPERATIONS is set in the Flags field of the SMB2 header, the file name includes a prefix that will be processed during DFS name normalization as specified in section 3.3.5.9. Otherwise, the file name is relative to the share that is identified by the TreeId in the SMB2 header. The NameOffset field SHOULD be set to the offset of the Buffer field from the beginning of the SMB2 header. The file name (after DFS normalization if needed) MUST conform to the specification of a relative pathname in [MS-FSCC] section 2.1.5. A zero length file name indicates a request to open the root of the share.

NameLength (2 bytes): The length of the file name, in bytes. If no file name is provided, this field MUST be set to 0.

CreateContextsOffset (4 bytes): The offset, in bytes, from the beginning of the SMB2 header to the first 8-byte aligned SMB2_CREATE_CONTEXT structure in the request. If no SMB2_CREATE_CONTEXTs are being sent, this value MUST be 0.

CreateContextsLength (4 bytes): The length, in bytes, of the list of SMB2_CREATE_CONTEXT structures sent in this request.

Buffer (variable): A variable-length buffer that contains the Unicode file name and create context list, as defined by NameOffset, NameLength, CreateContextsOffset, and CreateContextsLength. In the request, the Buffer field MUST be at least one byte in length. The file name (after DFS normalization if needed) MUST conform to the specification of a relative pathname in [MS-FSCC] section 2.1.5.

Show: