.\" $Id: roapmux.man,v 1.5 2012/11/05 14:45:36 ksb Exp $ .\" by KS Braunsdorf .\" $Compile: Display%h .\" $Display: ${groff-groff} -Tascii -man -tbl %f | ${PAGER-less} .\" $Display(*): ${groff-groff} -T%s -man -tbl % f .\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/roapmux.7 .\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/roapmux.7* .TH ROAPMUX 7 LOCAL .SH NAME roapmux - provide an authorization tableau to specific network clients .SH SYNOPSIS .ds PN "roapmux \fI\*(PN\fP [\fB\-Mx\fP] [\fB\-C\fP\~\fIconfigs\fP] [\fB\-E\fP\~\fIhxmd\fP] [\fB\-L\fP\~\fIhxmd-libs\fP] [\fB\-R\fP\~\fIreverse\fP] [\fB\-X\fP\~\fIex-config\fP] [\fB\-Z\fP\~\fIzero-config\fP] [\fIenvs\fP] [\fIgenerator\fP] .br \fI\*(PN\fP \fB\-h\fP .br \fI\*(PN\fP \fB\-V\fP [\fIenvs\fP] [\fIgenerator\fP] .SH DESCRIPTION The \fBR\fPemote \fBO\fPp \fBA\fPuthorization \fBP\fProtocol service provides authorization advice to local network peers, usually driven by the setup of a \fBstampctl\fP authorization stamp. This service runs under \fBtcpmux\fP (usually under \fBinetd\fP) on an authorization host to distribute custom authorization tableaus to specific network clients. Each stream appears (to the client) to be a valid \fBstampctl\fP(8l) tableau. The \fBstampctl\fP option \fB\-R\fP specifies and authorization host, which should provide this service, or one supporting the same API. .P Authorization requests via \fBstamp\fP(7l) fetch a tableau which is completely 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, .P The \fI\*(PN\fP service recognizes each client host via \fBgetpeername\fP(2) and a reverse DNS lookup on the resulting IP address. If the reverse lookup fails, then the proposed name of the host is \fB@\fP (commercial at), which cannot be part of any real hostname. To further resolve the client's credentials the same processing done by \fBmsrcmux\fP is applied to form the hostname suitable for \fBhxmd\fP. .SH "NETWORK API" .PP The \fBtcpmux\fP configuration for this service looks like: .nf \fBroap\fP stream tcp nowait \fIadmin\fP /usr/local/libexec/roapmux \*(PN \-C\fIsite.cf\fP \fIenv-list\fP \fIgenerator\fP .fi Where \fIadmin\fP is the name of a safe login to run the service, and \fIenv-list\fP is a (possibly empty) list of environment variables that provide context. The \fIsite.cf\fP configuration file specifies the \fBhxmd\fP configuration file to consult for site policy regarding each client. The \fIgenerator\fP specification is a multi-word \fBhxmd\fP parameter specification which outputs the specific tableau. Other options to \fI\*(PN\fP may be inserted before the optional \fIenv-list\fP parameter. .P While it is not actually required to use \fBhxmd\fP(8l) as the generator back-end, it is recommended. Any shell program that takes (at least) \fB\-C\fP, \fB\-D\fP, and \fB\-G\fP specifications as \fBhxmd\fP does could be specified to replace \fIhxmd\fP (under \fB\-E\fP). .P Almost all clients connect via a \fBstampctl\fP. Some clients may access this service via \fBmuxcat\fP, in which case the output is usually redirected to a file, or sent to a \fBgrep\fP pipeline to confirm for a specific tableau entry via a regular expression match. The standard usage via \fBmuxcat\fP is: .nf \fBmuxcat\fP \fIhost\fP roapmux \fIlogin\fP\fB:\fP\fIgroups\fP\fB:\fP\fInetgroups\fP:\fIdomain\fP:\fIquery\fP .fi .P Any \fBstampctl\fP 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 \fBstampctl\fP(8), specifically under \fB\-R\fP \fIroap\fP. .P Neither \fBsh\fP nor \fBm4\fP quotes are allowed in any of the credential values. This is assured via \fBperl\fP regular matches for each of the credential fields: .nf \fIlogin\fP /\ew*/ \- a login name or uid \fIgroups\fP /[\ew ,]*/ - a list of group names and gids \fInetgroups\fP /[\ew ,]*/ - a list of netgroups \fIdomain\fP /[-\ew.]*/ - a dns or YP/NIS domain \fIquery\fP /[-\es!#%+,./\ew:=@^{}]*/ - no shell meta characters .fi When the query has any leading or trailing white-space it is removed. Note the query may contain \*(lq../\*(rq as a path component. In the \fIgenerator\fP, a check for that should be imposed to prevent directory climbing. The query may contain a shell comment symbol (\fB#\fP). If policy requires a disallowed character in the query, then use one of the allowed symbols as an escape character. .SH OPTIONS No options are forced based on the name of the program. Assignments after the options are copied to the process environment, until a double-dash (\fB\-\-\fP) or the first word that doesn't contain an equal sign (\fB=\fP). .P The common \fBhxmd\fP configuration options may \fBnot\fP be repeated to catenate their values. This is a bug common to \fBmsrcmux\fP as well. However they may be specified as part of the \fIgenerator\fP. .TP .nf \fB\-C\fP \fIconfigs\fP .fi A colon separated list of the default client \fIconfigs\fP. The assumed value of \*(lqauto.cf\*(rq presumes that all your hosts look just like the server. Local site policy should pick a better value. .TP .nf \fB\-E\fP \fIhxmd\fP .fi The name of the generator program which outputs the tableau, if not \*(lq/usr/local/sbin/hxmd\*(rq. The option specification to this program is explained in AUTHENTICATION, below. .TP .nf \fB\-L\fP \fIhxmd-libs\fP .fi A colon separated list of directories to search for configuration files and \fBMAP\fP'ed files. .TP .nf \fB\-h\fP .fi Print only a brief help message. .TP .nf \fB\-M\fP .fi This implements a site policy requiring minimal information over the wire protocol. The intermediate protocol replies are stripped of meaning. .TP .nf \fB\-R\fP \fIreverse\fP .fi Consult the \fIreverse\fP file via \fBmk\fP(1l) to search for the correct host based on the \fImarker\fP returned by \fBgethostbyaddr\fP(3) and the IP \fIsubmarker\fP returned by \fBgetpeername\fP(2). When no name was found the marker will be commercial at (\fB@\fP). The \fB\-s\fP and \fB\-l0\fP options are presented, as well as the name of the configuration file(s) specified under \fB\-DCONFIG=\fP\fIconfig\fP. When the \fIreverse\fP filename is dot (\fB.\fP) then the specified configuration file is searched. .sp When the command \fBexit\fP's non-zero, or the resulting output contains white-space, or is zero length the client is notified that no such host exists. .TP .nf \fB\-V\fP .fi Show only the programs version information and exit. .TP .nf \fB\-x\fP .fi Trace replies from the remote service on \fIstderr\fP. .TP .nf \fB\-X\fP \fIex-config\fP .fi Passed on to \fBmsrc\fP, only 1 instance of this option is allowed. .TP .nf \fB\-Z\fP \fIzero-config\fP .fi Similarly to \fB\-X\fP, this option is passed on to \fBhxmd\fP. .SH AUTHENTICATION Any authentication required is the responsibility of the client. If the client sends invalid credentials to \fI\*(PN\fP, 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 \fBsyslogd\fP(8) logs for \fBauth\fP and \fBauthpriv\fP should reveal any such attack. .P The common client is an instance of \fBstampctl\fP driven as an \fBop\fP escalated process. Thus \fBop\fP has authenticated the process, and the escalated nature of the stamp prevents subornation of the stamp by the invoker. .SH EXAMPLES .TP .nf muxcat auth.example.com roap "ksb:staff charon:.::" .fi Ask the local \*(lqauth\*(rq server for a authorization tableau for the login \fBksb\fP in groups \fBstaff\fP and \fBcharon\fP with no available netgroups, or YP/NIS domain specified, and an empty query string. .TP .nf \fI\*(PN\fP \-h .fi Display the standard help output. .TP .TP .nf \fBstampctl\fP \-M/tmp/k0 \-Rlocalhost:roap REALM=water .fi Build an authorization stamp at /tmp/k0, using a local instance of \fI\*(PN\fP listed as "roap" under \fBtcpmux\fP. .TP .nf \fBstampctl\fP \-Q/tmp/k0 REALM .fi 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. .SH BUGS None known. .SH AUTHORS Kevin S Braunsdorf, Npcguild.org .br msrc at ksb.npcguild.org.no-spam .SH "SEE ALSO" .hlm 0 stampctl(8l), stamp(7l), msrcmux(8l), hxmd(8l), mk(1l), getpeername(2), muxcat(1l), muxsend(1l), recvmux(1l), tcpmux(8) or tcpmux(8l), inetd(8), xinetd(8), op-jacket(7l)