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.
_______________________________________________
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
