README

   1 ================================================================================
   2
   3 This package contains the suidgw utility
   4
   5 Copyright (c) 2013-2022 Martin Mares <mj@ucw.cz>
   6
   7 All files in this package can be freely distributed and used according
   8 to the terms of the GNU General Public License, either version 2 or
   9 (at your opinion) any newer version. This is the same distribution
  10 policy as for the Linux kernel itself -- see /usr/src/linux/COPYING
  11 for details.
  12
  13 ================================================================================
  14
  15
  16 For many years, I have been happily using suidperl to let ordinary users run
  17 various scripts with elevated privileges. However, suidperl is not supported
  18 on current systems any longer. Therefore I have written a simple wrapper,
  19 which can be used to emulate setuid/setgid on scripts written in any language.
  20
  21
  22 Theory of operation
  23 ~~~~~~~~~~~~~~~~~~~
  24
  25   o  /usr/bin/suidgw is the gateway binary, installed setuid root.
  26
  27   o  /usr/lib/suidgw/$SCRIPT is the script to be run, installed with
  28      an appropriate combination of setuid/setgid bits (as if it were
  29      a binary program). Note that Linux kernel ignores setuid/setgid
  30      on scripts, so running the scripts manually does no harm.
  31      [Alternatively, /usr/local/lib/suidgw/$SCRIPT can be used.]
  32
  33   o  /usr/bin/$SCRIPT is a symlink to /usr/bin/suidgw.
  34      [Or use any other directory accessible to ordinary users.]
  35
  36   o  When a user executes suidgw via the symlink, it parses argv[0],
  37      determines which $SCRIPT was called and checks that the name looks sane.
  38
  39   o  The suidgw finds /usr/lib/suidgw/$SCRIPT and checks that the current
  40      (real) user is allowed to run it.
  41
  42   o  Then it switches real, effective, and saved UID and runs the script.
  43      Environment variables are sanitized (currently, the whole environment
  44      is reset; in the future, we may propagate some variables if needed)
  45      and so are file descriptors (we make sure that fd's 0 to 2 exist).
  46
  47   o  The action is logged to the syslog (facility auth, level info).
  48
  49
  50 CAVEAT: We do not emulate proper POSIX real/effective/saved UID semantics,
  51 because when a recent Perl interpreter detects that real != effective, it
  52 refuses to run. Therefore we set all three UIDs and GIDs to the new effective
  53 user/group and record the ID's of the caller in environment variables ORIG_UID
  54 and ORIG_GID. Still, Linux kernel notices the UID changes and marks the task
  55 as undumpable, so this should be secure.