d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

First draft of documentation for AT/O_BENEATH handling of the absolute

Browse Source 
paths.

It was decided that committing the code and drafting of the man page
update is better than allowing the code to rot until wordsmithing
happens.

Reviewed by:	jilles (previous version)
Discussed with:	brooks, jilles, emaste
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D17714
This commit is contained in:
kib 2018-11-11 01:46:48 +00:00
parent 678be3be34
commit b2b4bc844b
9 changed files with 252 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
lib/libc/sys/access.2
View File

@ -28,7 +28,7 @@
.\" @(#)access.2 8.2 (Berkeley) 4/1/94
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt ACCESS 2
.Os
.Sh NAME
@ -121,7 +121,12 @@ The checks for accessibility are performed using the effective user and group
IDs instead of the real user and group ID as required in a call to
.Fn access .
.It Dv AT_BENEATH
Only operate on files and directories below the starting directory.
Only operate on files and directories below the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
Even if a process's real or effective user has appropriate privileges
@ -198,14 +203,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn faccessat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chmod 2 ,

26
lib/libc/sys/chflags.2
View File

@ -28,7 +28,7 @@
.\" @(#)chflags.2 8.3 (Berkeley) 5/2/95
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt CHFLAGS 2
.Os
.Sh NAME
@ -96,7 +96,12 @@ If
names a symbolic link, then the flags of the symbolic link are changed.
.It Dv AT_BENEATH
Only allow to change flags for a file which is beneath of
the starting directory.
the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
If
@ -306,14 +311,23 @@ The underlying file system does not support file flags, or
does not support all of the flags set in
.Fa flags .
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn chflagsat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chflags 1 ,

26
lib/libc/sys/chmod.2
View File

@ -28,7 +28,7 @@
.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt CHMOD 2
.Os
.Sh NAME
@ -103,7 +103,12 @@ If
names a symbolic link, then the mode of the symbolic link is changed.
.It Dv AT_BENEATH
Only allow to change permissions of a file which is beneath of
the starting directory.
the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
If
@ -289,14 +294,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn fchmodat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chmod 1 ,

26
lib/libc/sys/chown.2
View File

@ -28,7 +28,7 @@
.\" @(#)chown.2 8.4 (Berkeley) 4/19/94
.\" $FreeBSD$
.\"
.Dd Octover 20, 2018
.Dd November 11, 2018
.Dt CHOWN 2
.Os
.Sh NAME
@ -120,7 +120,12 @@ If
names a symbolic link, ownership of the symbolic link is changed.
.It Dv AT_BENEATH
Only allow to change ownership of a file which is beneath of
the starting directory.
the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
If
@ -231,14 +236,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn fchownat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chgrp 1 ,

28
lib/libc/sys/link.2
View File

@ -28,7 +28,7 @@
.\" @(#)link.2 8.3 (Berkeley) 1/12/94
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt LINK 2
.Os
.Sh NAME
@ -116,7 +116,12 @@ If
names a symbolic link, a new link for the target of the symbolic link is
created.
.It Dv AT_BENEATH
Only allow to link to a file which is beneath of the starting directory.
Only allow to link to a file which is beneath of the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
If
@ -260,16 +265,25 @@ respectively, is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
.Fa name1
is not strictly relative to the starting directory.
For example,
.Fa name1
is absolute or includes a ".." component that escapes the starting directory.
is absolute or includes a ".." component that escapes
the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified.
flag was provided to
.Fa linkat
and the absolute path
.Fa name1
does not have its tail fully contained under the topping directory,
or the relative path
.Fa name1
escapes it.
.El
.Sh SEE ALSO
.Xr chflags 2 ,

79
lib/libc/sys/open.2
View File

@ -28,7 +28,7 @@
.\" @(#)open.2 8.2 (Berkeley) 11/16/93
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt OPEN 2
.Os
.Sh NAME
@ -75,8 +75,14 @@ function is equivalent to the
.Fn open
function except in the case where the
.Fa path
specifies a relative path.
In this case the file to be opened is determined relative to the directory
specifies a relative path, or the
.Dv O_BENEATH
flag is provided.
For
.Fn openat
and relative
.Fa path ,
the file to be opened is determined relative to the directory
associated with the file descriptor
.Fa fd
instead of the current working directory.
@ -95,6 +101,26 @@ parameter, the current working directory is used
and the behavior is identical to a call to
.Fn open .
.Pp
When
.Fn openat
is called with an absolute
.Fa path
without the
.Dv O_BENEATH
flag, it ignores the
.Fa fd
argument.
When
.Dv O_BENEATH
is specified with an absolute
.Fa path ,
a directory passed by the
.Fa fd
argument is used as the topping point for the resolution.
See the definition of the
.Dv O_BENEATH
flag below.
.Pp
In
.Xr capsicum 4
capability mode,
@ -109,14 +135,28 @@ must be strictly relative to a file descriptor
as defined in
.Pa sys/kern/vfs_lookup.c .
.Fa path
must not be an absolute path and must not contain ".." components.
must not be an absolute path and must not contain ".." components
which cause the path resolution to escape the directory hierarchy
starting at
.Fa fd .
Additionally, no symbolic link in
.Fa path
may contain ".." components either.
may target absolute path or contain escaping ".." components.
.Fa fd
must not be
.Dv AT_FDCWD .
.Pp
If the
.Dv vfs.lookup_cap_dotdot
.Xr sysctl 3
MIB is set to zero, ".." components in the paths,
used in capability mode, or with the
.Dv O_BENEATH
flag, are completely disabled.
If the
.Dv vfs.lookup_cap_dotdot_nonlocal
MIB is set to zero, ".." is not allowed if found on non-local filesystem.
.Pp
The flags specified are formed by
.Em or Ns 'ing
the following values
@ -142,7 +182,7 @@ O_TTY_INIT ignored
O_DIRECTORY error if file is not a directory
O_CLOEXEC set FD_CLOEXEC upon open
O_VERIFY verify the contents of the file
O_BENEATH require path to be strictly relative to starting directory
O_BENEATH require path to be strictly relative to topping directory
.Ed
.Pp
Opening a file with
@ -273,19 +313,21 @@ been verified before operating on them.
.Dv O_BENEATH
returns
.Er ENOTCAPABLE
if the specified path, after resolving all symlinks and ".." references
in it, does not reside in the directory hierarchy of children beneath
the starting directory, or is an absolute path.
Starting directory is the process current directory if relative
if the specified relative path, after resolving all symlinks and ".."
references, does not reside in the directory hierarchy of
children beneath the topping directory.
Topping directory is the process current directory if relative
.Fa path
is used for
.Fn open ,
and the directory referenced by the
.Fa fd
argument when specifying relative
.Fa path
for
argument when using
.Fn openat .
If the specified path is absolute,
.Dv O_BENEATH
allows arbitrary prefix that ends up at the topping directory,
after which all further resolved components must be under it.
.Pp
If successful,
.Fn open
@ -509,9 +551,16 @@ is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode or the
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv O_BENEATH
flag was provided.
flag was provided, and the absolute
.Fa path
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
escapes it.
.El
.Sh SEE ALSO
.Xr chmod 2 ,

55
lib/libc/sys/stat.2
View File

@ -28,7 +28,7 @@
.\" @(#)stat.2 8.4 (Berkeley) 5/1/95
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt STAT 2
.Os
.Sh NAME
@ -84,11 +84,24 @@ and
.Fn lstat
except when the
.Fa path
specifies a relative path.
In this case the status is retrieved from a file relative to
specifies a relative path, or the
.Dv AT_BENEATH
flag is provided.
For
.Fn fstatat
and relative
.Fa path ,
the status is retrieved from a file relative to
the directory associated with the file descriptor
.Fa fd
instead of the current working directory.
For
.Dv AT_BENEATH
and absolute
.Fa path ,
the status is retrieved from a file specified by the
.Fa path ,
but additional permission checks are performed, see below.
.Pp
The values for the
.Fa flag
@ -101,7 +114,7 @@ If
.Fa path
names a symbolic link, the status of the symbolic link is returned.
.It Dv AT_BENEATH
Only stat files and directories below the starting directory.
Only stat files and directories below the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
@ -125,6 +138,23 @@ respectively, depending on whether or not the
bit is set in
.Fa flag .
.Pp
When
.Fn fstatat
is called with an absolute
.Fa path
without the
.Dv AT_BENEATH
flag, it ignores the
.Fa fd
argument.
When
.Dv AT_BENEATH
is specified with an absolute
.Fa path ,
a directory passed by the
.Fa fd
argument is used as the topping point for the resolution.
.Pp
The
.Fa sb
argument is a pointer to a
@ -405,14 +435,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn fstatat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr access 2 ,

26
lib/libc/sys/unlink.2
View File

@ -28,7 +28,7 @@
.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt UNLINK 2
.Os
.Sh NAME
@ -90,8 +90,13 @@ and
.Fa path
as a directory, not a normal file.
.It Dv AT_BENEATH
Only unlink files and directories which are beneath of the starting
Only unlink files and directories which are beneath of the topping
directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Pp
If
@ -204,14 +209,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn unlinkat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chflags 2 ,

26
lib/libc/sys/utimensat.2
View File

@ -31,7 +31,7 @@
.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd October 20, 2018
.Dd November 11, 2018
.Dt UTIMENSAT 2
.Os
.Sh NAME
@ -148,7 +148,12 @@ By default,
changes the times of the file referenced by the symbolic link.
.It Dv AT_BENEATH
Only allow to change the times of a file which is beneath of
the starting directory.
the topping directory.
See the description of the
.Dv O_BENEATH
flag in the
.Xr open 2
manual page.
.El
.Sh RETURN VALUES
.Rv -std
@ -271,14 +276,23 @@ is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.It Bq Er ENOTCAPABLE
.Fa path
is an absolute path,
or contained a ".." component leading to a
directory outside of the directory hierarchy specified by
.Fa fd ,
and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv AT_BENEATH
flag was specified but
flag was provided to
.Fn utimensat ,
and the absolute
.Fa path
is not strictly relative to the starting directory.
For example,
does not have its tail fully contained under the topping directory,
or the relative
.Fa path
is absolute or includes a ".." component that escapes the starting directory.
escapes it.
.El
.Sh SEE ALSO
.Xr chflags 2 ,