diff options
Diffstat (limited to 'manual/users.texi')
| -rw-r--r-- | manual/users.texi | 476 |
1 files changed, 262 insertions, 214 deletions
diff --git a/manual/users.texi b/manual/users.texi index e6e358f44a..5ee2e64deb 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -49,9 +49,9 @@ can use to examine these databases. accessing the user database. * Group Database:: Functions and data structures for accessing the group database. -* Netgroup Database:: Functions for accessing the netgroup database. -* Database Example:: Example program showing use of database +* Database Example:: Example program showing the use of database inquiry functions. +* Netgroup Database:: Functions for accessing the netgroup database. @end menu @node User and Group IDs @@ -68,32 +68,33 @@ in a data base which you can access as described in @ref{User Database}. @cindex group name @cindex group ID -Users are classified in @dfn{groups}. Each user name also belongs to -one or more groups, and has one @dfn{default group}. Users who are -members of the same group can share resources (such as files) that are -not accessible to users who are not a member of that group. Each group -has a @dfn{group name} and @dfn{group ID}. @xref{Group Database}, -for how to find information about a group ID or group name. +Users are classified in @dfn{groups}. Each user name belongs to one +@dfn{default group} and may also belong to any number of +@dfn{supplementary groups}. Users who are members of the same group can +share resources (such as files) that are not accessible to users who are +not a member of that group. Each group has a @dfn{group name} and +@dfn{group ID}. @xref{Group Database}, for how to find information +about a group ID or group name. @node Process Persona @section The Persona of a Process @cindex persona @cindex effective user ID @cindex effective group ID +@cindex supplementary group IDs -@c !!! bogus; not single ID. set of effective group IDs (and, in GNU, -@c set of effective UIDs) determines privilege. lying here and then -@c telling the truth below is confusing. -At any time, each process has a single user ID and a group ID which -determine the privileges of the process. These are collectively called -the @dfn{persona} of the process, because they determine ``who it is'' -for purposes of access control. These IDs are also called the -@dfn{effective user ID} and @dfn{effective group ID} of the process. +@c When Hurd is more widely used, explain multiple effective user IDs +@c here. -zw +At any time, each process has an @dfn{effective user ID}, a @dfn{effective +group ID}, and a set of @dfn{supplementary group IDs}. These IDs +determine the privileges of the process. They are collectively +called the @dfn{persona} of the process, because they determine ``who it +is'' for purposes of access control. Your login shell starts out with a persona which consists of your user -ID and your default group ID. -@c !!! also supplementary group IDs. -In normal circumstances, all your other processes inherit these values. +ID, your default group ID, and your supplementary group IDs (if you are +in more than one group). In normal circumstances, all your other processes +inherit these values. @cindex real user ID @cindex real group ID @@ -106,16 +107,19 @@ also important. Both the real and effective user ID can be changed during the lifetime of a process. @xref{Why Change Persona}. -@cindex supplementary group IDs -In addition, a user can belong to multiple groups, so the persona -includes @dfn{supplementary group IDs} that also contribute to access -permission. - -For details on how a process's effective user IDs and group IDs affect +For details on how a process's effective user ID and group IDs affect its permission to access files, see @ref{Access Permission}. -The user ID of a process also controls permissions for sending signals -using the @code{kill} function. @xref{Signaling Another Process}. +The effective user ID of a process also controls permissions for sending +signals using the @code{kill} function. @xref{Signaling Another +Process}. + +Finally, there are many operations which can only be performed by a +process whose effective user ID is zero. A process with this user ID is +a @dfn{privileged process}. Commonly the user name @code{root} is +associated with user ID 0, but there may be other user names with this +ID. +@c !!! should mention POSIX capabilities here. @node Why Change Persona @section Why Change the Persona of a Process? @@ -152,6 +156,9 @@ adopt the persona of @code{games} so it can write the scores file. @node How Change Persona @section How an Application Can Change Persona @cindex @code{setuid} programs +@cindex saved set-user-ID +@cindex saved set-group-ID +@cindex @code{_POSIX_SAVED_IDS} The ability to change the persona of a process can be a source of unintentional privacy violations, or even intentional abuse. Because of @@ -164,22 +171,28 @@ program to change its persona is that it has been set up in advance to change to a particular user or group. This is the function of the setuid and setgid bits of a file's access mode. @xref{Permission Bits}. -When the setuid bit of an executable file is set, executing that file -automatically changes the effective user ID to the user that owns the -file. Likewise, executing a file whose setgid bit is set changes the -effective group ID to the group of the file. @xref{Executing a File}. -Creating a file that changes to a particular user or group ID thus -requires full access to that user or group ID. +When the setuid bit of an executable file is on, executing that file +gives the process a third user ID: the @dfn{file user ID}. This ID is +set to the owner ID of the file. The system then changes the effective +user ID to the file user ID. The real user ID remains as it was. +Likewise, if the setgid bit is on, the process is given a @dfn{file +group ID} equal to the group ID of the file, and its effective group ID +is changed to the file group ID. + +If a process has a file ID (user or group), then it can at any time +change its effective ID to its real ID and back to its file ID. +Programs use this feature to relinquish their special privileges except +when they actually need them. This makes it less likely that they can +be tricked into doing something inappropriate with their privileges. + +@strong{Portability Note:} Older systems do not have file IDs. +To determine if a system has this feature, you can test the compiler +define @code{_POSIX_SAVED_IDS}. (In the POSIX standard, file IDs are +known as saved IDs.) @xref{File Attributes}, for a more general discussion of file modes and accessibility. -A process can always change its effective user (or group) ID back to its -real ID. Programs do this so as to turn off their special privileges -when they are not needed, which makes for more robustness. - -@c !!! talk about _POSIX_SAVED_IDS - @node Reading Persona @section Reading the Persona of a Process @@ -276,18 +289,15 @@ include the header files @file{sys/types.h} and @file{unistd.h}. @comment unistd.h @comment POSIX.1 -@deftypefun int setuid (uid_t @var{newuid}) -This function sets both the real and effective user ID of the process -to @var{newuid}, provided that the process has appropriate privileges. -@c !!! also sets saved-id - -If the process is not privileged, then @var{newuid} must either be equal -to the real user ID or the saved user ID (if the system supports the -@code{_POSIX_SAVED_IDS} feature). In this case, @code{setuid} sets only -the effective user ID and not the real user ID. -@c !!! xref to discussion of _POSIX_SAVED_IDS - -The @code{setuid} function returns a value of @code{0} to indicate +@deftypefun int seteuid(uid_t @var{neweuid}) +This function sets the effective user ID of a process to @var{newuid}, +provided that the process is allowed to change its effective user ID. A +privileged process (effective user ID zero) can change its effective +user ID to any legal value. An unprivileged process with a file user ID +can change its effective user ID to its real user ID or to its file user +ID. Otherwise, a process may not change its effective user ID at all. + +The @code{seteuid} function returns a value of @code{0} to indicate successful completion, and a value of @code{-1} to indicate an error. The following @code{errno} error conditions are defined for this function: @@ -297,9 +307,27 @@ function: The value of the @var{newuid} argument is invalid. @item EPERM -The process does not have the appropriate privileges; you do not -have permission to change to the specified ID. +The process may not change to the specified ID. @end table + +Older systems (those without the @code{_POSIX_SAVED_IDS} feature) do not +have this function. +@end deftypefun + +@comment unistd.h +@comment POSIX.1 +@deftypefun int setuid (uid_t @var{newuid}) +If the calling process is privileged, this function sets both the real +and effective user ID of the process to @var{newuid}. It also deletes +the file user ID of the process, if any. @var{newuid} may be any +legal value. (Once this has been done, there is no way to recover the +old effective user ID.) + +If the process is not privileged, and the system supports the +@code{_POSIX_SAVED_IDS} feature, then this function behaves like +@code{seteuid}. + +The return values and error conditions are the same as for @code{seteuid}. @end deftypefun @comment unistd.h @@ -311,9 +339,9 @@ not to change the real user ID; likewise if @var{euid} is @code{-1}, it means not to change the effective user ID. The @code{setreuid} function exists for compatibility with 4.3 BSD Unix, -which does not support saved IDs. You can use this function to swap the +which does not support file IDs. You can use this function to swap the effective and real user IDs of the process. (Privileged processes are -not limited to this particular usage.) If saved IDs are supported, you +not limited to this particular usage.) If file IDs are supported, you should use that feature instead of this function. @xref{Enable/Disable Setuid}. @@ -339,31 +367,49 @@ the header files @file{sys/types.h} and @file{unistd.h}. @comment unistd.h @comment POSIX.1 +@deftypefun int setegid (gid_t @var{newgid}) +This function sets the effective group ID of the process to +@var{newgid}, provided that the process is allowed to change its group +ID. Just as with @code{seteuid}, if the process is privileged it may +change its effective group ID to any value; if it isn't, but it has a +file group ID, then it may change to its real group ID or file group ID; +otherwise it may not change its effective group ID. + +Note that a process is only privileged if its effective @emph{user} ID +is zero. The effective group ID only affects access permissions. + +The return values and error conditions for @code{setegid} are the same +as those for @code{seteuid}. + +This function is only present if @code{_POSIX_SAVED_IDS} is defined. +@end deftypefun + +@comment unistd.h +@comment POSIX.1 @deftypefun int setgid (gid_t @var{newgid}) This function sets both the real and effective group ID of the process -to @var{newgid}, provided that the process has appropriate privileges. -@c !!! also sets saved-id +to @var{newgid}, provided that the process is privileged. It also +deletes the file group ID, if any. -If the process is not privileged, then @var{newgid} must either be equal -to the real group ID or the saved group ID. In this case, @code{setgid} -sets only the effective group ID and not the real group ID. +If the process is not privileged, then @code{setgid} behaves like +@code{setegid}. The return values and error conditions for @code{setgid} are the same -as those for @code{setuid}. +as those for @code{seteuid}. @end deftypefun @comment unistd.h @comment BSD -@deftypefun int setregid (gid_t @var{rgid}, fid_t @var{egid}) +@deftypefun int setregid (gid_t @var{rgid}, gid_t @var{egid}) This function sets the real group ID of the process to @var{rgid} and the effective group ID to @var{egid}. If @var{rgid} is @code{-1}, it means not to change the real group ID; likewise if @var{egid} is @code{-1}, it means not to change the effective group ID. The @code{setregid} function is provided for compatibility with 4.3 BSD -Unix, which does not support saved IDs. You can use this function to +Unix, which does not support file IDs. You can use this function to swap the effective and real group IDs of the process. (Privileged -processes are not limited to this usage.) If saved IDs are supported, +processes are not limited to this usage.) If file IDs are supported, you should use that feature instead of using this function. @xref{Enable/Disable Setuid}. @@ -371,7 +417,19 @@ The return values and error conditions for @code{setregid} are the same as those for @code{setreuid}. @end deftypefun -The GNU system also lets privileged processes change their supplementary +@code{setuid} and @code{setgid} behave differently depending on whether +the effective user ID at the time is zero. If it is not zero, they +behave like @code{seteuid} and @code{setegid}. If it is, they change +both effective and real IDs and delete the file ID. To avoid confusion, +we recommend you always use @code{seteuid} and @code{setegid} except +when you know the effective user ID is zero and your intent is to change +the persona permanently. This case is rare---most of the programs that +need it, such as @code{login} and @code{su}, have already been written. + +Note that if your program is setuid to some user other than @code{root}, +there is no way to drop privileges permanently. + +The system also lets privileged processes change their supplementary group IDs. To use @code{setgroups} or @code{initgroups}, your programs should include the header file @file{grp.h}. @pindex grp.h @@ -396,11 +454,16 @@ The calling process is not privileged. @comment grp.h @comment BSD @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid}) -The @code{initgroups} function effectively calls @code{setgroups} to -set the process's supplementary group IDs to be the normal default for -the user name @var{user}. The group ID @var{gid} is also included. -@c !!! explain that this works by reading the group file looking for -@c groups USER is a member of. +The @code{initgroups} function sets the process's supplementary group +IDs to be the normal default for the user name @var{user}. If @var{gid} +is not -1, it includes that group also. + +This function works by scanning the group database for all the groups +@var{user} belongs to. It then calls @code{setgroups} with the list it +has constructed. + +The return values and error conditions are the same as for +@code{setgroups}. @end deftypefun @node Enable/Disable Setuid @@ -410,11 +473,11 @@ A typical setuid program does not need its special access all of the time. It's a good idea to turn off this access when it isn't needed, so it can't possibly give unintended access. -If the system supports the saved user ID feature, you can accomplish -this with @code{setuid}. When the game program starts, its real user ID -is @code{jdoe}, its effective user ID is @code{games}, and its saved -user ID is also @code{games}. The program should record both user ID -values once at the beginning, like this: +If the system supports the @code{_POSIX_SAVED_IDS} feature, you can +accomplish this with @code{seteuid}. When the game program starts, its +real user ID is @code{jdoe}, its effective user ID is @code{games}, and +its saved user ID is also @code{games}. The program should record both +user ID values once at the beginning, like this: @smallexample user_user_id = getuid (); @@ -424,22 +487,22 @@ game_user_id = geteuid (); Then it can turn off game file access with @smallexample -setuid (user_user_id); +seteuid (user_user_id); @end smallexample @noindent and turn it on with @smallexample -setuid (game_user_id); +seteuid (game_user_id); @end smallexample @noindent Throughout this process, the real user ID remains @code{jdoe} and the -saved user ID remains @code{games}, so the program can always set its +file user ID remains @code{games}, so the program can always set its effective user ID to either one. -On other systems that don't support the saved user ID feature, you can +On other systems that don't support file user IDs, you can turn setuid access on and off by using @code{setreuid} to swap the real and effective user IDs of the process, as follows: @@ -475,12 +538,12 @@ feature with a preprocessor conditional, like this: Here's an example showing how to set up a program that changes its effective user ID. -This is part of a game program called @code{caber-toss} that -manipulates a file @file{scores} that should be writable only by the game -program itself. The program assumes that its executable -file will be installed with the set-user-ID bit set and owned by the -same user as the @file{scores} file. Typically, a system -administrator will set up an account like @code{games} for this purpose. +This is part of a game program called @code{caber-toss} that manipulates +a file @file{scores} that should be writable only by the game program +itself. The program assumes that its executable file will be installed +with the setuid bit set and owned by the same user as the @file{scores} +file. Typically, a system administrator will set up an account like +@code{games} for this purpose. The executable file is given mode @code{4755}, so that doing an @samp{ls -l} on it produces output like: @@ -490,7 +553,7 @@ The executable file is given mode @code{4755}, so that doing an @end smallexample @noindent -The set-user-ID bit shows up in the file modes as the @samp{s}. +The setuid bit shows up in the file modes as the @samp{s}. The scores file is given mode @code{644}, and doing an @samp{ls -l} on it shows: @@ -501,7 +564,7 @@ it shows: Here are the parts of the program that show how to set up the changed user ID. This program is conditionalized so that it makes use of the -saved IDs feature if it is supported, and otherwise uses @code{setreuid} +file IDs feature if it is supported, and otherwise uses @code{setreuid} to swap the effective and real user IDs. @smallexample @@ -511,7 +574,7 @@ to swap the effective and real user IDs. #include <stdlib.h> -/* @r{Save the effective and real UIDs.} */ +/* @r{Remember the effective and real UIDs.} */ static uid_t euid, ruid; @@ -524,7 +587,7 @@ do_setuid (void) int status; #ifdef _POSIX_SAVED_IDS - status = setuid (euid); + status = seteuid (euid); #else status = setreuid (ruid, euid); #endif @@ -544,7 +607,7 @@ undo_setuid (void) int status; #ifdef _POSIX_SAVED_IDS - status = setuid (ruid); + status = seteuid (ruid); #else status = setreuid (euid, ruid); #endif @@ -560,7 +623,7 @@ undo_setuid (void) int main (void) @{ - /* @r{Save the real and effective user IDs.} */ + /* @r{Remember the real and effective user IDs.} */ ruid = getuid (); euid = geteuid (); undo_setuid (); @@ -574,8 +637,8 @@ Notice how the first thing the @code{main} function does is to set the effective user ID back to the real user ID. This is so that any other file accesses that are performed while the user is playing the game use the real user ID for determining permissions. Only when the program -needs to open the scores file does it switch back to the original -effective user ID, like this: +needs to open the scores file does it switch back to the file user ID, +like this: @smallexample /* @r{Record the score.} */ @@ -623,15 +686,16 @@ Don't have @code{setuid} programs with privileged user IDs such as @code{root} unless it is absolutely necessary. If the resource is specific to your particular program, it's better to define a new, nonprivileged user ID or group ID just to manage that resource. +It's better if you can write your program to use a special group than a +special user. @item -Be cautious about using the @code{system} and @code{exec} functions in -combination with changing the effective user ID. Don't let users of -your program execute arbitrary programs under a changed user ID. -Executing a shell is especially bad news. Less obviously, the -@code{execlp} and @code{execvp} functions are a potential risk (since -the program they execute depends on the user's @code{PATH} environment -variable). +Be cautious about using the @code{exec} functions in combination with +changing the effective user ID. Don't let users of your program execute +arbitrary programs under a changed user ID. Executing a shell is +especially bad news. Less obviously, the @code{execlp} and @code{execvp} +functions are a potential risk (since the program they execute depends +on the user's @code{PATH} environment variable). If you must @code{exec} another program under a changed ID, specify an absolute file name (@pxref{File Name Resolution}) for the executable, @@ -639,6 +703,14 @@ and make sure that the protections on that executable and @emph{all} containing directories are such that ordinary users cannot replace it with some other program. +You should also check the arguments passed to the program to make sure +they do not have unexpected effects. Likewise, you should examine the +environment variables. Decide which arguments and variables are safe, +and reject all others. + +You should never use @code{system} in a privileged program, because it +invokes a shell. + @item Only use the user ID controlling the resource in the part of the program that actually uses that resource. When you're finished with it, restore @@ -692,7 +764,8 @@ This string is statically allocated and might be overwritten on subsequent calls to this function or to @code{getlogin}. The use of this function is deprecated since it is marked to be -withdrawn in XPG4.2 and it is already removed in POSIX.1. +withdrawn in XPG4.2 and has already been removed from newer revisions of +POSIX.1. @end deftypefun @comment stdio.h @@ -1077,7 +1150,7 @@ This macro is used to specify the user accounting log file. The @code{utmpname} function returns a value of @code{0} if the new name was successfully stored, and a value of @code{-1} to indicate an error. -Note that @code{utmpname} does not try open the database, and that +Note that @code{utmpname} does not try to open the database, and that therefore the return value does not say anything about whether the database can be successfully opened. @end deftypefun @@ -1321,10 +1394,10 @@ members. Older systems do not even have the @code{ut_host} member. @cindex password database @pindex /etc/passwd -This section describes all about how to search and scan the database of -registered users. The database itself is kept in the file -@file{/etc/passwd} on most systems, but on some systems a special -network server gives access to it. +This section describes how to search and scan the database of registered +users. The database itself is kept in the file @file{/etc/passwd} on +most systems, but on some systems a special network server gives access +to it. @menu * User Data Structure:: What each user record contains. @@ -1397,21 +1470,20 @@ user ID @var{uid}. @comment pwd.h @comment POSIX.1c @deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) -This function is similar to @code{getpwuid} in that is returns -information about the user whose user ID is @var{uid}. But the result -is not placed in a static buffer. Instead the user supplied structure -pointed to by @var{result_buf} is filled with the information. The -first @var{buflen} bytes of the additional buffer pointed to by -@var{buffer} are used to contain additional information, normally -strings which are pointed to by the elements of the result structure. +This function is similar to @code{getpwuid} in that it returns +information about the user whose user ID is @var{uid}. However, it +fills the user supplied structure pointed to by @var{result_buf} with +the information instead of using a static buffer. The first +@var{buflen} bytes of the additional buffer pointed to by @var{buffer} +are used to contain additional information, normally strings which are +pointed to by the elements of the result structure. If the return value is @code{0} the pointer returned in @var{result} points to the record which contains the wanted data (i.e., @var{result} -contains the value @var{result_buf}). In case the return value is non -null there is no user in the data base with user ID @var{uid} or the -buffer @var{buffer} is too small to contain all the needed information. -In the later case the global @var{errno} variable is set to -@code{ERANGE}. +contains the value @var{result_buf}). If it is nonzero, there is no +user in the data base with user ID @var{uid}, or the buffer @var{buffer} +is too small to contain all the needed information. In the latter case, +@var{errno} is set to @code{ERANGE}. @end deftypefun @@ -1423,27 +1495,19 @@ containing information about the user whose user name is @var{name}. This structure may be overwritten on subsequent calls to @code{getpwnam}. -A null pointer value indicates there is no user named @var{name}. +A null pointer return indicates there is no user named @var{name}. @end deftypefun @comment pwd.h @comment POSIX.1c @deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) This function is similar to @code{getpwnam} in that is returns -information about the user whose user name is @var{name}. But the result -is not placed in a static buffer. Instead the user supplied structure -pointed to by @var{result_buf} is filled with the information. The -first @var{buflen} bytes of the additional buffer pointed to by -@var{buffer} are used to contain additional information, normally -strings which are pointed to by the elements of the result structure. +information about the user whose user name is @var{name}. However, like +@code{getpwuid_r}, it fills the user supplied buffers in +@var{result_buf} and @var{buffer} with the information instead of using +a static buffer. -If the return value is @code{0} the pointer returned in @var{result} -points to the record which contains the wanted data (i.e., @var{result} -contains the value @var{result_buf}). In case the return value is non -null there is no user in the data base with user name @var{name} or the -buffer @var{buffer} is too small to contain all the needed information. -In the later case the global @var{errno} variable is set to -@code{ERANGE}. +The return values are the same as for @code{getpwuid_r}. @end deftypefun @@ -1466,8 +1530,8 @@ pointer to the entry. The structure is statically allocated and is |