9 files changed, 252 insertions, 66 deletions

diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2
index b1b049925c7d6..0001d99941b6e 100644
--- a/lib/libc/sys/access.2
+++ b/lib/libc/sys/access.2
@@ -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 ,
diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2
index c9caea862009c..7db10569ea31c 100644
--- a/lib/libc/sys/chflags.2
+++ b/lib/libc/sys/chflags.2
@@ -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 ,
diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2
index 65a7047293297..aef920ee6fefd 100644
--- a/lib/libc/sys/chmod.2
+++ b/lib/libc/sys/chmod.2
@@ -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 ,
diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2
index 8ba2b9240b3d7..7eb8322c77d86 100644
--- a/lib/libc/sys/chown.2
+++ b/lib/libc/sys/chown.2
@@ -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 ,
diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2
index 057f2aeccd522..3c6e32b3e9a5a 100644
--- a/lib/libc/sys/link.2
+++ b/lib/libc/sys/link.2
@@ -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 ,
diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2
index d98d5b62a227e..012e0afd23d89 100644
--- a/lib/libc/sys/open.2
+++ b/lib/libc/sys/open.2
@@ -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 ,
diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2
index 37b04aedcd801..f72dc0d0a117a 100644
--- a/lib/libc/sys/stat.2
+++ b/lib/libc/sys/stat.2
@@ -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 ,
diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2
index 2e0ed54b0a297..c6c6a150c1a20 100644
--- a/lib/libc/sys/unlink.2
+++ b/lib/libc/sys/unlink.2
@@ -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 ,
diff --git a/lib/libc/sys/utimensat.2 b/lib/libc/sys/utimensat.2
index 7fcb3c6696974..cf7ba290a813c 100644
--- a/lib/libc/sys/utimensat.2
+++ b/lib/libc/sys/utimensat.2
@@ -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 ,