From 1f305be431e07cfe5a40b3140775238ef44cdcbb Mon Sep 17 00:00:00 2001
From: Konstantin Belousov <kib@FreeBSD.org>
Date: Tue, 22 Sep 2020 22:54:54 +0000
Subject: [PATCH] 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
---
 lib/libc/sys/access.2    |  9 ++++++++-
 lib/libc/sys/chflags.2   |  9 ++++++++-
 lib/libc/sys/chmod.2     |  9 ++++++++-
 lib/libc/sys/chown.2     |  9 ++++++++-
 lib/libc/sys/fhlink.2    |  9 ++++++++-
 lib/libc/sys/getfh.2     |  9 ++++++++-
 lib/libc/sys/link.2      |  9 ++++++++-
 lib/libc/sys/open.2      | 38 +++++++++++++++++++++++++++++++++-----
 lib/libc/sys/stat.2      |  9 ++++++++-
 lib/libc/sys/unlink.2    |  9 ++++++++-
 lib/libc/sys/utimensat.2 |  9 ++++++++-
 11 files changed, 113 insertions(+), 15 deletions(-)

diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2
index 4ab31d3a99e..1cd7eed1301 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 March 30, 2020
+.Dd September 23, 2020
 .Dt ACCESS 2
 .Os
 .Sh NAME
@@ -127,6 +127,13 @@ See the description of the
 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.
 .El
 .Pp
 Even if a process's real or effective user has appropriate privileges
diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2
index 2b8ca12950b..b6b0b43249c 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 March 30, 2020
+.Dd September 23, 2020
 .Dt CHFLAGS 2
 .Os
 .Sh NAME
@@ -102,6 +102,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2
index 2f1b6afbb83..1d66408e389 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 March 30, 2020
+.Dd September 23, 2020
 .Dt CHMOD 2
 .Os
 .Sh NAME
@@ -109,6 +109,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2
index 9c571e76e83..64bfdeaa961 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 March 30, 2020
+.Dd September 23, 2020
 .Dt CHOWN 2
 .Os
 .Sh NAME
@@ -126,6 +126,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/fhlink.2 b/lib/libc/sys/fhlink.2
index db4ccf6fe40..1fcb7365fc0 100644
--- a/lib/libc/sys/fhlink.2
+++ b/lib/libc/sys/fhlink.2
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd September 23, 2020
 .Dt FHLINK 2
 .Os
 .Sh NAME
@@ -113,6 +113,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/getfh.2 b/lib/libc/sys/getfh.2
index d6318cdd1aa..5dc5896af6d 100644
--- a/lib/libc/sys/getfh.2
+++ b/lib/libc/sys/getfh.2
@@ -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
@@ -112,6 +112,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2
index e46de86a01d..c3451da1088 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 March 30, 2020
+.Dd September 23, 2020
 .Dt LINK 2
 .Os
 .Sh NAME
@@ -122,6 +122,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2
index c1bd88ec9d1..f54873563f0 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 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 topping directory,
 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 ,
diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2
index dd90420f20c..4759d297e8d 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 March 30, 2020
+.Dd September 23, 2020
 .Dt STAT 2
 .Os
 .Sh NAME
@@ -120,6 +120,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2
index d4bdf46e622..838d4da68af 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 March 30, 2020
+.Dd September 23, 2020
 .Dt UNLINK 2
 .Os
 .Sh NAME
@@ -100,6 +100,13 @@ See the description of the
 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.
 .El
 .Pp
 If
diff --git a/lib/libc/sys/utimensat.2 b/lib/libc/sys/utimensat.2
index baf947e04ca..3016d1af72a 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 March 30, 2020
+.Dd September 23, 2020
 .Dt UTIMENSAT 2
 .Os
 .Sh NAME
@@ -154,6 +154,13 @@ See the description of the
 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.
 .El
 .Sh RETURN VALUES
 .Rv -std
-- 
2.45.0