svn commit: r366023 - head/lib/libc/sys

Tue Sep 22 22:54:57 UTC 2020

Author: kib
Date: Tue Sep 22 22:54:54 2020
New Revision: 366023
URL: https://svnweb.freebsd.org/changeset/base/366023

Log:
  Document {O,AT}_RESOLVE_BENEATH and new O_BENEATH behavior for relative paths.
  
  PR:	248335
  Reviewed by:	markj
  Tested by:	pho
  Sponsored by:	The FreeBSD Foundation
  MFC after:	1 week
  Differential revision:	https://reviews.freebsd.org/D25886

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/fhlink.2
  head/lib/libc/sys/getfh.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	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/access.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)access.2	8.2 (Berkeley) 4/1/94
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt ACCESS 2
 .Os
 .Sh NAME
@@ -124,6 +124,13 @@ IDs instead of the real user and group ID as required 
 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.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/chflags.2
==============================================================================
--- head/lib/libc/sys/chflags.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/chflags.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"	@(#)chflags.2	8.3 (Berkeley) 5/2/95
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt CHFLAGS 2
 .Os
 .Sh NAME
@@ -99,6 +99,13 @@ Only allow to change flags for a file which is beneath
 the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/chmod.2
==============================================================================
--- head/lib/libc/sys/chmod.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/chmod.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)chmod.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt CHMOD 2
 .Os
 .Sh NAME
@@ -106,6 +106,13 @@ Only allow to change permissions of a file which is be
 the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/chown.2
==============================================================================
--- head/lib/libc/sys/chown.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/chown.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)chown.2	8.4 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt CHOWN 2
 .Os
 .Sh NAME
@@ -123,6 +123,13 @@ Only allow to change ownership of a file which is bene
 the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/fhlink.2
==============================================================================
--- head/lib/libc/sys/fhlink.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/fhlink.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt FHLINK 2
 .Os
 .Sh NAME
@@ -110,6 +110,13 @@ created.
 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.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/getfh.2
==============================================================================
--- head/lib/libc/sys/getfh.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/getfh.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -29,7 +29,7 @@
 .\"	@(#)getfh.2	8.1 (Berkeley) 6/9/93
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt GETFH 2
 .Os
 .Sh NAME
@@ -109,6 +109,13 @@ names a symbolic link, the status of the symbolic link
 Only stat files and directories below the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/link.2
==============================================================================
--- head/lib/libc/sys/link.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/link.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)link.2	8.3 (Berkeley) 1/12/94
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt LINK 2
 .Os
 .Sh NAME
@@ -119,6 +119,13 @@ created.
 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.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/open.2
==============================================================================
--- head/lib/libc/sys/open.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/open.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)open.2	8.2 (Berkeley) 11/16/93
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt OPEN 2
 .Os
 .Sh NAME
@@ -117,6 +117,12 @@ is specified with an absolute
 a directory passed by the
 .Fa fd
 argument is used as the topping point for the resolution.
+When
+.Dv O_BENEATH
+is specified with a relative path, the
+.Fa fd
+argument is used both as the starting point, and as the topping point
+for the resolution.
 See the definition of the
 .Dv O_BENEATH
 flag below.
@@ -183,7 +189,8 @@ 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 topping directory
+O_BENEATH	require resolved path to be strictly relative to topping directory
+O_RESOLVE_BENEATH	require walked path to be strictly relative to topping directory
 .Ed
 .Pp
 Opening a file with
@@ -311,8 +318,8 @@ been verified before operating on them.
 .Dv O_BENEATH
 returns
 .Er ENOTCAPABLE
-if the specified relative path, after resolving all symlinks and ".."
-references, does not reside in the directory hierarchy of
+if the specified path, after resolving all symlinks and ".."
+references, does not end up with tail residing in the directory hierarchy of
 children beneath the topping directory.
 Topping directory is the process current directory if relative
 .Fa path
@@ -322,11 +329,20 @@ and the directory referenced by the
 .Fa fd
 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
+.Dv O_RESOLVE_BENEATH
+returns
+.Er ENOTCAPABLE
+if any intermediate component of the specified relative path does not
+reside in the directory hierarchy beneath the topping directory.
+Comparing to
+.Dv O_BENEATH,
+absolute paths or even the temporal escape from beneath of the topping
+directory is not allowed.
+.Pp
 When
 .Fa fd
 is opened with
@@ -540,6 +556,12 @@ and
 .Dv O_EXEC
 or
 .Dv O_SEARCH .
+.It Bq Er EINVAL
+The
+.Dv O_RESOLVE_BENEATH
+flag is specified and
+.Dv path
+is absolute.
 .It Bq Er EBADF
 The
 .Fa path
@@ -582,6 +604,12 @@ does not have its tail fully contained under the toppi
 or the relative
 .Fa path
 escapes it.
+.It Bq Er ENOTCAPABLE
+The
+.Dv O_RESOLVE_BENEATH
+flag was provided, and the relative
+.Fa path
+escapes topping directory.
 .El
 .Sh SEE ALSO
 .Xr chmod 2 ,

Modified: head/lib/libc/sys/stat.2
==============================================================================
--- head/lib/libc/sys/stat.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/stat.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)stat.2	8.4 (Berkeley) 5/1/95
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt STAT 2
 .Os
 .Sh NAME
@@ -117,6 +117,13 @@ names a symbolic link, the status of the symbolic link
 Only stat files and directories below the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/unlink.2
==============================================================================
--- head/lib/libc/sys/unlink.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/unlink.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -28,7 +28,7 @@
 .\"     @(#)unlink.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt UNLINK 2
 .Os
 .Sh NAME
@@ -97,6 +97,13 @@ Only unlink files and directories which are beneath of
 directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.

Modified: head/lib/libc/sys/utimensat.2
==============================================================================
--- head/lib/libc/sys/utimensat.2	Tue Sep 22 22:48:12 2020	(r366022)
+++ head/lib/libc/sys/utimensat.2	Tue Sep 22 22:54:54 2020	(r366023)
@@ -31,7 +31,7 @@
 .\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt UTIMENSAT 2
 .Os
 .Sh NAME
@@ -151,6 +151,13 @@ Only allow to change the times of a file which is bene
 the topping directory.
 See the description of the
 .Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
+.It Dv AT_RESOLVE_BENEATH
+Only walks paths below the topping directory.
+See the description of the
+.Dv O_RESOLVE_BENEATH
 flag in the
 .Xr open 2
 manual page.
