239 lines
13 KiB
HTML
239 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>setuid</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="setuid"></a> <a name="tag_03_670"></a><!-- setuid -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_670_01"></a>NAME</h4>
|
|
|
|
<blockquote>setuid - set user ID</blockquote>
|
|
|
|
<h4><a name="tag_03_670_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/unistd.h.html">unistd.h</a>><br>
|
|
<br>
|
|
int setuid(uid_t</tt> <i>uid</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>If the process has appropriate privileges, <i>setuid</i>() shall set the real user ID, effective user ID, and the saved
|
|
set-user-ID of the calling process to <i>uid</i>.</p>
|
|
|
|
<p>If the process does not have appropriate privileges, but <i>uid</i> is equal to the real user ID or the saved set-user-ID,
|
|
<i>setuid</i>() shall set the effective user ID to <i>uid</i>; the real user ID and saved set-user-ID shall remain unchanged.</p>
|
|
|
|
<p>The <i>setuid</i>() function shall not affect the supplementary group list in any way.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and <i>errno</i> set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>setuid</i>() function shall fail, return -1, and set <i>errno</i> to the corresponding value if one or more of the
|
|
following are true:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of the <i>uid</i> argument is invalid and not supported by the implementation.</dd>
|
|
|
|
<dt>[EPERM]</dt>
|
|
|
|
<dd>The process does not have appropriate privileges and <i>uid</i> does not match the real user ID or the saved set-user-ID.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_670_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The various behaviors of the <i>setuid</i>() and <a href="../functions/setgid.html"><i>setgid</i>()</a> functions when called by
|
|
non-privileged processes reflect the behavior of different historical implementations. For portability, it is recommended that new
|
|
non-privileged applications use the <a href="../functions/seteuid.html"><i>seteuid</i>()</a> and <a href=
|
|
"../functions/setegid.html"><i>setegid</i>()</a> functions instead.</p>
|
|
|
|
<p>The saved set-user-ID capability allows a program to regain the effective user ID established at the last <i><a href=
|
|
"../functions/exec.html">exec</a></i> call. Similarly, the saved set-group-ID capability allows a program to regain the effective
|
|
group ID established at the last <i><a href="../functions/exec.html">exec</a></i> call. These capabilities are derived from System
|
|
V. Without them, a program might have to run as superuser in order to perform the same functions, because superuser can write on
|
|
the user's files. This is a problem because such a program can write on any user's files, and so must be carefully written to
|
|
emulate the permissions of the calling process properly. In System V, these capabilities have traditionally been implemented only
|
|
via the <i>setuid</i>() and <a href="../functions/setgid.html"><i>setgid</i>()</a> functions for non-privileged processes. The fact
|
|
that the behavior of those functions was different for privileged processes made them difficult to use. The POSIX.1-1990 standard
|
|
defined the <i>setuid</i>() function to behave differently for privileged and unprivileged users. When the caller had the
|
|
appropriate privilege, the function set the calling process' real user ID, effective user ID, and saved set-user ID on
|
|
implementations that supported it. When the caller did not have the appropriate privilege, the function set only the effective user
|
|
ID, subject to permission checks. The former use is generally needed for utilities like <i>login</i> and <i>su</i>, which are not
|
|
conforming applications and thus outside the scope of IEEE Std 1003.1-2001. These utilities wish to change the user ID
|
|
irrevocably to a new value, generally that of an unprivileged user. The latter use is needed for conforming applications that are
|
|
installed with the set-user-ID bit and need to perform operations using the real user ID.</p>
|
|
|
|
<p>IEEE Std 1003.1-2001 augments the latter functionality with a mandatory feature named _POSIX_SAVED_IDS. This feature
|
|
permits a set-user-ID application to switch its effective user ID back and forth between the values of its <i><a href=
|
|
"../functions/exec.html">exec</a></i>-time real user ID and effective user ID. Unfortunately, the POSIX.1-1990 standard did not
|
|
permit a conforming application using this feature to work properly when it happened to be executed with the
|
|
(implementation-defined) appropriate privilege. Furthermore, the application did not even have a means to tell whether it had this
|
|
privilege. Since the saved set-user-ID feature is quite desirable for applications, as evidenced by the fact that NIST required it
|
|
in FIPS 151-2, it has been mandated by IEEE Std 1003.1-2001. However, there are implementors who have been reluctant to
|
|
support it given the limitation described above.</p>
|
|
|
|
<p>The 4.3BSD system handles the problem by supporting separate functions: <i>setuid</i>() (which always sets both the real and
|
|
effective user IDs, like <i>setuid</i>() in IEEE Std 1003.1-2001 for privileged users), and <a href=
|
|
"../functions/seteuid.html"><i>seteuid</i>()</a> (which always sets just the effective user ID, like <i>setuid</i>() in
|
|
IEEE Std 1003.1-2001 for non-privileged users). This separation of functionality into distinct functions seems desirable.
|
|
4.3BSD does not support the saved set-user-ID feature. It supports similar functionality of switching the effective user ID back
|
|
and forth via <a href="../functions/setreuid.html"><i>setreuid</i>()</a>, which permits reversing the real and effective user IDs.
|
|
This model seems less desirable than the saved set-user-ID because the real user ID changes as a side effect. The current 4.4BSD
|
|
includes saved effective IDs and uses them for <a href="../functions/seteuid.html"><i>seteuid</i>()</a> and <a href=
|
|
"../functions/setegid.html"><i>setegid</i>()</a> as described above. The <a href="../functions/setreuid.html"><i>setreuid</i>()</a>
|
|
and <a href="../functions/setregid.html"><i>setregid</i>()</a> functions will be deprecated or removed.</p>
|
|
|
|
<p>The solution here is:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Require that all implementations support the functionality of the saved set-user-ID, which is set by the <i><a href=
|
|
"../functions/exec.html">exec</a></i> functions and by privileged calls to <i>setuid</i>().</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Add the <a href="../functions/seteuid.html"><i>seteuid</i>()</a> and <a href="../functions/setegid.html"><i>setegid</i>()</a>
|
|
functions as portable alternatives to <i>setuid</i>() and <a href="../functions/setgid.html"><i>setgid</i>()</a> for non-privileged
|
|
and privileged processes.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Historical systems have provided two mechanisms for a set-user-ID process to change its effective user ID to be the same as its
|
|
real user ID in such a way that it could return to the original effective user ID: the use of the <i>setuid</i>() function in the
|
|
presence of a saved set-user-ID, or the use of the BSD <a href="../functions/setreuid.html"><i>setreuid</i>()</a> function, which
|
|
was able to swap the real and effective user IDs. The changes included in IEEE Std 1003.1-2001 provide a new mechanism
|
|
using <a href="../functions/seteuid.html"><i>seteuid</i>()</a> in conjunction with a saved set-user-ID. Thus, all implementations
|
|
with the new <a href="../functions/seteuid.html"><i>seteuid</i>()</a> mechanism will have a saved set-user-ID for each process, and
|
|
most of the behavior controlled by _POSIX_SAVED_IDS has been changed to agree with the case where the option was defined. The <a
|
|
href="../functions/kill.html"><i>kill</i>()</a> function is an exception. Implementors of the new <a href=
|
|
"../functions/seteuid.html"><i>seteuid</i>()</a> mechanism will generally be required to maintain compatibility with the older
|
|
mechanisms previously supported by their systems. However, compatibility with this use of <a href=
|
|
"../functions/setreuid.html"><i>setreuid</i>()</a> and with the _POSIX_SAVED_IDS behavior of <a href=
|
|
"../functions/kill.html"><i>kill</i>()</a> is unfortunately complicated. If an implementation with a saved set-user-ID allows a
|
|
process to use <a href="../functions/setreuid.html"><i>setreuid</i>()</a> to swap its real and effective user IDs, but were to
|
|
leave the saved set-user-ID unmodified, the process would then have an effective user ID equal to the original real user ID, and
|
|
both real and saved set-user-ID would be equal to the original effective user ID. In that state, the real user would be unable to
|
|
kill the process, even though the effective user ID of the process matches that of the real user, if the <a href=
|
|
"../functions/kill.html"><i>kill</i>()</a> behavior of _POSIX_SAVED_IDS was used. This is obviously not acceptable. The alternative
|
|
choice, which is used in at least one implementation, is to change the saved set-user-ID to the effective user ID during most calls
|
|
to <a href="../functions/setreuid.html"><i>setreuid</i>()</a>. The standard developers considered that alternative to be less
|
|
correct than the retention of the old behavior of <a href="../functions/kill.html"><i>kill</i>()</a> in such systems. Current
|
|
conforming applications shall accommodate either behavior from <a href="../functions/kill.html"><i>kill</i>()</a>, and there
|
|
appears to be no strong reason for <a href="../functions/kill.html"><i>kill</i>()</a> to check the saved set-user-ID rather than
|
|
the effective user ID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="getegid.html"><i>getegid</i>()</a> , <a
|
|
href="geteuid.html"><i>geteuid</i>()</a> , <a href="getgid.html"><i>getgid</i>()</a> , <a href="getuid.html"><i>getuid</i>()</a> ,
|
|
<a href="setegid.html"><i>setegid</i>()</a> , <a href="seteuid.html"><i>seteuid</i>()</a> , <a href=
|
|
"setgid.html"><i>setgid</i>()</a> , <a href="setregid.html"><i>setregid</i>()</a> , <a href="setreuid.html"><i>setreuid</i>()</a> ,
|
|
the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/sys/types.h.html"><i><sys/types.h></i></a>, <a href="../basedefs/unistd.h.html"><i><unistd.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_670_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>In the SYNOPSIS, the optional include of the <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> header is
|
|
removed.</p>
|
|
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The requirement to include <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> has been removed. Although <a
|
|
href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> was required for conforming implementations of previous POSIX
|
|
specifications, it was not required for UNIX applications.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The functionality associated with _POSIX_SAVED_IDS is now mandatory. This is a FIPS requirement.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following changes were made to align with the IEEE P1003.1a draft standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The effects of <i>setuid</i>() in processes without appropriate privileges are changed.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A requirement that the supplementary group list is not affected is added.</p>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|