[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 mode 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. POSIX mode is defined in POSIX-FSCC 2.1.1.

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].

POSIXMode (4 bytes): The POSIX mode as defined in POSIX-FSCC 2.1.1.

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.2 Client Details

3.2.1 Abstract Data Model

3.2.1.1 Global

The client MUST implement the following:

SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are globally available and enabled.

3.2.1.2 Per SMB2 Transport Connection

The client MUST implement the following:

Connection.SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are available on this connection.

3.2.1.4 Per Tree Connect

The client MUST implement the following:

TreeConnect.SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are effective on this mount.

3.2.1.5 Per Open

The client MUST implement the following:

Open.Posix: A boolean that indicates whether SMB3 POSIX Extensions are effective for this open.

Open.PosixAppend: the file was opened with O_APPEND by the client application.

3.2.3 Initialization

Global.SupportsPosix a boolean that MUST be initialized in an implementation defined manner.

3.2.4 Higher-Layer Triggered Events

3.2.4.2 Application Requests a Connection to a Share

The application provides the following additional info:

• Posix: A boolean indicating whether the application requests POSIX semantics on this share.

If the client does not implement the SMB 3.1.1 dialect and Posix is TRUE, the client MUST return STATUS_NOT_SUPPORTED to the calling application.

If Global.SupportsPosix is FALSE and Posix is TRUE, the client MUST return STATUS_NOT_SUPPORTED to the calling application.

The client MUST lookup the target server in the ConnectionTable. If an existing connection is found and if Connection.SupportsPosix is FALSE, the client MUST return STATUS_NOT_SUPPORTED to the calling application.

3.2.4.2.2 Negotiating the Protocol

3.2.4.2.2.2 SMB2-Only Negotiate

If Posix is requested by the application, it MUST do the following:

• Increment NegotiateContextCount by 1.

• Add an SMB2_NEGOTIATE_CONTEXT with ContextType as SMB3_POSIX_EXTENSIONS_AVAILABLE to the negotiate request as specified in section 2.2.3.1.

• Set Connection.SupportsPosix to TRUE.

3.2.4.2.4 Connecting to the Share

If Posix is TRUE, the client MUST set TreeConnect.SupportsPosix to TRUE.

3.2.4.3 Application Requests Opening a File

The application MUST provide the following additional parameter when creating files or directories:

• POSIXPerms: The requested POSIX permissions for the new object.

If TreeConnect.SupportsPosix is FALSE, the reminder of this section can be skipped.

When an application requests an open() with O_APPEND, the client MUST fill DesiredAccess with FILE_APPEND_DATA but without FILE_WRITE_DATA. The client MUST set Open.PosixAppend to True.

Otherwise the client MUST construct a create context, as specified in section 2.2.13.2.16 using the POSIXPerms value provided by the application, and append it to any other create contexts being issued with this CREATE request. Open.Posix MUST be set to TRUE.

3.2.4.7 Application Requests Writing to a File or Named Pipe

The Offset field MUST be set to -1 if Open.PosixAppend is True, otherwise Offset MUST be set to the application provided value.

3.2.4.8 Application Requests Querying File Attributes

If Open.Posix is FALSE and InformationClass is FilePosixInformation, as specified in section 2.3.1, the client MUST return STATUS_INVALID_INFO_CLASS.

3.2.4.9 Application Requests Applying File Attributes

The application optionally provides the following additional info:

• POSIXPerms: The requested POSIX permissions

If the optional parameter POSIXPerms is not present in the request, the reminder of this section MUST be skipped.

If Open.Posix is FALSE, the reminder of this section MUST be skipped.

Otherwise the client MUST initialize an empty security descriptor object, as specified in [MS-DTYP] section 2.4.6.

The client MUST process the optional POSIXPerms argument as follows:

• append an ACCESS_ALLOWED_ACE with SID S-1-5-88-3-mode, where mode is the numeric representation of POSIXPerms.

The client MUST initialize an SMB2 SET_INFO Request following the syntax specified in section [MS-SMB2] 2.2.39, SMB2 SET_INFO Request.

The SMB2 header MUST be initialized as specified in [MS-SMB2] 3.2.4.13, Application Requests Applying File Security.

The SMB2 SET_INFO Request MUST be initialized as specified in [MS-SMB2] 3.2.4.13, Application Requests Applying File Security with the following difference:

• The created security descriptor is copied into Buffer

3.2.5 Processing Events and Sequencing Rules

3.2.5.2 Receiving an SMB2 NEGOTIATE Response

If Connection.Dialect is "3.1.1", the client MUST process the NegotiateContextList that is specified by the response's NegotiateContextOffset and NegotiateContextCount fields as follows:

• If Connection.SupportsPosix is FALSE, a SMB3_POSIX_EXTENSIONS_AVAILABLE context MUST be ignored if present.

• If Connection.SupportsPosix is TRUE and the NegotiateContextList does not contain the SMB3_POSIX_EXTENSIONS_AVAILABLE context, the client MUST return STATUS_NOT_SUPPORTED to the calling application.

• If the NegotiateContextList contains more than one SMB3_POSIX_EXTENSIONS_AVAILABLE negotiate context, the client MUST return an error to the calling application.

Processing the SMB3_POSIX_EXTENSIONS_AVAILABLE negotiate context:

• If the SMB3_POSIX_EXTENSIONS_AVAILABLE negotiate context PosixTag doesn't match the data in 2.2.3.1.8 the request MUST return STATUS_INVALID_LEVEL to the calling application.

3.2.5.5 Receiving an SMB2 TREE_CONNECT Response

If TreeConnect.SupportsPosix is TRUE the client SHOULD send a SMB2_CREATE request to the server with the following parameters:

• path as ""

• DesiredAccess: READ_ATTRIBUTES

• RequestedOplockLevel: SMB2_OPLOCK_LEVEL_NONE

• FileAttributes: FILE_ATTRIBUTE_DIRECTORY

• ShareAccess: FILE_SHARE_READ + FILE_SHARE_WRITE + FILE_SHARE_DELETE

• CreateDisposition: FILE_OPEN

• CreateOptions: FILE_DIRECTORY_FILE

• SMB2_CREATE_CONTEXT: a single SMB2_CREATE_POSIX_CONTEXT context as specified in 2.2.13.2.16. POSIXPerms MUST be set to 0.

When receiving the response for this request, if the status code in the SMB2 header is not equal to STATUS_SUCCESS, the client MUST return the error to the calling application.

If the CreateContexts lists of the response doesn't contain a SMB2_CREATE_POSIX_CONTEXT context as specified in 2.2.14.2.16, the client MUST return the STATUS_NOT_SUPPORTED to the calling application.

Otherwise the client MUST set TreeConnect.SupportsPosix to TRUE and MUST return the metadata values of the context to the calling application.

3.2.5.7 Receiving an SMB2 CREATE Response for a New Create Operation

If Open.Posix is FALSE the reminder of this section MUST be skipped.

Otherwise, if the SMB2_CREATE_POSIX_CONTEXT context as specified in 2.2.14.2.16 is not present in the response, the client MUST return STATUS_NOT_SUPPORTED to the application.

The client MUST return the attributes returned in the SMB2_CREATE_POSIX_CONTEXT context to the calling application.

3.3 Server Details

3.3.1 Abstract Data Model

3.3.1.5 Global

The server MUST implement the following:

SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are globally available and enabled.

3.3.1.6 Per Share

The server MUST implement the following:

Share.SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are enabled on this share.

3.3.1.9 Per Tree Connect

The server MUST implement the following:

TreeConnect.SupportsPosix: A boolean that indicates whether SMB3 POSIX Extensions are enabled on this share.

3.3.1.10 Per Open

The server MUST implement the following:

Open.Posix: A boolean that indicates whether SMB3 POSIX Extensions are enabled for this open.

Open.PosixAppend: the client successfully requested an open with POSIX append-IO semantics.

3.3.3 Initialization

Global.SupportsPosix: a boolean that MUST be initialized in an implementation defined way.

3.3.5 Processing Events and Sequencing Rules

3.3.5.4 Receiving a SMB2 NEGOTIATE_CONTEXT Request

If the NegotiateContextList does not contain a SMB3_POSIX_EXTENSIONS_AVAILABLE context as specified in section 2.2.3.1, the reminder of this section can be skipped.

Otherwise, if Connection.Dialect is not "3.1.1", the request MUST fail with STATUS_INVALID_PARAMETER.

If Global.SupportsPosix is FALSE, the request MUST fail with STATUS_NOT_SUPPORTED.

The server MUST build a SMB3_POSIX_EXTENSIONS_AVAILABLE negotiate context, as specified in section 2.2.4.1.8, and add it to NegotiateContextList.

3.3.5.9 Receiving a SMB2 CREATE Request

3.3.5.9.1 Handling the SMB2_CREATE_POSIX_CONTEXT Create Context

If no SMB2_CREATE_POSIX_CONTEXT is present in the request, the remainder of this section MUST be skipped.

Otherweise, if Connection.Dialect is not 3.1.1, the server MUST fail the context with STATUS_INVALID_CLASS.

If more then one SMB2_CREATE_POSIX_CONTEXT is present, the request MUST fail with STATUS_INVALID_PARAMETER.

If Global.SupportsPosix is FALSE, the server MUST fail the request with STATUS_NOT_SUPPORTED.

If Share.SupportsPosix is FALSE, the server MUST fail the request with STATUS_NOT_SUPPORTED.

If the request is for a named pipe, the request MUST fail with STATUS_NOT_SUPPORTED.

If DesiredAccess contains FILE_APPEND_DATA:

• if DesiredAccess also contains FILE_WRITE_DATA, the subsequent actions MUST be skipped

• otherwise the server MUST pass O_APPEND to the underlying object store when requesting the open from the underlying object store.

Querying the object store:

• The server MUST pass TRUE as the value to the parameter IsPosix.

• The server MUST pass POSIXPerms from the SMB2_CREATE_POSIX_CONTEXT as additional parameter.

Successful Open Initialization:

• Open.Posix MUST be set to TRUE.

• Open.PosixAppend to True if O_APPEND was requested from the underlying object store.

The server MUST construct a response following the syntax specified in section 2.2.14. The values MUST be set as follows:

• NumberOfLinks: is set to the value queried from the object store.

• ReparseTag: is set to the value queried from the object store.

• POSIXPerms: is set to the value queried from the object store.

• OwnerSID: is set to the value queried from the object store.

• GroupSID: is set to the value queried from the object store.

3.3.5.13 Receiving an SMB2 WRITE Request

If the offset in the WRITE requests is -1:

• if Open.PosixAppend is not True, the operation MUST be failed with STATUS_INVALID_PARAMETER.

• otherwise the server MUST request a write from the underlying object store that writes data at the current end of the file

If the offset in the WRITE requests is not -1:

• if Open.PosixAppend is True, the operation MUST be failed with STATUS_INVALID_PARAMETER.

3.3.5.18 Receiving a SMB2 QUERY_DIRECTORY Request

In addition to the information classes listed in MS-SMB2 3.3.5.18, the server MUST support the FilePosixInformation class as specified in POSIX-FSCC 2.3.1.1

If the information class in the request is not FilePosixInformation, the reminder of this section MUST be skipped.

If Connection.Dialect is not "3.1.1" the request MUST be failed with STATUS_INVALID_INFO_CLASS.

If Open.Posix is FALSE, the server MUST fail the request with STATUS_INVALID_INFO_CLASS.

Querying the object store:

• The server MUST query the object store for the metdata requested in POSIX-FSCC 2.3.1.1.

The server MUST construct a response following the syntax specified in section POSIX-FSCC 2.3.1.1 and fill in the metadata with the values received from the object store.

3.3.5.20 Receiving a SMB2 QUERY_INFO Request

3.3.5.20.1 Handling SMB2_0_INFO_FILE

In addition to the information classes listed in MS-SMB2 2.2.37, the server MUST support the FilePosixInformation class as specified in POSIX-FSCC 2.3.1.1

If the information class in the request is not FilePosixInformation, the reminder of this section MUST be skipped.

If Connection.Dialect is not "3.1.1" the request MUST be failed with STATUS_INVALID_INFO_CLASS.

If Open.Posix is FALSE, the server MUST fail the request with STATUS_INVALID_INFO_CLASS.

Querying the object store:

• The server MUST query the object store for the metdata requested in POSIX-FSCC 2.3.1.1.

The server MUST construct a response following the syntax specified in section POSIX-FSCC 2.3.1.1 and fill in the metadata with the values received from the object store.

3.3.5.20.1 Handling SMB2_0_INFO_FILESYSTEM

In addition to the information classes listed in MS-SMB2 2.2.37, the server MUST support the FileFsPosixInformation class as specified in POSIX-FSCC 2.3.2.1.

If the information class in the request is not FileFsPosixInformation, the reminder of this section MUST be skipped.

If Connection.Dialect is not "3.1.1" the request MUST be failed with STATUS_INVALID_INFO_CLASS.

If Open.Posix is FALSE, the server MUST fail the request with STATUS_INVALID_INFO_CLASS.

Querying the object store:

• The server MUST query the object store for the metdata requested in POSIX-FSCC 2.3.2.1.

The server MUST construct a response following the syntax specified in section POSIX-FSCC 2.3.2.1 and fill in the metadata with the values received from the object store.

3.3.5.21 Receiving a SMB2 SET_INFO Request

3.3.5.21.3 Handling SMB2_0_INFO_SECURITY

If AdditionalInformation does not contain DACL_SECURITY_INFORMATION the reminder of this section MUST be skipped.

If the SECURITY_DESCRIPTOR.DACL in the Buffer does not contain an ACCESS_ALLOWED_ACE with the SID S-1-5-88-3, the reminder of this section MUST be skipped.

If Connection.Dialect is not "3.1.1" the request MUST be failed with STATUS_INVALID_INFO_CLASS.

If Open.Posix is FALSE, the server MUST fail the request with STATUS_INVALID_INFO_CLASS.

The server MUST issue an request to the underlying object store to modify the POSIX mode of the object, taking the mode value from the encoded SID S-1-5-88-3-mode.