'\" t
.\"     Title: uid_wrapper
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 2015-11-03
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "UID_WRAPPER" "1" "2015\-11\-03" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
uid_wrapper \- A wrapper to fake privilege separation
.SH "SYNOPSIS"
.sp
LD_PRELOAD=libuid_wrapper\&.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 \fB\&./myapplication\fR
.SH "DESCRIPTION"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Allows uid switching as a normal user\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Start any application making it believe it is running as root\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Support for user/group changing in the local thread using the syscalls (like glibc)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
More precisely this library intercepts seteuid and related calls, and simulates them in a manner similar to the nss_wrapper and socket_wrapper libraries\&.
.RE
.sp
Some projects like a file server need privilege separation to be able to switch to the connection user and do file operations\&. uid_wrapper convincingly lies to the application letting it believe it is operating as root and even switching between UIDs and GIDs as needed\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBUID_WRAPPER\fR
.RS 4
If you load the uid_wrapper and enable it with setting UID_WRAPPER=1 all setuid and setgid will work, even as a normal user\&.
.RE
.PP
\fBUID_WRAPPER_ROOT\fR
.RS 4
It is possible to start your application as fake root with setting UID_WRAPPER_ROOT=1\&.
.RE
.PP
\fBUID_WRAPPER_DEBUGLEVEL\fR
.RS 4
If you need to see what is going on in uid_wrapper itself or try to find a bug, you can enable logging support in uid_wrapper if you built it with debug symbols\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
0 = ERROR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 = WARNING
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
2 = DEBUG
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
3 = TRACE
.RE
.RE
.PP
\fBUID_WRAPPER_MYUID\fR
.RS 4
This environment variable can be used to tell uid_wrapper to let geteuid() return the real (instead of the faked) UID of the user who started the process with uid_wrapper\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
uid_t uid;

setenv("UID_WRAPPER_MYUID", "1", 1);
uid = geteuid();
unsetenv("UID_WRAPPER_MYUID");
.fi
.if n \{\
.RE
.\}
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
$ LD_PRELOAD=libuid_wrapper\&.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 id
uid=0(root) gid=0(root) 0(root)
.fi
.if n \{\
.RE
.\}
.SH "WORKAROUNDS"
.sp
If you need to write code that behaves differently depending on whether uid_wrapper is enabled or not, for example in cases where you have to file permissions, you can predefine the uid_wrapper_enabled() function in your project as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
bool uid_wrapper_enabled(void)
{
    return false;
}
.fi
.if n \{\
.RE
.\}
.sp
Since uid_wrapper overloads this function if enabled, you can use it in your code to detect uid_wrapper\&.