/ 
Unix-SavedIDs-0.4.0
River stage zero No dependents
/ Unix::SetUser

NAME

Unix::SetUser - carefully drop root privileges

SYNOPSIS

	use Unix::SetUser;

	if ( $> != 0 ) {
		die "Run this as root!\n";
	}
	
	# do something with root privileges

	set_user('nobody');

	# do stuff without root privileges

DESCRIPTION

Dropping privileges is something that needs to be done right and can easily be done wrong. Even if you know how to do it right, it takes a lot of boring code.

About Saved IDs

Most modern unices have saved ids. This is a 3rd id type, so you have real user id, effective user id and now saved user id. (The same applies to groups). This means if you don't set your saved id, you really haven't dropped root privileges. Please see Unix::SavedIDs, the module used in Unix::SetUser to handle saved ids, for more information.

USAGE

set_user(new_user, [primary_group] , [supplemental_group ... ]);

This is the only function provided by Unix::SetUser. It is exported by default.

set_user() switches the uid, euid, suid, gid, egid, sgid and reduces the supplemental groups to those specified if any.

new_user is the user name or numeric user id of the user whom you wish the process to run as.

primary_group is the group name or numeric group id of the primary group. If undefined, the primary group of the user new_user is used.

supplemental_group is any group which you'd like the process to be a member of. If undefined, all supplemental group memberships are dropped.

All names and groups are assumed to be numeric uids and numeric gids if they are integers. Otherwise they are assumed to be user names or group names.

EXAMPLES

  • set_user('jdoe');

    Switch the uid, euid & suid to 'jdoe'. Switch the gid, egid & suid to jdoe's primary group (probably 'jdoe' or 'users' but maybe not.) Drop membership in any other groups.

  • set_user('jdoe','users,'tape');

    Switch the uid, euid & suid to 'jdoe'. Switch the gid, egid & sgid to 'users'. Add membership in the 'tape' group and drop membership in any other groups.

  • set_user('jdoe',undef,'tape');

    Switch the uid, euid & suid to 'jdoe'. Switch the gid, egid & sgid to jdoe's primary group (probably 'jdoe' or 'users' but maybe not.) Add membership in the 'tape' group and drop membership in any other groups.

DIAGNOSTICS

set_user() returns undef on success and croaks on failure.

DISCUSSION

Here's some of the gotchas involved in dropping privileges. These are all taken care of by Unix::SetUser

Make sure you drop group membership as well as changing user id.
Handle supplemental groups as well as the users primary group.
Set saved ids as well as real and effective ids.
Check to make sure ids really did change.
Check group membership without getting hung up about the order the groups are listed in.

PORTABILITY

This module will only work on unix-like systems which support saved ids. That is the vast majority of unices. I would like to add support for unices without saved ids and Windows, but I don't use those systems so I can't justify the time spent.

ACKNOWLEDGMENTS

After I wrote version 0.1, I discovered Proc::UID by Paul Fenwick. It does everything that this module does plus more. Sadly, its unmaintained since 2004 and the author specifically states that it is not for production code.

BUGS AND LIMITATIONS

This has only been tested on Linux and OpenBSD.

I assume you want uid == euid == suid and gid == euid == suid. If you don't Unix::SavedIds will let you manipulate all 3.

Please report any bugs or feature requests to bug-process-dropprivs@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Dylan Martin <dmartin@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2008, Dylan Martin & Seattle Central Community College <dmartin@cpan.org>.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

DISCLAIMER

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.