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>