Proc::UID - Manipulate a variety of UID and GID settings.
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.
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.
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.
Proc::UID is designed with the following goals in mind:
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.
The following interface is the preferred method to manipulate a the UID/GID of a process.
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.
If privileges cannot be dropped, then the function will throw an exception.
drop_uid_temp
or drop_gid_temp
. It is equivilent
to setting the effective uid/gid to the saved uid/gid.
If Proc::UID is called with the :vars
parameter, the following
variables will be made available:
$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.
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.
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.
perlsec and perlvar
Setuid Demystified