.\" $NetBSD: setuid.7,v 1.5 2009/03/09 19:24:31 joerg Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Henry Spencer <henry@spsystems.net>.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 26, 2009
.Dt SETUID 7
.Os
.Sh NAME
.Nm setuid
.Nd checklist for security of setuid programs
.Sh DESCRIPTION
.Em Please note :
This manual page was written long ago, and is in need of updating to
match today's systems.
We think it is valuable enough to include, even though parts of it
are outdated.
A carefully-researched updated version
would be very useful, if anyone is feeling enthusiastic...
.Pp
Writing a secure setuid (or setgid) program is tricky.
There are a number of possible ways of subverting such a program.
The most conspicuous security holes occur when a setuid program is
not sufficiently careful to avoid giving away access to resources
it legitimately has the use of.
Most of the other attacks are basically a matter of altering the program's
environment in unexpected ways and hoping it will fail in some
security-breaching manner.
There are generally three categories of environment manipulation:
supplying a legal but unexpected environment that may cause the
program to directly do something insecure,
arranging for error conditions that the program may not handle correctly,
and the specialized subcategory of giving the program inadequate
resources in hopes that it won't respond properly.
.Pp
The following are general considerations of security when writing
a setuid program.
.Bl -bullet
.It
The program should run with the weakest userid possible, preferably
one used only by itself.
A security hole in a setuid program running with a highly-privileged
userid can compromise an entire system.
Security-critical programs like
.Xr passwd 1
should always have private userids, to minimize possible damage
from penetrations elsewhere.
.It
The result of
.Xr getlogin 2
or
.Xr ttyname 3
may be wrong if the descriptors have been meddled with.
There is
.Em no
foolproof way to determine the controlling terminal
or the login name (as opposed to uid) on V7.
.It
On some systems, the setuid bit may not be honored if
the program is run by root,
so the program may find itself running as root.
.It
Programs that attempt to use
.Xr creat 3
for locking can foul up when run by root;
use of
.Xr link 2
is preferred when implementing locking.
Using
.Xr chmod 2
for locking is an obvious disaster.
.It
Breaking an existing lock is very dangerous; the breakdown of a locking
protocol may be symptomatic of far worse problems.
Doing so on the basis of the lock being
.Sq old
is sometimes necessary,
but programs can run for surprising lengths of time on heavily-loaded
systems.
.It
Care must be taken that user requests for I/O are checked for
permissions using the user's permissions, not the program's.
Use of
.Xr access 2
is recommended.
.It
Programs executed at user request (e.g. shell escapes) must
not receive the setuid program's permissions;
use of daughter processes and
.Dq setuid(getuid())
plus
.Dq setgid(getgid())
after
.Xr fork 2
but before
.Xr exec 3
is vital.
.It
Similarly, programs executed at user request must not receive other
sensitive resources, notably file descriptors.
Use of
.Xr fcntl 2
.Dv F_CLOSEM ,
.Dv FILENO_STDERR + 1
(close all fd's greater than stderr)
and/or
.Xr fcntl 2
.Dv F_SETFD ,
.Dv FD_CLOEXEC
(close-on-exec) arrangements
on systems which have them
is recommended.
.Pp
Other resources should also be examined for sanity and possibly set to
desired settings, such as the current working directory, signal disposition,
resource limits, environment, umask, group membership, chroot.
.Pp
Programs activated by one user but handling traffic on behalf of
others (e.g. daemons) should avoid doing
.Dq setuid(getuid())
or
.Dq setgid(getgid()) ,
since the original invoker's identity is almost certainly inappropriate.
On systems which permit it, use of
.Dq setuid(geteuid())
and
.Dq setgid(getegid())
is recommended when performing work on behalf of the system as
opposed to a specific user.
.It
There are inherent permission problems when a setuid program executes
another setuid program,
since the permissions are not additive.
Care should be taken that created files are not owned by the wrong person.
Use of
.Dq setuid(geteuid())
and its gid counterpart can help, if the system allows them.
.It
Care should be taken that newly-created files do not have the wrong
permission or ownership even momentarily.
Permissions should be arranged by using
.Xr umask 2
in advance, rather than by creating the file wide-open and then using
.Xr chmod 2 .
Ownership can get sticky due to the limitations of the setuid concept,
although using a daughter process connected by a pipe can help.
.It
Setuid programs should be especially careful about error checking,
and the normal response to a strange situation should be termination,
rather than an attempt to carry on.
.El
.Pp
The following are ways in which the program may be induced to carelessly
give away its special privileges.
.Bl -bullet
.It
The directory the program is started in, or directories it may
plausibly
.Xr chdir 2
to, may contain programs with the same names as system programs,
placed there in hopes that the program will activate a shell with
a permissive
.Ev PATH
setting.
.Ev PATH
should
.Em always
be standardized before invoking a shell
(either directly or via
.Xr popen 3
or
.Xr execvp 3
or
.Xr execlp 3 ) .
.It
Similarly, a bizarre
.Ev IFS
setting may alter the interpretation of a shell command in really
strange ways, possibly causing a user-supplied program to be invoked.
.Ev IFS
too should always be standardized before invoking a shell.
.It
Environment variables in general cannot be trusted.
Their contents should never be taken for granted.
.It
Setuid shell files (on systems which implement such) simply cannot
cope adequately with some of these problems.
They also have some nasty problems like trying to run a
.Pa \&.profile
when run under a suitable name.
They are terminally insecure, and must be avoided.
.It
Relying on the contents of files placed in publically-writable
directories, such as
.Pa /tmp ,
is a nearly-incurable security problem.
Setuid programs should avoid using
.Pa /tmp
entirely, if humanly possible.
The sticky-directories modification (sticky bit on for a directory means
only owner of a file can remove it) helps,
but is not a complete solution.
.It
A related problem is that
spool directories, holding information that the program will trust
later, must never be publically writable even if the files in the
directory are protected.
Among other sinister manipulations that can be performed, note that
on many Unixes, a core dump of a setuid program is owned
by the program's owner and not by the user running it.
.El
.Pp
The following are unusual but possible error conditions that the
program should cope with properly (resource-exhaustion questions
are considered separately, see below).
.Bl -bullet
.It
The value of
.Ar argc
might be 0.
.It
The setting of the
.Xr umask 2
might not be sensible.
In any case, it should be standardized when creating files
not intended to be owned by the user.
.It
One or more of the standard descriptors might be closed, so that
an opened file might get (say) descriptor 1, causing chaos if the
program tries to do a
.Xr printf 3 .
.It
The current directory (or any of its parents)
may be unreadable and unsearchable.
On many systems
.Xr pwd 1
does not run setuid-root,
so it can fail under such conditions.
.It
Descriptors shared by other processes (i.e., any that are open
on startup) may be manipulated in strange ways by said processes.
.It
The standard descriptors may refer to a terminal which has a bizarre
mode setting, or which cannot be opened again,
or which gives end-of-file on any read attempt, or which cannot
be read or written successfully.
.It
The process may be hit by interrupt, quit, hangup, or broken-pipe signals,
singly or in fast succession.
The user may deliberately exploit the race conditions inherent
in catching signals;
ignoring signals is safe, but catching them is not.
.It
Although non-keyboard signals cannot be sent by ordinary users in V7,
they may perhaps be sent by the system authorities (e.g. to
indicate that the system is about to shut down),
so the possibility cannot be ignored.
.It
On some systems there may be an
.Xr alarm 3
signal pending on startup.
.It
The program may have children it did not create.
This is normal when the process is part of a pipeline.
.It
In some non-V7 systems, users can change the ownerships of their files.
Setuid programs should avoid trusting the owner identification of a file.
.It
User-supplied arguments and input data
.Em must
be checked meticulously.
Overly-long input stored in an array without proper bound checking
can easily breach security.
When software depends on a file being in a specific format, user-supplied
data should never be inserted into the file without being checked first.
Meticulous checking includes allowing for the possibility of non-ASCII
characters.
.It
Temporary files left in public directories like
.Pa /tmp
might vanish at inconvenient times.
.El
.Pp
The following are resource-exhaustion possibilities that the
program should respond properly to.
.Bl -bullet
.It
The user might have used up all of his allowed processes, so
any attempt to create a new one (via
.Xr fork 2
or
.Xr popen 3 )
will fail.
.It
There might be many files open, exhausting the supply of descriptors.
Running
.Xr fcntl 2
.Dv F_CLOSEM
on systems which have it,
is recommended.
.It
There might be many arguments.
.It
The arguments and the environment together might occupy a great deal
of space.
.El
.Pp
Systems which impose other resource limitations can open setuid
programs to similar resource-exhaustion attacks.
.Pp
Setuid programs which execute ordinary programs without reducing
authority pass all the above problems on to such unprepared children.
Standardizing the execution environment is only a partial solution.
.Sh SEE ALSO
.Xr passwd 1 ,
.Xr pwd 1 ,
.Xr access 2 ,
.Xr chdir 2 ,
.Xr chroot 2 ,
.Xr execve 2 ,
.Xr fcntl 2 ,
.Xr fork 2 ,
.Xr getlogin 2 ,
.Xr link 2 ,
.Xr setegid 2 ,
.Xr seteuid 2 ,
.Xr setgid 2 ,
.Xr setgroups 2 ,
.Xr setrlimit 2 ,
.Xr setuid 2 ,
.Xr sigaction 2 ,
.Xr umask 2 ,
.Xr alarm 3 ,
.Xr creat 3 ,
.Xr execvp 3 ,
.Xr popen 3 ,
.Xr printf 3 ,
.Xr ttyname 3
.Sh HISTORY
Written by Henry Spencer, and based on additional outside contributions.
.Sh AUTHORS
.An Henry Spencer Aq henry@spsystems.net
.Sh BUGS
The list really is rather long...
and probably incomplete.