diff options
Diffstat (limited to 'man/man2/setfsuid.2')
| -rw-r--r-- | man/man2/setfsuid.2 | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/man/man2/setfsuid.2 b/man/man2/setfsuid.2 new file mode 100644 index 000000000..c6e75dafa --- /dev/null +++ b/man/man2/setfsuid.2 @@ -0,0 +1,127 @@ +.\" Copyright (C) 1995, Thomas K. Dyas <tdyas@eden.rutgers.edu> +.\" and Copyright (C) 2013, 2019, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 1995-08-06 Thomas K. Dyas <tdyas@eden.rutgers.edu> +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on capability requirements +.\" +.TH setfsuid 2 (date) "Linux man-pages (unreleased)" +.SH NAME +setfsuid \- set user identity used for filesystem checks +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/fsuid.h> +.P +.BI "[[deprecated]] int setfsuid(uid_t " fsuid ); +.fi +.SH DESCRIPTION +On Linux, a process has both a filesystem user ID and an effective user ID. +The (Linux-specific) filesystem user ID is used +for permissions checking when accessing filesystem objects, +while the effective user ID is used for various other kinds +of permissions checks (see +.BR credentials (7)). +.P +Normally, the value of the process's filesystem user ID +is the same as the value of its effective user ID. +This is so, because whenever a process's effective user ID is changed, +the kernel also changes the filesystem user ID to be the same as +the new value of the effective user ID. +A process can cause the value of its filesystem user ID to diverge +from its effective user ID by using +.BR setfsuid () +to change its filesystem user ID to the value given in +.IR fsuid . +.P +Explicit calls to +.BR setfsuid () +and +.BR setfsgid (2) +are (were) usually used only by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is (was) a security hole that can expose it to unwanted signals. +(However, this issue is historical; see below.) +.P +.BR setfsuid () +will succeed only if the caller is the superuser or if +.I fsuid +matches either the caller's real user ID, effective user ID, +saved set-user-ID, or current filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem user ID of the caller. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.P +At the time when this system call was introduced, one process +could send a signal to another process with the same effective user ID. +This meant that if a privileged process changed its effective user ID +for the purpose of file permission checking, +then it could become vulnerable to receiving signals +sent by another (unprivileged) process with the same user ID. +The filesystem user ID attribute was thus added to allow a process to +change its user ID for the purposes of file permission checking without +at the same time becoming vulnerable to receiving unwanted signals. +Since Linux 2.0, signal permission handling is different (see +.BR kill (2)), +with the result that a process can change its effective user ID +without being vulnerable to receiving signals from unwanted processes. +Thus, +.BR setfsuid () +is nowadays unneeded and should be avoided in new applications +(likewise for +.BR setfsgid (2)). +.P +The original Linux +.BR setfsuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setfsuid32 () +supporting 32-bit IDs. +The glibc +.BR setfsuid () +wrapper function transparently deals with the variation across kernel versions. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit user IDs), +it will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH BUGS +No error indications of any kind are returned to the caller, +and the fact that both successful and unsuccessful calls return +the same value makes it impossible to directly determine +whether the call succeeded or failed. +Instead, the caller must resort to looking at the return value +from a further call such as +.I setfsuid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsuid () +changed the filesystem user ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETUID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsgid (2), +.BR capabilities (7), +.BR credentials (7) |