svn commit: r340347 - head/lib/libc/sys
Konstantin Belousov
kib at FreeBSD.org
Sun Nov 11 01:46:51 UTC 2018
Author: kib
Date: Sun Nov 11 01:46:48 2018
New Revision: 340347
URL: https://svnweb.freebsd.org/changeset/base/340347
Log:
First draft of documentation for AT/O_BENEATH handling of the absolute
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
Modified:
head/lib/libc/sys/access.2
head/lib/libc/sys/chflags.2
head/lib/libc/sys/chmod.2
head/lib/libc/sys/chown.2
head/lib/libc/sys/link.2
head/lib/libc/sys/open.2
head/lib/libc/sys/stat.2
head/lib/libc/sys/unlink.2
head/lib/libc/sys/utimensat.2
Modified: head/lib/libc/sys/access.2
==============================================================================
--- head/lib/libc/sys/access.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/access.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 e
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 ,
Modified: head/lib/libc/sys/chflags.2
==============================================================================
--- head/lib/libc/sys/chflags.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/chflags.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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
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 ,
Modified: head/lib/libc/sys/chmod.2
==============================================================================
--- head/lib/libc/sys/chmod.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/chmod.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/chown.2
==============================================================================
--- head/lib/libc/sys/chown.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/chown.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/link.2
==============================================================================
--- head/lib/libc/sys/link.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/link.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/open.2
==============================================================================
--- head/lib/libc/sys/open.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/open.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/stat.2
==============================================================================
--- head/lib/libc/sys/stat.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/stat.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/unlink.2
==============================================================================
--- head/lib/libc/sys/unlink.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/unlink.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
Modified: head/lib/libc/sys/utimensat.2
==============================================================================
--- head/lib/libc/sys/utimensat.2 Sun Nov 11 00:57:13 2018 (r340346)
+++ head/lib/libc/sys/utimensat.2 Sun Nov 11 01:46:48 2018 (r340347)
@@ -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 ,
More information about the svn-src-head
mailing list