The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Proc-UID-0.05
River stage zero No dependents
++
/ Proc::UID

NAME

Proc::UID - Manipulate a variety of UID and GID settings.

SYNOPSIS

        use Proc::UID qw(:vars);
        print "My saved-uid is $SUID, effective-uid is $EUID ",
              "my real-uid is $RUID\n";

        use Proc::UID qw(:funcs);
        print "Permanently dropping privs to $new_gid and $new_uid\n";
        drop_gid_perm($new_gid); # Throws an exception on failure.
        drop_uid_perm($new_uid); # Throws an exception on failure.

        print "Saved-UIDs are cached\n" if suid_is_cached();

WARNING

If your code is running with additional privileges, it is recommended that you always carefully test and audit your code, including this module if you use it.

This module is provided "as is", without warranty of any kind, either express or implied, including, but limited to, the implied warranties of merchantability and fitness for a particular purpose.

DESCRIPTION

Perl only has concepts of effective and real user-ids (UIDs) and group-ids (GIDs), accessible via the special variables $<, $>, $( and $). However most modern Unix systems also have a concept of saved UIDs.

This module provides a consistent and logical interface to real, effective, and saved UIDs and GIDs. It also provides a way to permanently drop privileges to that of a given user, a process which $< = $> = $uid does not guarantee, and the exact syntax of which may vary from between operating systems.

Proc::UID is also very pedantic about making sure that operations succeeded, and checking the value which it returns for a UID/GID really is the one that's being used. Perl may sometimes cache the values of $<, $>, $( and $), which means they can be wrong after being changed with low-level system calls.

Proc::UID provides both a variable and function interfaces to underlying UIDs.

DESIGN GOALS

Proc::UID is designed with the following goals in mind:

The interface should be easy to understand.

The traditional POSIX setuid function is notorious for being difficult to understand. The goal of Proc::UID is to provide an interface that is straightforward and easy to understand, and that operates in the same fashion regardless of operating system.

Mistakes should be difficult to make.

Any code that works with elevated privileges needs to be particularly careful with its actions. It would be a very Bad Thing if a program were to continue operating believing it had dropped privileges when it had not.

To best achieve this goal, Proc::UID will always check the success of any operation requested, and will generate an exception in the case of failure.

Proc::UID also provides a set of functions with very clear names that allow logical operations (temporarily drop privileges, permanently drop privileges, and regain privileges) to be performed. These logical operations are based upon the paper "Setuid demystified", by Hao Chen, David Wagner, and Drew Dean.

PREFERRED INTERFACE

The following interface is the preferred method to manipulate a the UID/GID of a process.

drop_uid_perm($uid) and drop_gid_perm($gid)

The drop_uid_perm and drop_gid_perm functions allow a program to permanently drop its privileges to the given $uid or $gid. It guarantees that the real, effective and saved uid/gid will be set to the argument supplied.

If drop_uid_perm or drop_gid_perm cannot drop privileges, then it will throw an exception.

drop_uid_temp($uid) and drop_gid_temp($gid)

These functions will allow privileges to be dropped in a temporary fashion. They have the effect of setting the effective uid to the supplied argument, and the saved uid to the previous effective uid. The real uid is not changed.

If privileges cannot be dropped, then the function will throw an exception.

restore_uid() and restore_gid()

These functions will allow you to restore a privilege previously dropped using drop_uid_temp or drop_gid_temp. It is equivilent to setting the effective uid/gid to the saved uid/gid.

VARIABLE INTERFACE

If Proc::UID is called with the :vars parameter, the following variables will be made available:

$EUID

This is the effective UID of the process. It is nominally the same as $>. However reading $EUID always results in the effective UID of the process being read. Setting $EUID will result in an exception being thrown if it does not succeed.

$RUID

As above, but for the real UID. Nominally the same as $<.

$SUID

As above, but for the saved UID. There is no equivilent special variable in Perl.

FUNCTIONAL INTERFACE

geteuid() / getegid()
getruid() / getrgid()
getsuid() / getsgid()

Return the effective, real, or saved user-id/group-id respectively. These functions will always make a system call to get the current value.

seteuid($uid) / setegid($gid)
setruid($uid) / setrgid($gid)
setsuid($uid) / setsgid($gid)

Set the effective, real, or saved user-id/group-id respectively. If the operation fails, an exception will be thrown.

suid_is_cached()

Not all systems support direct manipulation of the saved UID, or require use of system calls which Proc::UID does not yet understand.

Since the saved UID is always equal to the effective UID when a process starts, Proc::UID can infer the value of the saved UID even if it can't read it directly. If this is the case, then suid_is_cached will return true.

If suid_is_cached returns false, then you're running on a system where Proc::UID knows how to directly manipulate saved UIDs.

BUGS

Many operating systems have different interfaces into their extra UIDs. This module has not yet been tested under all of them.

The module does not manipulate or make available access to any other operating-system-specific privileges, such as the filesystem UID under Linux.

LICENSE

Copyright (c) 2004-2008 Paul Fenwick <pjf@cpan.org>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

TESTING STRATEGY

Proc::UID's testing strategy is intended to be very complete. Should any tests fail when building Proc::UID on your system, then it is recommended that you do not use Proc::UID, and report the failing tests to the author.

For complete testing, Proc::UID's tests need to run as root.

SEE ALSO

perlsec and perlvar

Perl Training Australia's Perl Security course manual, available from http://perltraining.com.au/notes.html

Setuid Demystified, http://www.cs.berkeley.edu/~hchen/paper/usenix02.html

Unix::SavedIDs, Unix::SetUser