[POSIX-SMB2] SMB3 POSIX Extensions

Specifies the SMB3 protocol extension for supporting POSIX compliant operating systems.

Published Version

Previous Versions

1 Introduction

The SMB3 POSIX Extensions are protocol extensions to enable POSIX compliant operating systems to better interoperate with SMB3 servers and storage appliances by extending the [MS-SMB2] specification. Popular servers such as Samba, Windows Server and others support SMB3 by default. These extensions are already implemented in multiple clients and servers.

2 Messages and Structures

2.2 Message Syntax

2.2.3 SMB2 NEGOTIATE Request

2.2.3.1 SMB2 NEGOTIATE_CONTEXT Request Values

Refer to section 2.2.3.1 of [MS-SMB2] for additional details. This section only explains details relevant to a SMB3_POSIX_EXTENSIONS_AVAILABLE negotiate context request.

ContextType (2 bytes): Specifies the type of context in the Data field. This field MUST contain one of the values specified in section 2.2.3.1 of [MS-SMB2] or the following extended value:

DataLength (2 bytes): The length, in bytes, of the Data field.

Reserved (4 bytes): This field MUST NOT be used and MUST be reserved. This value MUST be set to 0 by the client, and MUST be ignored by the server.

Data (variable): A variable-length field that contains the negotiate context specified by the ContextType field.

2.2.3.1.8 SMB3_POSIX_EXTENSIONS_AVAILABLE

The SMB3_POSIX_EXTENSIONS_AVAILABLE context is specified in an SMB2 NEGOTIATE request by the client to indicate the version of SMB3 POSIX Extensions that the client supports. The format of the data in the Data field of this SMB2_NEGOTIATE_CONTEXT is as follows.

PosixTag (16 bytes): A blob indicating the SMB3 POSIX version. The following versions are defined.

2.2.4 SMB2 NEGOTIATE Response

2.2.4.1 SMB2 NEGOTIATE_CONTEXT Response Values

2.2.4.1.8 SMB3_POSIX_EXTENSIONS_AVAILABLE

The SMB3_POSIX_EXTENSIONS_AVAILABLE context is specified in an SMB2 NEGOTIATE response by the server to indicate that the SMB3 POSIX version specified by the client is supported. The format of the data in the Data field of this SMB2_NEGOTIATE_CONTEXT MUST take the same form specified in section 2.2.3.1.8.

2.2.13 SMB2 CREATE Request

2.2.13.2 SMB2_CREATE_CONTEXT Request Values

Refer to section 2.2.13.2 of [MS-SMB2] for additional details. This section only explains details relevant to a SMB2_CREATE_POSIX_CONTEXT request.

Next (4 bytes): The offset from the beginning of this Create Context to the beginning of a subsequent 8-byte aligned Create Context. This field MUST be set to 0 if there are no subsequent contexts.

TagOffset (2 bytes): The offset from the beginning of this structure to its 8-byte aligned tag value.

TagLength (2 bytes): The length, in bytes, of the Create Context tag.

Reserved (2 bytes): This field MUST NOT be used and MUST be reserved. This value MUST be set to 0 by the client, and ignored by the server.

BlobOffset (2 bytes): The offset, in bytes, from the beginning of this structure to the 8-byte aligned data payload. If BlobLength is 0, the client SHOULD set this value to 0 and the server MUST ignore it on receipt.

BlobLength (4 bytes): The length, in bytes, of the data. The format of the data is determined by the type of SMB2_CREATE_CONTEXT request, as outlined in the following sections. The type is inferred from the Create Context name specified by the TagOffset and TagLength fields.

Buffer (variable): A variable-length buffer that contains the name and data fields, as defined by TagOffset, TagLength, BlobOffset, and BlobLength. The tag is represented as four or more octets and MUST be one of the values provided in section 2.2.13.2 of [MS-SMB2] and the following table. The structure tag indicates what information is encoded by the data payload. The values specified in section 2.2.13.2 of [MS-SMB2] and the following extended value are the valid Create Context values and are defined to be in network byte order.

2.2.13.2.16 SMB2_CREATE_POSIX_CONTEXT

The SMB2_CREATE_POSIX_CONTEXT context is only specified on an SMB2 CREATE Request if SMB3_POSIX_EXTENSIONS_AVAILABLE was negotiated. The client MAY specify SMB2_CREATE_POSIX_CONTEXT if POSIX permissions will be set on create, or POSIX attributes will be requested from the returned file handle.

POSIXPerms (4 bytes): The posix permissions requested on create if FILE_SUPERSEDE, FILE_CREATE, FILE_OPEN_IF, FILE_OVERWRITE, or FILE_OVERWRITE_IF are specfied in the CreateDisposition. The server MUST ignore this value if the file exists. If the CreateDisposition is FILE_OPEN the client MUST set this to 0 and it MUST be ignored by the server.

2.2.14.2 SMB2_CREATE_CONTEXT Response Values

2.2.14.2.16 SMB2_CREATE_POSIX_CONTEXT Response

The SMB2_CREATE_POSIX_CONTEXT response is sent by the server in response to a SMB2_CREATE_POSIX_CONTEXT request (section 2.2.13.2.16).

NumberOfLinks (4 bytes): The number of hard links to the file.

ReparseTag (4 bytes): The reparse tag, as defined in section 2.1.2.1 of [MS-FSCC].

POSIXPerms (4 bytes): The posix permissions for the opened file as defined in section 4.5 of IEEE Std 1003.1-2017.

OwnerSID (variable): The owner SID as defined in Microsoft Security identifiers.

GroupSID (variable): The group SID as defined in Microsoft Security identifiers.

2.2.33 SMB2 QUERY_DIRECTORY Request

Refer to section 2.2.33 of [MS-SMB2] for additional details. This section only explains details relevant to a SMB2_FIND_POSIX_INFORMATION request.

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

FileInformationClass (1 byte): The file information class describing the format that data MUST be returned in. Possible values are specified in section 2.2.33 of [MS-SMB2] as well as the following extended file information class:

Flags (1 byte): Flags indicating how the query directory operation MUST be processed. As indicated in section 2.2.33 of [MS-SMB2].

FileIndex (4 bytes): The byte offset within the directory, indicating the position at which to resume the enumeration. If SMB2_INDEX_SPECIFIED is set in Flags, this value MUST be supplied and is based on the FileIndex value received in a previous enumeration response. Otherwise, it MUST be set to zero and the server MUST ignore it.

FileId (16 bytes): An SMB2_FILEID identifier of the directory on which to perform the enumeration. This is returned from an SMB2 Create Request to open a directory on the server.

FileNameOffset (2 bytes): The offset, in bytes, from the beginning of the SMB2 header to the search pattern to be used for the enumeration. This field MUST be 0 if no search pattern is provided.

FileNameLength (2 bytes): The length, in bytes, of the search pattern. This field MUST be 0 if no search pattern is provided.

OutputBufferLength (4 bytes): The maximum number of bytes the server is allowed to return in the SMB2 QUERY_DIRECTORY Response.

Buffer (variable): A variable-length buffer containing the Unicode search pattern for the request, as described by the FileNameOffset and FileNameLength fields. The format, including wildcards and other conventions for this pattern, is specified in [MS-CIFS] section 2.2.1.1.3.

2.2.34 SMB2 QUERY_DIRECTORY Response

Refer to section 2.2.34 of [MS-SMB2] for additional details. This section only explains details relevant to a SMB2_FIND_POSIX_INFORMATION request.

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

OutputBufferOffset (2 bytes): The offset, in bytes, from the beginning of the SMB2 header to the directory enumeration data being returned.

OutputBufferLength (4 bytes): The length, in bytes, of the directory enumeration being returned.

Buffer (variable): A variable-length buffer containing the directory enumeration being returned in the response, as described by the OutputBufferOffset and OutputBufferLength. The format of this content is as specified in [MS-FSCC] section 2.4, within the topic for the specific file information class referenced in the SMB2 QUERY_DIRECTORY Request. The format for FilePosixInformation is described POSIX-FSCC 2.3.1.1.

2.2.37 SMB2 QUERY_INFO Request

Refer to section 2.2.37 of [MS-SMB2] for additional details. This section only explains details relevant to a SMB2_FIND_POSIX_INFORMATION request.

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

InfoType (1 byte): The type of information queried. This field MUST contain one of the values specified in section 2.2.37 of [MS-SMB2].

FileInfoClass (1 byte): For file information queries, this field MUST contain one of the FILE_INFORMATION_CLASS values, as specified in section 3.3.5.20.1 of [MS-SMB2] and in [MS-FSCC] section 2.4, or the following extension defined in section [POSIX-FSCC 2.3.1.1].

• FilePosixInformation

OutputBufferLength (4 bytes): The maximum number of bytes of information the server can send in the response.

InputBufferOffset (2 bytes): The offset, in bytes, from the beginning of the SMB2 header to the input buffer.

Reserved (2 bytes): This field MUST NOT be used and MUST be reserved. The client MUST set this field to 0, and the server MUST ignore it on receipt.

InputBufferLength (4 bytes): The length of the input buffer.

AdditionalInformation (4 bytes): Provides additional information to the server.

Flags (4 bytes): The flags MUST be set to a combination of zero or more of the bit values defined in section 2.2.37 of [MS-SMB2] for a FileFullEaInformation query.

FileId (16 bytes): An SMB2_FILEID identifier of the file or named pipe on which to perform the query. Queries for underlying object store or quota information are directed to the volume on which the file resides.

Buffer (variable): A variable-length buffer containing the input buffer for the request, as described by the InputBufferOffset and InputBufferLength fields.

3 Protocol Details

3.3 Server Details

3.3.5 Processing Events and Sequencing Rules

3.3.5.4 Receiving a SMB2 NEGOTIATE_CONTEXT Request

3.3.5.9 Receiving a SMB2 CREATE Request

3.3.5.18 Receiving a SMB2 QUERY_DIRECTORY Request

3.3.5.20 Receiving a SMB2 QUERY_INFO Request

3.3.5.21 Receiving a SMB2 SET_INFO Request