Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 11 Nov 2018 01:46:48 +0000 (UTC)
From:      Konstantin Belousov <kib@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r340347 - head/lib/libc/sys
Message-ID:  <201811110146.wAB1kmGE019607@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
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 ,



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201811110146.wAB1kmGE019607>