ROAPMUX(7)                                                          ROAPMUX(7)



NAME
       roapmux - provide an authorization tableau to specific network clients

SYNOPSIS
       roapmux  [-Mx]  [-C  configs]  [-E  hxmd]  [-L  hxmd-libs] [-R reverse]
       [-X ex-config] [-Z zero-config] [envs] [generator]
       roapmux -h
       roapmux -V [envs] [generator]

DESCRIPTION
       The Remote Op Authorization  Protocol  service  provides  authorization
       advice  to  local network peers, usually driven by the setup of a stam-
       pctl authorization stamp.  This  service  runs  under  tcpmux  (usually
       under  inetd)  on an authorization host to distribute custom authoriza-
       tion tableaus to specific network clients.  Each stream appears (to the
       client)  to  be  a  valid stampctl(8l) tableau.  The stampctl option -R
       specifies and authorization host, which should provide this service, or
       one supporting the same API.

       Authorization  requests  via  stamp(7l)  fetch  a tableau which is com-
       pletely indistinguishable from a locally created tableau, unless  local
       site policy includes an embedded indicator.  No recommendation for this
       indicator is provide, since every authorization token is  a  matter  of
       site policy,

       The  roapmux service recognizes each client host via getpeername(2) and
       a reverse DNS lookup on the  resulting  IP  address.   If  the  reverse
       lookup  fails, then the proposed name of the host is @ (commercial at),
       which cannot be part of any real  hostname.   To  further  resolve  the
       client's  credentials the same processing done by msrcmux is applied to
       form the hostname suitable for hxmd.

NETWORK API
       The tcpmux configuration for this service looks like:
            roap stream tcp nowait admin /usr/local/libexec/roapmux roapmux -Csite.cf env-list generator
       Where admin is the name of a safe login to run the  service,  and  env-
       list  is  a (possibly empty) list of environment variables that provide
       context.  The site.cf configuration file specifies the hxmd  configura-
       tion file to consult for site policy regarding each client.  The gener-
       ator specification is a multi-word hxmd parameter  specification  which
       outputs the specific tableau.  Other options to roapmux may be inserted
       before the optional env-list parameter.

       While it is not actually required to  use  hxmd(8l)  as  the  generator
       back-end,  it  is recommended.  Any shell program that takes (at least)
       -C, -D, and -G specifications  as  hxmd  does  could  be  specified  to
       replace hxmd (under -E).

       Almost  all  clients  connect  via a stampctl.  Some clients may access
       this service via muxcat, in which case the output is usually redirected
       to  a  file,  or  sent  to a grep(1) pipeline to confirm for a specific
       tableau entry via a regular expression match.  The standard  usage  via
       muxcat is:
            muxcat host roapmux login:groups:netgroups:domain:query

       Any  stampctl  jackets gain access to the correct authorization service
       via the DNS name.  How this name is derived is another matter  of  site
       policy.   One  could  abstract  that  information to a local filesystem
       path, use a locally defined name, leverage  an  existing  configuration
       management  service,  or  use  a service discovery protocol.  See stam-
       pctl(8), specifically under -R roap.

       Neither sh(1) nor m4(1) quotes are allowed in  any  of  the  credential
       values.   This  is  assured via perl(1) regular matches for each of the
       credential fields:
            login /\w*/ - a login name or uid
            groups /[\w ,]*/ - a list of group names and gids
            netgroups /[\w ,]*/ - a list of netgroups
            domain /[-\w.]*/ - a dns or YP/NIS domain
            query /[-\s!#%+,./\w:=@^{}]*/ - no shell meta characters
       When the query has any leading or trailing white-space it  is  removed.
       Note  the  query may contain "../" as a path component.  In the genera-
       tor, a check for that should be imposed to prevent directory  climbing.
       The query may contain a shell comment symbol (#).  If policy requires a
       disallowed character in the query, then use one of the allowed  symbols
       as an escape character.

OPTIONS
       No  options  are  forced based on the name of the program.  Assignments
       after the options are copied to the process environment, until  a  dou-
       ble-dash (--) or the first word that doesn't contain an equal sign (=).

       The common hxmd configuration options may not be repeated  to  catenate
       their  values.   This is a bug common to msrcmux as well.  However they
       may be specified as part of the generator.

       -C configs
              A colon separated list  of  the  default  client  configs.   The
              assumed  value  of  "auto.cf"  presumes that all your hosts look
              just like the server.  Local site policy should  pick  a  better
              value.

       -E hxmd
              The  name of the generator program which outputs the tableau, if
              not "/usr/local/sbin/hxmd".  The option  specification  to  this
              program is explained in AUTHENTICATION, below.

       -L hxmd-libs
              A  colon  separated list of directories to search for configura-
              tion files and MAP'ed files, see msrc(8l).

       -h
              Print only a brief help message.

       -M
              This implements a site policy requiring minimal information over
              the  wire  protocol.   The  intermediate  protocol  replies  are
              stripped of meaning.

       -R reverse
              Consult the reverse file via mk(1l) to search  for  the  correct
              host based on the marker returned by gethostbyaddr(3) and the IP
              submarker returned by getpeername(2).  When no  name  was  found
              the  marker  will  be commercial at (@).  The -s and -l0 options
              are presented, as well as the name of the configuration  file(s)
              specified  under  -DCONFIG=config.  When the reverse filename is
              dot (.) then the specified configuration file is searched.

              When the command exit(3)'s non-zero,  or  the  resulting  output
              contains  white-space,  or is zero length the client is notified
              that no such host exists.

       -V
              Show only the programs version information and exit.

       -x
              Trace replies from the remote service on stderr.

       -X ex-config
              Passed on to msrc, only 1 instance of this option is allowed.

       -Z zero-config
              Similarly to -X, this option is passed on to hxmd.

AUTHENTICATION
       Any authentication required is the responsibility of  the  client.   If
       the  client  sends  invalid  credentials to roapmux, it should expect a
       nonsense reply.  This allows clients to pose hypothetical questions  to
       the  service, which may be viewed as a lapse in judgment on the part of
       the provider, but actually  offers  very  limited  information  to  any
       attacker.  Periodic review of the syslogd(8) logs for auth and authpriv
       should reveal any such attack.

       The common client is an instance of stampctl driven as an op(1l)  esca-
       lated  process.   Thus  op has authenticated the process, and the esca-
       lated nature of the stamp prevents subornation  of  the  stamp  by  the
       invoker.

EXAMPLES
       muxcat auth.example.com roap "ksb:staff charon:.::"
              Ask  the local "auth" server for a authorization tableau for the
              login ksb in groups staff and  charon  with  no  available  net-
              groups, or YP/NIS domain specified, and an empty query string.

       roapmux -h
              Display the standard help output.


       stampctl -M/tmp/k0 -Rlocalhost:roap REALM=water
              Build  an  authorization  stamp at /tmp/k0, using a local
              instance of roapmux listed as "roap" under tcpmux.

       stampctl -Q/tmp/k0 REALM
              Ask the new stamp for the value  of  the  tableau  entry.
              This  may be any value, since the "roap" service may have
              replaced the suggested value.

BUGS
       None known.

AUTHORS
       Kevin S Braunsdorf, Npcguild.org
       msrc at ksb.npcguild.org.no-spam

SEE ALSO
       stampctl(8l),   stamp(7l),   msrcmux(7l),   hxmd(8l),    mk(1l),
       getpeername(2),  muxcat(1l), muxsend(1l), recvmux(7l), tcpmux(8)
       or tcpmux(8l), inetd(8) or xinetd(8), op-jacket(7l), perl(()



                                     LOCAL                          ROAPMUX(7)

NAME | SYNOPSIS | DESCRIPTION | NETWORK API | OPTIONS | AUTHENTICATION | EXAMPLES | BUGS | AUTHORS | SEE ALSO