STAMP(7)                                                              STAMP(7)



NAME
       stamp - jacket to check stamp authorization criteria

SYNOPSIS
       stamp  [-C  config]  [-f  file]  [-g group] [-m mac] [-P pid] [-R root]
       [-u user] mnemonic program euid:egid cred_type:cred
       stamp -h
       stamp -H
       stamp -V

DESCRIPTION
       The op(1l) privilege escalation  application  authenticates  the  login
       name  (uid),  group  membership  (gid),  or  netgroup membership of the
       invoker, then might request more authentication via  pam(3),  to  grant
       escalated access.

       This model implies that just knowing who someone is grants them access.
       That is to say, op by default authenticates the  invoker,  but  doesn't
       look  for  any  authorization.  Authorization is out-sourced to jackets
       (or helmets).

       Stamp looks for  a  previously  created  authorization  socket  in  the
       filesystem  of  the  local  host.   That  socket  is usually created by
       stampctl(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.

       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
       "approval steps" above must be  represented  by  a  unique  path  in  a
       trusted  directory the filesystem, which is specified to stampctl under
       the -M option.  Each step should depend on the previous  one  by  using
       this jacket to assure that the supporting authorization is presently in
       effect.

       The command-line usage maps to the jacket  interface  used  by  op(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.

ENVIRONMENT
       All  jackets have the same command-line options, because op creates the
       command-line from a set of fixed options and some copied from its  com-
       mand-line.   So the specification of the requests authorization is sent
       to the jacket via environment variables.  Each jacket  documents  these
       under  -H.   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.)

       $STAMP_FACILITY=facility
              There  is  a  default location prefix (set by local site policy)
              which defaults to /var/op 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.

       $STAMP_SPEC=spec
              This is the key specification for a stamp request.   The  format
              of the value is:
                   stamp[:nameOPvalue]*
              Where  stamp  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.

              Any name specification must be present in the tableau (see stam-
              pctl(8l)). The OP operator may be any of =, !  (string  equality
              or  inequality),  ==, !=, <, <=, >, >= (integer comparison), =~,
              !~ (regular expression matches). Each requires the stated  rela-
              tionship  between  the  tableau entry and the given value.  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.

              An existence check is implied if the name is offered alone.

              In truth, more than a single variable may be set with the prefix
              "STAMP_SPEC":  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 coat(7l) to create 2 instances of stamp, which requires some
              reveal logic.

       $STAMP_SET=tableau[:tableau]...
              Recover  the  tableau entry as an environment entry in the esca-
              lated process's environment.  This allows  in-line  scripts  and
              applications to read the tableau for clues.

       $STAMP_REVEAL=prefix
              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.

       $STAMP_WARN=message
              When the stamp doesn't exist, denies the authorization, or is in
              penalty mode the message replaces the ubiquious "Sorry" message.

OPTIONS
       -C config
              Which op configuration file sourced the rule.

       -f file
              The file specification given to op, as an absolute path.

       -g group
              The group specification given to op

       -h
              Print a brief help message.

       -H
              Only output an explaination the environment interface available.

       -m mac
              The (complete) MAC label to be assigned to the process.

       -P pid
              The process-id of the jacketed process (only as a jacket).  When
              stamp  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).

       -R root
              The directory we shall chroot under.

       -u user
              The user specification given to op.

       -V
              Output only the version of the program, then exit.

EXAMPLES
       We'll assume that $PATH includes the local  jacket  directory  (usually
       /usr/local/libexec/jacket) for these examples.

       stamp -V
              Output the standard version information.

       stamp -H
              Output  a  help message with detail so the the environment vari-
              able that specify the authorization required,  and  their  local
              default values.

       export STAMP_SPEC=${USER:-${LOGIN}}:TTY='tty'
              Set a request to authorize the current login on this tty.  While
              it is seldom necessary to mock op, the might be used in a  shell
              script as such:
                   if stamp -- true /bin/true 0:0 myself:ok >/dev/null ; then
                        # yay, we are authorized
                   else
                        # sadly, we are not clear to proceed
                   fi
              The  specification after the double-dash is required to mock the
              protocol op 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).

       $STAMP_SPEC=puma/$l:TTY=$y  jacket=/usr/local/libexec/jacket/stamp
              This is the op 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.

       mnemonic  stampctl -M puma/$l -I 90m TTY=$y ;  users=...
              The  op target command that might have built the puma stamp file
              for the last example.

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

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

SEE ALSO
       op(1l), sh(1), op-jacket(7l), stampctl(8l), pam(3), login(1), coat(7l)



                                     LOCAL                            STAMP(7)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | OPTIONS | EXAMPLES | BUGS | AUTHOR | SEE ALSO