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.


WARNING

This release of Proc::UID is for testing and review purposes only. Please do not use it in production code. The interface may change, and the underlying code has not yet been rigourously tested.

If you discover any of the included tests fail, or that any other problems with the code, please contact Paul Fenwick, pjf@cpan.org.


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() / getsuid()
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.


BUGS

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

The current implementation of this module assumes the presence of a setresuid call. This does not exist on all operating systems.

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


AUTHOR

Paul Fenwick pjf@cpan.org

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


SEE ALSO

perlsec and perlvar

Setuid Demystified