.\" $Id: stamp.man,v 1.10 2012/10/19 17:34:31 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall -D DESTDIR=${DESTDIR} %o %f && cp %f ${DESTDIR}/usr/local/man/man7/stamp.7
.\" $Deinstall: ${rm-rm} -f ${DESTDIR}/usr/local/man/man7/stamp.7*
.TH STAMP 7 LOCAL
.SH NAME
stamp - jacket to check stamp authorization criteria
.SH SYNOPSIS
.ds PN "stamp
\fI\*(PN\fP [\fB\-C\fP\~\fIconfig\fP] [\fB\-f\fP\~\fIfile\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-m\fP\~\fImac\fP] [\fB\-P\fP\~\fIpid\fP] [\fB\-R\fP\~\fIroot\fP] [\fB\-u\fP\~\fIuser\fP] \fImnemonic\fP \fIprogram\fP \fIeuid:egid\fP \fIcred_type:cred\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-H\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
The \fBop\fP(1l) privilege escalation application authenticates the
login name (uid), group membership (gid), or netgroup membership of
the invoker, then might request more authentication via \fBpam\fP(3),
to grant escalated access.
.P
This model implies that just knowing \fBwho\fP
someone is grants them access.  That is to say, \fBop\fP by default
authenticates the invoker, but doesn't look for any authorization.
Authorization is out-sourced to jackets (or helmets).
.P
.hlm 0
\fIStamp\fP looks for a previously created authorization socket in
the filesystem of the local host.  That socket is usually created by
\fBstampctl\fP(8l) to represent the specific approval of another person
or application for a specific login, group, or netgroup.
Without the requested stamp's authorization the proposed access fails.
.hlm 1
.P
The chain of approvals may be arbitrarily long.  An operations manager
may approve a change request for many tickets, the owners of those
tickets may approve many changes, the workers doing those changes may
have a limited window to act on the approved work.  Each of the
\*(lqapproval steps\*(rq above must be represented by a unique
path in a trusted directory the filesystem, which is specified
to \fBstampctl\fP under the \fB\-M\fP option.  Each step should
depend on the previous one by using this jacket to assure that
the supporting authorization is presently in effect.
.P
The command-line usage maps to the jacket interface used by
\fBop\fP(1l).  There is almost no usage of this jacket directly
from an interactive shell, and little usage from scripts.
See op-jacket(7l) for a complete descriptions of
the option specification and usage.

.SH ENVIRONMENT

All jackets have the same command-line options, because \fBop\fP
creates the command-line from a set of fixed options and some
copied from its command-line.  So the specification of the requests
authorization is sent to the jacket via environment variables.
Each jacket documents these under \fB\-H\fP.  We also explain them
in detail below.  (N.B.: local site policy may change the
default values or even the names of these, so look at the run-time
list to confirm this information.)

.TP
.nf
$STAMP_FACILITY
.fi
There is a default location prefix (set by local site policy) which defaults
to \fB/var/op\fP for all stamps.  After that path there is usually a
facility name followed by the token for the requesting person.
This environment variable changes the name of the facility, while
STAMP_SPEC (below) specifies the specific stamp required.
.TP
.nf
$STAMP_SPEC
.fi
This is the key specification for a \fI\*(PN\fP request.  The format of
the value is:
.nf
	\fIstamp\fP[:\fIname\fP\fIOP\fP\fIvalue\fP]*
.fi
Where \fIstamp\fP is the path under the facility specified above
to the requester's stamp file.  The name is usually composed of
either the login name, a group name, or both with an optional
prefix.  For example "puma/ksb" might be used for my login's
permission to escalation command for the "puma" application.
.sp
Any \fIname\fP specification must be present in
the tableau (see \fBstampctl\fP(8l)). The \fIOP\fP operator may
be any of \fB=\fP, \fB!\fP (string equality or inequality),
\fB==\fP, \fB!=\fP, \fB<\fP, \fB<=\fP, \fB>\fP, \fB>=\fP (integer comparison),
\fB=~\fP, \fB!~\fP (regular expression matches). Each requires the
stated relationship between the tableau entry and the given \fIvalue\fP.
This feature allows the authorization to be limited to a known tty,
as specific directory or file, or any other item that might
be represented as a fixed string.
.sp
An existence check is implied if the \fIname\fP is offered alone.
.sp
In truth, more than a single variable may be set with the prefix
\*(lqSTAMP_SPEC\*(rq: they must all match, the last one in alpha-order
is the one used by the jacket code to reauthenticate.  This is
only needed when 2 different authorities must conspire to allow
a third party to take action, and the order of their actions is unknown.
Another way to require 2 authorizations would be to use \fBcoat\fP(7l)
to create 2 instances of \fI\*(PN\fP, which requires some reveal logic.
.TP
.nf
$STAMP_REVEAL
.fi
Most jackets have a reveal specification.  The removes a prefix from
every matching environment variable.  If the prefix is "CAT_" and
there is a $CAT_PATH in the escalated environment the entry will be
renamed "PATH".  This allows the jacket to have a different $PATH
than the escalated program.
.TP
.nf
$STAMP_WARN
.fi
When the stamp doesn't exist, denys the authorization, or is in penalty
mode the message replaces the ubiquious \*(lqSorry\*(rq message.


.SH OPTIONS
.TP
.nf
\fB\-C\fP \fIconfig\fP
.fi
Which \fBop\fP configuration file sourced the rule.
.TP
.nf
\fB\-f\fP \fIfile\fP
.fi
The file specification given to \fBop\fP, as an absolute path.
.TP
.nf
\fB\-g\fP \fIgroup\fP
.fi
The group specification given to \fBop\fP
.TP
.nf
\fB\-h\fP
.fi
Print a brief help message.
.TP
.nf
\fB\-H\fP
.fi
Explain the usage of this jacket.
.TP
.nf
\fB\-m\fP \fImac\fP
.fi
The (complete) MAC label to be assigned to the process.
.TP
.nf
\fB\-P\fP \fIpid\fP
.fi
The process-id of the jacketed process (only as a jacket).
When \fI\*(PN\fP is used as a jacket it attempts to prevent
the timeout of the authorizing stamp.  It reconnects to the
stamp about 69% of the way through the idle timeout to request
a status update (which it ignores).
.TP
.nf
\fB\-R\fP \fIroot\fP
.fi
The directory we shall chroot under.
.TP
.nf
\fB\-u\fP \fIuser\fP
.fi
The user specification given to \fBop\fP.
.TP
\fB\-V\fP
.nf
Show version information.
.fi

.SH EXAMPLES

We'll assume that $PATH includes the local jacket directory
(usually \fB/usr/local/libexec/jacket\fP) for these examples.
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output the standard version information.
.TP
.nf
\fI\*(PN\fP \-H
.fi
Output a help message with detail so the the environment variable that
specify the authorization required, and their local default values.
.TP
.nf
export STAMP_SPEC=${USER:-${LOGIN}}:TTY=`tty`
.fi
Set a request to authorize the current login on this tty.
While it is seldom necessary to mock \fBop\fP, the might be used in
a shell script as such:
.nf
	if \fI\*(PN\fP \-\- true /bin/true 0:0 myself:ok >/dev/null ; then
		# yay, we are authorized
	else
		# sadly, we are not clear to proceed
	fi
.fi
The specification after the double-dash is required to mock the
protocol \fBop\fP uses to call the jacket.  In this context these
mandatory parameters are mostly ignored, but may be checked for
their format (viz. a number must be composed of digits).
.TP
.fi
$STAMP_SPEC=puma/$l:TTY=$y  jacket=/usr/local/libexec/jacket/stamp
.fi
This is the \fBop\fP configuration line to request an authorization
for the customer against the puma/$LOGIN stamp with a matching tty.
The matching tty prevents others with access to the same account to
piggy-back on the authorization.
.TP
.nf
\fImnemonic\fP	\fBstampctl\fP \-M puma/$l \-I 90m TTY=$y ;  users=...
.fi
The \fBop\fP target command that might have built the puma stamp
file for the last example.

.SH BUGS
The protocol used between the control program and this jacket is
undocumented for this version, as I plan to change it in the next.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
stamp at ksb.npcguild Dot org

.SH "SEE ALSO"
.hlm 0
op(1l), sh(1), op-jacket(7l), stampctl(8l), pam(3), login(1), coat(7l),
road(8l)