================================================================================

This package contains the suidgw utility

Copyright (c) 2013 Martin Mares <mj@ucw.cz>

All files in this package can be freely distributed and used according
to the terms of the GNU General Public License, either version 2 or
(at your opinion) any newer version. This is the same distribution
policy as for the Linux kernel itself -- see /usr/src/linux/COPYING
for details.

================================================================================


For many years, I have been happily using suidperl to let ordinary users run
various scripts with elevated privileges. However, suidperl is not supported
on current systems any longer. Therefore I have written a simple wrapper,
which can be used to emulate setuid/setgid on scripts written in any language.


Theory of operation
~~~~~~~~~~~~~~~~~~~

  o  /usr/bin/suidgw is the gateway binary, installed setuid root.

  o  /usr/lib/suidgw/$SCRIPT is the script to be run, installed with
     an appropriate combination of setuid/setgid bits (as if it were
     a binary program). Note that Linux kernel ignores setuid/setgid
     on scripts, so running the scripts manually does no harm.
     [Alternatively, /usr/local/lib/suidgw/$SCRIPT can be used.]

  o  /usr/bin/$SCRIPT is a symlink to /usr/bin/suidgw.
     [Or use any other directory accessible to ordinary users.]

  o  When a user executes suidgw via the symlink, it parses argv[0],
     determines which $SCRIPT was called and checks that the name looks sane.

  o  The suidgw finds /usr/lib/suidgw/$SCRIPT and checks that the current
     (real) user is allowed to run it.

  o  Then it switches real, effective, and saved UID and runs the script.
     Environment variables are sanitized (currently, the whole environment
     is reset; in the future, we may propagate some variables if needed)
     and so are file descriptors (we make sure that fd's 0 to 2 exist).

  o  The action is logged to the syslog (facility auth, level info).


CAVEAT: We do not emulate proper POSIX real/effective/saved UID semantics,
because when a recent Perl interpreter detects that real != effective, it
refuses to run. Therefore we set all three UIDs and GIDs to the new effective
user/group and record the ID's of the caller in environment variables ORIG_UID
and ORIG_GID. Still, Linux kernel notices the UID changes and marks the task
as undumpable, so this should be secure.