.\" $Id: op-jacket.man,v 1.12 2012/09/07 15:07:02 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/op-jacket.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/op-jacket.7*
.TH OP-JACKET 7 LOCAL
.SH NAME
op-jacket \- description of the usage of a jacket (or helmet) under \fBop\fP

.SH SYNOPSIS
.ds PN "jacket
\fI\*(PN\fP [\fB\-C\fP\~config] [\fB\-f\fP\~\fIfile\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-P\fP\~\fIpid\fP] [\fB\-R\fP\~\fIroot\fP] [\fB\-u\fP\~\fIuser\fP] \fImnemonic\fP \fIprogram\fP \fIeuid\fP:\fIegid\fP \fIcred_type\fP:\fIcred\fP
.br
\fI\*(PN\fP \fB\-h\fP|\fB\-H\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
A \*(lqjacket\*(rq completes an additional step in the authorization of
a privilege escalation which \fBop\fP has already authenticated (and given
preliminary authorization).
A \*(lqhelmet\*(rq does exactly the same operation, but it \fBexit\fP(3)s
after the authorization, while the jacket waits for the
escalated command to \fBexit\fP to cleanup afterwards.

.P
For the purposes of this document we'll examine the jacket case,
a helmet just doesn't provide any cleanup, but takes the same
steps as a jacket.  All such programs support jacket mode, some
do not support helmet mode because they require a cleanup step.
.P
While a jacket may be run from the command line for testing, it
is mainly run from \fBop\fP(1l).  This is because \fBop\fP always provides
the command line options which describe the current escalation context.
That's what allows the jacket to continue the authorization of
the given escalation.  Providing all these options from
a script is much harder, mostly you have to make some of
them up (which weakens the credential's strength).
.P
The output of each process is a stream of \fBop\fP-specific commands, which
any other application would have no way to parse or understand.

.SH OPTIONS
Every jacket takes the same options.  Detailed specification of the
authorization required is always sent via the environment.
Since \fBop\fP's configuration markup is declarative, this best
maps that style to the task at hand.
.TP
.nf
\fB-C\fP \fIconfig\fP
.fi
Which \fBop\fP configuration file provided the specification for the rule.
This is usually an absolute path to the configuration file that
contained the definition of the rule \fBop\fP is using.  It won't be
an absolute path if the access file is configured as a relative path.
It may not be visible if the jacket \fBchroot\fP's, as the escalated
process does (see \fB\-R\fP below).
.sp
This could contain \fBmk\fP(1l) markup or other meta information.
The only sure thing about the file is that it is relatively secure.
If the access is in sentinel mode, the jacket may not even be allowed
to open the file (this is intended behavior).
.TP
.nf
\fB-f\fP \fIfile\fP
.fi
The file specification given to \fBop\fP, as an absolute path.  If you
have to check something about the contents of the file, this is the
place to do it.
.TP
.nf
\fB-g\fP \fIgroup\fP
.fi
The group specification given to \fBop\fP.
.TP
.nf
\fB-h\fP
.fi
Print a brief command-line help message.  Never used by \fBop\fP.
.TP
.nf
\fB-H\fP
.fi
Print a brief description of the environment parameters.
Never used by \fBop\fP.  Some jackets may not support this option.
.TP
.nf
\fB-P\fP \fIpid\fP
.fi
The process-id of the jacketed process (only as a jacket).
This is how a jacket knows that it is in "jacket mode".
If no \fB\-P\fP option is presented it should assume helmet
mode and exit EX_OK (0) to allow \fBop\fP to finish the escalation
process.
.TP
.nf
\fB-R\fP \fIroot\fP
.fi
The directory we \fBchroot\fP(2)'ed under.  Only set when a \fBchroot\fP is
requested.  To be clear, the jacket must \fBchroot\fP, if is needs to
see the filesystem as the escalated process does.
.sp
This might also be used to abort any authorization that requires access to
the superior environment.  For example, for logging actions taken.
.TP
.nf
\fB-u\fP \fIuser\fP
.fi
The user specification given to \fBop\fP
.TP
.nf
\fB-V\fP
.fi
Show version information.  Never used by \fBop\fP.
.TP
.nf
\fImnemonic\fP
.fi
The requested \fImnemonic\fP from \fBop\fP's command line.
.TP
.nf
\fIprogram\fP
.fi
The program mapped from the \fImnemonic\fP.  This will be given
to \fBexecve\fP if the escalation is allowed.
Repeating checks that are easy with \fB%_\fP or \fB!_\fP is never
a good idea.  Hiding checks (that should be in the configuration) in
a local jacket is Poor Form, at best.
In light of the \fIroot\fP option, there are three unique case to code:
.sp
The internal echo function is represented as a \fIprogram\fP that
is just the word \*(lqecho\*(rq.  No actual external program will
be executed.
.sp
Since the jacket is run outside of the new root: when a chroot is in
effect (under \fB\-R\fP) the path to the actual executable must be
computed by prepending the specified \fIroot\fP.  The \fBsigned\fP
jacket has the correct code to do this.
.sp
Otherwise the \fIprogram\fP path is correct as given.
.TP
.nf
\fIeuid\fP:\fIegid\fP
.fi
The computed effective \fIuid\fP and \fIgid\fP that will be assigned
before the execution of the process.
.TP
.nf
\fIcred_type\fP:\fIcred\fP
.fi
The credential type that granted access (groups, users, or netgroups),
plus the matching element.  The pseudo \fIcred_type\fP "test" is
used by my test drivers; always with the number of the test as the
\fIcred\fP.

.SH JACKETS
.P
Listed below are the jackets I use.  Feel free to submit others that
you believe are useful.
.TP
.nf
\fBcoat\fP
.fi
Apply a list of jackets to this escalation.  This provides an
environment that allows each listed jacket to provide a "thumbs up"
(or down) for the escalation.  Only when all allow the escalation will
it occur.  Each is also given an exit code to process.  This is
actually a pretty hard trick, so you'd better be impressed.
.TP
.nf
\fBenvauth\fP
.fi
Checks for the existence and value of environment variables.  The
values are checked against an RE match (ENVAUTH_VAR_\fIname\fP=\fIRE\fP)
or against a non-match (ENVAUTH_NOT_\fIname\fP=\fIRE\fP).
.TP
.nf
\fBproxy-agent\fP
.fi
Forwards the original \fBssh-agent\fP environment to the escalated
process by creating a socket that proxies all connections.  This
avoid the checks in OpenSsh that think that file permissions are
not good enough.
.TP
.nf
\fBsheval\fP
.fi
Set environment variables to the shell evaluation a command.
See \fBsheval\fP(7l).
.TP
.nf
\fBsigned\fP
.fi
Compare the proposed executable to a checksum or hash value.  See
\fBsigned\fP(7l)
.TP
\fBstamp\fP
Allow an authentication stamp to hold credentials for future (or
parallel) escalations.  This is very much like \fBsudo\fP's
\*(lqtimestamp\*(rq feature.  This requires that the command below be run as
the superuser at system boot:
.nf
	/usr/local/libexec/jacket/stampctl \fIfacility-dirs\fP
.fi
See \fBstampctl\fP(8l) for details on usage.
.TP
.nf
\fBtimebox\fP
.fi
Check the current time.  A specification my use any \fBstrftime\fP(3) format
to produce an inequality that must be true.
Some commands may only be allowed after hours, or on weekends.
This is out-sourced from \fBop\fP so that
local policy can be detailed.  Commands may be limited to a box
with $\fBTIMEBOX_INSIDE\fP or outside a box with $\fBTIMEBOX_FORBID\fP.
.TP
.nf
\fBwrope\fP
.fi
Allows an escalated process to see the client's wrapper diversions.
.TP
.nf
\fBxdisplay\fP
.fi
Does the \fBxauth\fP copy to allow an escalated process to access the
original login's $\fBDISPLAY\fP.  The the home directory for the
logins is the same no action is taken.

.SH EXAMPLES
.PD 0
.TP
.nf
/usr/local/libexec/jacket/envauth \-V
.fi
Output the version and environment parameters for the
environment authorization jacket.
.sp
.TP
.nf
( sleep 5 & \e
.nf
.TP
.nf
ENVAUTH_VAR_XTERM_LOCALE=. ENVAUTH_NOT_XTERM_LOCALE='^polish$' \e
.fi
.TP
.nf
exec /usr/local/libexec/jacket/envauth \-P $! \-\- \e
.fi
.TP
.nf
  true /usr/bin/true 0:0 test:case1 )
.fi
Run a test for the environment authorization jacket, which should
succeed, for me, since the value of $XTERM_LOCALE is \*(lqC\*(rq
not \*(lqpolish\*(rq.
This fails when the variable is unset as well.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/timebox $TIMEBOX_INSIDE=000000<=%H%M%s<045960
.fi
Limit this escalation window from midnight to before 05:00, from the
\fBop\fP configuration file.
.TP
.nf
/usr/local/sbin/stampctl \-M ecru/$l \-E 10m TTY=$y ; ...
.fi
Enable an authorization stamp for 10 minutes.  Note there is
usually a link from sbin/stampctl to the libexec/jacket/stampctl
location.  This makes it much easier for the admin to find the
application.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/stamp $STAMP_SPEC=ecru/$l:TTY=$y
.fi
This escalation requires that the login be on the same controlling tty
as when the stamp was created for the \*(lqecru\*(rq facility.
.sp
.TP
jacket=/usr/local/libexec/jacket/xdisplay
Forward the current X display to the inferior process.  This does
write in the home directory of the target login, but that's the
only way to do it.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/coat COAT=stamp,xdisplay
.fi
Wrap 2 jackets around the process.  Both have the same effect as
they would if they were the only jackets in the stack.  This is
a really hard trick, but \fBcoat\fP does it.
.PD 1

.SH BUGS
.P
Any \fBchroot\fP can ruin your day.
.P
There is no \fBjail\fP access for FreeBSD platforms.

.SH AUTHOR
K S Braunsdorf, from the Non-Player Character Guild
.br
op at-not-a-spammer ksb dot npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), op(1l), sudo(1), coat(7l), sheval(7l), signed(7l),
stamp(7l), stampctl(8l),
proxy-agent(7l), wrope(7l)