The New Samba VFS

On Linux the O_PATH flag to open() can be used to open a filehandle on a file or directory with interesting properties: ¹

• the file-handle indicates a location in the filesystem tree,
• no permission checks are done by the kernel on the filesystem object and
• only operations that act purely at the file descriptor level are allowed.

The file itself is not opened, and other file operations (e.g., read(2), write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2), mmap(2)) fail with the error EBADF.

The following subset of operations that is relevant to Samba is allowed:

• close(2),
• fchdir(2), if the file descriptor refers to a directory,
• fstat(2),
• fstatfs(2) and
• passing the file descriptor as the dirfd argument of openat() and the other "*at()" system calls. This includes linkat(2) with AT_EMPTY_PATH (or via procfs using AT_SYMLINK_FOLLOW) even if the file is not a directory.

Opening a file or directory with the O_PATH flag requires no permissions on the object itself (but does require execute permission on the directories in the path prefix). By contrast, obtaining a reference to a filesystem object by opening it with the O_RDONLY flag requires that the caller have read permission on the object, even when the subsequent operation (e.g., fchdir(2), fstat(2)) does not require read permis‐ sion on the object.

If for example Samba receives an SMB request to open a file requesting SEC_FILE_READ_ATTRIBUTE access rights because the client wants to read the file's metadata from the handle, Samba will have to call open() with at least O_RDONLY access rights.

The O_PATH flag is currently not used in Samba. By leveraging this Linux specific flags we can avoid permission mismatches as described above.

Additionally O_PATH allows basing all filesystem accesses done by the fileserver on handle based syscalls by opening all client pathnames with O_PATH and consistently using for example fstat() instead of stat() throughout the codebase.

Subsequent parts of this document will call such file-handles opened with O_PATH path referencing file-handles or *pathref*s for short.

In Samba the decision whether to call POSIX open() on a client pathname or whether to leave the low-level handle at -1 (what we call a stat-open) is based on the client requested SMB acccess mask.

The set of access rights that trigger an open() includes READ_CONTROL_ACCESS. As a result, the open() will be done with at least O_RDONLY. If the filesystem supports NT style ACLs natively (like GPFS or ZFS), the filesystem may grant the user requested right READ_CONTROL_ACCESS, but it may not grant READ_DATA (O_RDONLY).

Currently the full set of access rights that trigger opening a file is:

• FILE_READ_DATA
• FILE_WRITE_DATA
• FILE_APPEND_DATA
• FILE_EXECUTE
• WRITE_DAC_ACCESS
• WRITE_OWNER_ACCESS
• SEC_FLAG_SYSTEM_SECURITY
• READ_CONTROL_ACCESS

In the future we can remove the following rights from the list on systems that support O_PATH:

• WRITE_DAC_ACCESS
• WRITE_OWNER_ACCESS
• SEC_FLAG_SYSTEM_SECURITY
• READ_CONTROL_ACCESS

The code of higher level file-handle consumers must be kept simple and streamlined, avoiding special casing the handling of the file-handles opened with or without O_PATH. To achieve this, a fallback that allows opening a file-handle with the same higher level semantics even if the system doesn't support O_PATH is needed.

The way this is implemented on such systems is impersonating the root user for the open() syscall. In order to avoid privelege escalations security issues, we must carefully control the use these file-handles.

The low level filehandle is stored in a public struct struct file_handle that is part of the widely used struct files_struct. Consumers used to simply access the fd directly by derefencing pointers to struct files_struct.

In order to guard access to such file-handles we do two things:

• tag the pathref file-handles and
• control access to the file-handle by making the structure struct file_handle private, only allowing access with accessor functions that implement a security boundary.

In order to avoid bypassing restrictive permissions on intermediate directories of a client path, the root user is only impersonated after changing directory to the parent directory of the client requested pathname.

Two functions can then be used to fetch the low-level system file-handle from a struct files_struct:

• fsp_get_io_fd(fsp): enforces fsp is NOT a pathref file-handle and
• fsp_get_pathref_fd(fsp): allows fsp to be either a pathref file-handle or a traditional POSIX file-handle opened with O_RDONLY or any other POSIX open flag.

Note that the name fsp_get_pathref_fd() may sound confusing at first given that the fsp can be either a pathref fsp or a "normal/full" fsp, but as any full file-handle can be used for IO and as path reference, the name correctly reflects the intended usage of the caller.

The general guideline is:

• if you do something like fstat(fd), use fsp_get_pathref_fd(),
• if you do something like *at(dirfd, ...), use fsp_get_pathref_fd(),
• if you want to print the fd for example in DEBUG messages, use fsp_get_pathref_fd(),
• if you want to call close(fd), use fsp_get_pathref_fd(),
• if you're doing a logical comparison of fd values, use fsp_get_pathref_fd().

In any other case use fsp_get_io_fd().

• SMB_VFS_CONNECT()
• SMB_VFS_DISCONNECT()
• SMB_VFS_DISK_FREE()
• SMB_VFS_FS_CAPABILITIES()
• SMB_VFS_GET_DFS_REFERRALS()
• SMB_VFS_SNAP_CHECK_PATH()
• SMB_VFS_SNAP_CREATE()
• SMB_VFS_SNAP_DELETE()
• SMB_VFS_STATVFS()

No changes needed.

• SMB_VFS_AIO_FORCE()
• SMB_VFS_BRL_LOCK_WINDOWS()
• SMB_VFS_BRL_UNLOCK_WINDOWS()
• SMB_VFS_CLOSE()
• SMB_VFS_CLOSEDIR()
• SMB_VFS_DURABLE_COOKIE()
• SMB_VFS_DURABLE_DISCONNECT()
• SMB_VFS_FALLOCATE()
• SMB_VFS_FCHMOD()
• SMB_VFS_FCHOWN()
• SMB_VFS_FCNTL()
• SMB_VFS_FDOPENDIR()
• SMB_VFS_FGET_DOS_ATTRIBUTES()
• SMB_VFS_FGET_NT_ACL()
• SMB_VFS_FSCTL()
• SMB_VFS_FSET_DOS_ATTRIBUTES()
• SMB_VFS_FSET_NT_ACL()
• SMB_VFS_FSTAT()
• SMB_VFS_FSYNC()
• SMB_VFS_FSYNC_SEND()
• SMB_VFS_FTRUNCATE()
• SMB_VFS_GETLOCK()
• SMB_VFS_GET_ALLOC_SIZE()
• SMB_VFS_GET_SHADOW_COPY_DATA()
• SMB_VFS_KERNEL_FLOCK()
• SMB_VFS_LINUX_SETLEASE()
• SMB_VFS_LOCK()
• SMB_VFS_LSEEK()
• SMB_VFS_OFFLOAD_READ_SEND()
• SMB_VFS_OFFLOAD_WRITE_SEND()
• SMB_VFS_PREAD()
• SMB_VFS_PREAD_SEND()
• SMB_VFS_PWRITE()
• SMB_VFS_PWRITE_SEND()
• SMB_VFS_READDIR()
• SMB_VFS_RECVFILE()
• SMB_VFS_REWINDDIR()
• SMB_VFS_SEEKDIR()
• SMB_VFS_SENDFILE()
• SMB_VFS_SET_COMPRESSION()
• SMB_VFS_STRICT_LOCK_CHECK()
• SMB_VFS_TELLDIR()

If an fsp is provided by the SMB layer we use that, otherwise we use the pathref fsp smb_fname->fsp provided by filename_convert().

• SMB_VFS_CREATE_FILE()

All intermediate VFS calls within SMB_VFS_CREATE_FILE() will be based on smb_fname->fsp if the requested path exists. When creating a file we rely on non_widelink_open() which doesn't depend on a dirfsp.

• SMB_VFS_MKDIRAT()

Needs a real dirfsp (done).

• SMB_VFS_OPENAT()

Is only called from within non_widelink_open() with a dirfsp equivalent of AT_FDCWD and so doesn't need a real dirfsp.

The following operations need a real dirfsp:

• SMB_VFS_LINKAT()
• SMB_VFS_MKNODAT()
• SMB_VFS_RENAMEAT()
• SMB_VFS_SYMLINKAT()
• SMB_VFS_UNLINKAT()

Callers use openat_pathref_fsp() to open a fsp on the parent directory.

All path based VFS functtions will be replaced by handle based variants using the smb_fname->fsp provided by filename_convert().

• SMB_VFS_CHDIR()
• SMB_VFS_CHFLAGS()
• SMB_VFS_CHMOD()
• SMB_VFS_DURABLE_RECONNECT()
• SMB_VFS_GETXATTR()
• SMB_VFS_GET_COMPRESSION()
• SMB_VFS_GET_DOS_ATTRIBUTES()
• SMB_VFS_GET_NT_ACL_AT()
• SMB_VFS_LCHOWN()
• SMB_VFS_LISTXATTR()
• SMB_VFS_LSTAT()
• SMB_VFS_NTIMES()
• SMB_VFS_REMOVEXATTR()
• SMB_VFS_SETXATTR()
• SMB_VFS_SET_DOS_ATTRIBUTES()
• SMB_VFS_STAT()
• SMB_VFS_STREAMINFO()
• SMB_VFS_SYS_ACL_BLOB_GET_FILE()
• SMB_VFS_SYS_ACL_DELETE_DEF_FILE()
• SMB_VFS_SYS_ACL_GET_FILE()
• SMB_VFS_SYS_ACL_SET_FILE()

Replace with corresponding handle based VFS calls.

• SMB_VFS_CREATE_DFS_PATHAT()
• SMB_VFS_READ_DFS_PATHAT()
• SMB_VFS_READLINKAT()

As the DFS link implementation is based on symlinks, we have to use *AT based functions with real dirfsps.

• SMB_VFS_GET_DOS_ATTRIBUTES_SEND()
• SMB_VFS_GETXATTRAT_SEND()
• SMB_VFS_READDIR_ATTRAT() (NEW)

• SMB_VFS_FGETXATTR()
• SMB_VFS_FLISTXATTR()
• SMB_VFS_FREMOVEXATTR()
• SMB_VFS_FSETXATTR()
• SMB_VFS_SYS_ACL_BLOB_GET_FD()
• SMB_VFS_SYS_ACL_GET_FD()
• SMB_VFS_SYS_ACL_DELETE_DEF_FD() (NEW)
• SMB_VFS_SYS_ACL_SET_FD()

Based upon securely opening a full fd based on /proc/self/fd/%d as in the case of xattrs, pathref handles can't be used for xattr IO, and in the case of ACLs pathref handles can't be used to access default ACEs.

• SMB_VFS_CONNECTPATH()
• SMB_VFS_GET_REAL_FILENAME()
• SMB_VFS_REALPATH()
• SMB_VFS_TRANSLATE_NAME()

No changes needed.

• SMB_VFS_FILE_ID_CREATE()
• SMB_VFS_FS_FILE_ID()
• SMB_VFS_GET_QUOTA()
• SMB_VFS_GETWD()
• SMB_VFS_SET_QUOTA()

No changes needed.

• SMB_VFS_AUDIT_FILE()

This is currently unused.