diff options
Diffstat (limited to 'contrib/pf/authpf/authpf.8')
| -rw-r--r-- | contrib/pf/authpf/authpf.8 | 463 |
1 files changed, 463 insertions, 0 deletions
diff --git a/contrib/pf/authpf/authpf.8 b/contrib/pf/authpf/authpf.8 new file mode 100644 index 0000000..141aecf --- /dev/null +++ b/contrib/pf/authpf/authpf.8 @@ -0,0 +1,463 @@ +.\" $OpenBSD: authpf.8,v 1.30 2003/08/17 23:24:47 henning Exp $ +.\" +.\" Copyright (c) 2002 Bob Beck (beck@openbsd.org>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 10, 2002 +.Dt AUTHPF 8 +.Os +.Sh NAME +.Nm authpf +.Nd authenticating gateway user shell +.Sh SYNOPSIS +.Nm authpf +.Sh DESCRIPTION +.Nm +is a user shell for authenticating gateways. +It is used to change +.Xr pf 4 +rules when a user authenticates and starts a session with +.Xr sshd 8 +and to undo these changes when the user's session exits. +It is designed for changing filter and translation rules for an individual +source IP address as long as a user maintains an active +.Xr ssh 1 +session. +Typical use would be for a gateway that authenticates users before +allowing them Internet use, or a gateway that allows different users into +different places. +.Nm +logs the successful start and end of a session to +.Xr syslogd 8 . +This, combined with properly set up filter rules and secure switches, +can be used to ensure users are held accountable for their network traffic. +.Pp +.Nm +can add filter and translation rules using the syntax described in +.Xr pf.conf 5 . +.Nm +requires that the +.Xr pf 4 +system be enabled before use. +.Pp +.Nm +is meant to be used with users who can connect via +.Xr ssh 1 +only. +On startup, +.Nm +retrieves the client's connecting IP address via the +.Ev SSH_CLIENT +environment variable and, after performing additional access checks, +reads a template file to determine what filter and translation rules +(if any) to add. +On session exit the same rules that were added at startup are removed. +.Pp +Each +.Nm +process stores its rules in a separate ruleset inside a +.Xr pf 4 +.Pa anchor +shared by all +.Nm +processes. +By default, the +.Pa anchor +name "authpf" is used, and the ruleset names equal the PIDs of the +.Nm +processes. +The following rules need to be added to the main ruleset +.Pa /etc/pf.conf +in order to cause evaluation of any +.Nm +rules: +.Bd -literal -offset indent +nat-anchor authpf +rdr-anchor authpf +binat-anchor authpf +anchor authpf +.Ed +.Sh FILTER AND TRANSLATION RULES +Filter and translation rules for +.Nm +use the same format described in +.Xr pf.conf 5 . +The only difference is that these rules may (and probably should) use +the macro +.Em user_ip , +which is assigned the connecting IP address whenever +.Nm +is run. +Additionally, the macro +.Em user_id +is assigned the user name. +.Pp +Filter and nat rules will first be searched for in +.Pa /etc/authpf/users/$USER/ +and then in +.Pa /etc/authpf/ . +Per-user rules from the +.Pa /etc/authpf/users/$USER/ +directory are intended to be used when non-default rules +are needed on an individual user basis. +It is important to ensure that a user can not write or change +these configuration files. +.Pp +Filter and translation rules are loaded from the file +.Pa /etc/authpf/users/$USER/authpf.rules . +If this file does not exist the file +.Pa /etc/authpf/authpf.rules +is used. +The +.Pa authpf.rules +file must exist in one of the above locations for +.Nm +to run. +.Pp +Translation rules are also loaded from this file. +The use of translation rules in an +.Pa authpf.rules +file is optional. +.Sh CONFIGURATION +Options are controlled by the +.Pa /etc/authpf/authpf.conf +file. +If the file is empty, defaults are used for all +configuration options. +The file consists of pairs of the form +.Li name=value , +one per line. +Currently, the allowed values are as follows: +.Bl -tag -width Ds +.It anchor=name +Use the specified +.Pa anchor +name instead of "authpf". +.El +.Sh USER MESSAGES +On successful invocation, +.Nm +displays a message telling the user he or she has been authenticated. +It will additionally display the contents of the file +.Pa /etc/authpf/authpf.message +if the file exists and is readable. +.Pp +There exist two methods for providing additional granularity to the control +offered by +.Nm +- it is possible to set the gateway to explicitly allow users who have +authenticated to +.Xr ssh 1 +and deny access to only a few troublesome individuals. +This is done by creating a file with the banned user's login name as the +filename in +.Pa /etc/authpf/banned/ . +The contents of this file will be displayed to a banned user, thus providing +a method for informing the user that they have been banned, and where they can +go and how to get there if they want to have their service restored. +This is the default behaviour. +.Pp +It is also possible to configure +.Nm +to only allow specific users access. +This is done by listing their login names, one per line, in +.Pa /etc/authpf/authpf.allow . +If "*" is found on a line, then all usernames match. +If +.Nm +is unable to verify the user's permission to use the gateway, it will +print a brief message and die. +It should be noted that a ban takes precedence over an allow. +.Pp +On failure, messages will be logged to +.Xr syslogd 8 +for the system administrator. +The user does not see these, but will be told the system is unavailable due to +technical difficulties. +The contents of the file +.Pa /etc/authpf/authpf.problem +will also be displayed if the file exists and is readable. +.Sh CONFIGURATION ISSUES +.Nm +maintains the changed filter rules as long as the user maintains an +active session. +It is important to remember however, that the existence +of this session means the user is authenticated. +Because of this, it is important to configure +.Xr sshd 8 +to ensure the security of the session, and to ensure that the network +through which users connect is secure. +.Xr sshd 8 +should be configured to use the +.Ar ClientAliveInterval +and +.Ar ClientAliveCountMax +parameters to ensure that a ssh session is terminated quickly if +it becomes unresponsive, or if arp or address spoofing is used to +hijack the session. +Note that TCP keepalives are not sufficient for +this, since they are not secure. +.Pp +.Nm +will remove statetable entries that were created during a user's +session. +This ensures that there will be no unauthenticated traffic +allowed to pass after the controlling +.Xr ssh 1 +session has been closed. +.Pp +.Nm +is designed for gateway machines which typically do not have regular +(non-administrative) users using the machine. +An administrator must remember that +.Nm +can be used to modify the filter rules through the environment in +which it is run, and as such could be used to modify the filter rules +(based on the contents of the configuration files) by regular +users. +In the case where a machine has regular users using it, as well +as users with +.Nm +as their shell, the regular users should be prevented from running +.Nm +by using the +.Pa /etc/authpf/authpf.allow +or +.Pa /etc/authpf/banned/ +facilities. +.Pp +.Nm +modifies the packet filter and address translation rules, and because +of this it needs to be configured carefully. +.Nm +will not run and will exit silently if the +.Pa /etc/authpf/authpf.conf +file does not exist. +After considering the effect +.Nm +may have on the main packet filter rules, the system administrator may +enable +.Nm +by creating an appropriate +.Pa /etc/authpf/authpf.conf +file. +.Sh EXAMPLES +\fBControl Files\fP - To illustrate the user-specific access control +mechanisms, let us consider a typical user named bob. +Normally, as long as bob can authenticate himself, the +.Nm +program will load the appropriate rules. +Enter the +.Pa /etc/authpf/banned/ +directory. +If bob has somehow fallen from grace in the eyes of the +powers-that-be, they can prohibit him from using the gateway by creating +the file +.Pa /etc/authpf/banned/bob +containing a message about why he has been banned from using the network. +Once bob has done suitable penance, his access may be restored by moving or +removing the file +.Pa /etc/authpf/banned/bob . +.Pp +Now consider a workgroup containing alice, bob, carol and dave. +They have a +wireless network which they would like to protect from unauthorized use. +To accomplish this, they create the file +.Pa /etc/authpf/authpf.allow +which lists their login ids, one per line. +At this point, even if eve could authenticate to +.Xr sshd 8 , +she would not be allowed to use the gateway. +Adding and removing users from +the work group is a simple matter of maintaining a list of allowed userids. +If bob once again manages to annoy the powers-that-be, they can ban him from +using the gateway by creating the familiar +.Pa /etc/authpf/banned/bob +file. +Though bob is listed in the allow file, he is prevented from using +this gateway due to the existence of a ban file. +.Pp +\fBDistributed Authentication\fP - It is often desirable to interface with a +distributed password system rather than forcing the sysadmins to keep a large +number of local password files in sync. +The +.Xr login.conf 5 +mechanism in +.Ox +can be used to fork the right shell. +To make that happen, +.Xr login.conf 5 +should have entries that look something like this: +.Bd -literal -offset indent +shell-default:shell=/bin/csh + +default:\e + ... + :shell=/usr/sbin/authpf + +daemon:\e + ... + :shell=/bin/csh:\e + :tc=default: + +staff:\e + ... + :shell=/bin/csh:\e + :tc=default: +.Ed +.Pp +Using a default password file, all users will get +.Nm +as their shell except for root who will get +.Pa /bin/csh . +.Pp +\fBSSH Configuration\fP - As stated earlier, +.Xr sshd 8 +must be properly configured to detect and defeat network attacks. +To that end, the following options should be added to +.Xr sshd_config 5 : +.Bd -literal -offset indent +Protocol 2 +ClientAliveInterval 15 +ClientAliveCountMax 3 +.Ed +.Pp +This ensures that unresponsive or spoofed sessions are terminated within a +minute, since a hijacker should not be able to spoof ssh keepalive messages. +.Pp +\fBBanners\fP - Once authenticated, the user is shown the contents of +.Pa /etc/authpf/authpf.message . +This message may be a screen-full of the appropriate use policy, the contents +of +.Pa /etc/motd +or something as simple as the following: +.Bd -literal -offset indent +This means you will be held accountable by the powers that be +for traffic originating from your machine, so please play nice. +.Ed +.Pp +To tell the user where to go when the system is broken, +.Pa /etc/authpf/authpf.problem +could contain something like this: +.Bd -literal -offset indent +Sorry, there appears to be some system problem. To report this +problem so we can fix it, please phone 1-900-314-1597 or send +an email to remove@bulkmailerz.net. +.Ed +.Pp +\fBPacket Filter Rules\fP - In areas where this gateway is used to protect a +wireless network (a hub with several hundred ports), the default rule set as +well as the per-user rules should probably allow very few things beyond +encrypted protocols like +.Xr ssh 1 , +.Xr ssl 8 , +or +.Xr ipsec 4 . +On a securely switched network, with plug-in jacks for visitors who are +given authentication accounts, you might want to allow out everything. +In this context, a secure switch is one that tries to prevent address table +overflow attacks. +The examples below assume a switched wired net. +.Pp +Example +.Pa /etc/pf.conf : +.Bd -literal +# by default we allow internal clients to talk to us using +# ssh and use us as a dns server. +internal_if=\&"fxp1\&" +gateway_addr=\&"10.0.1.1\&" +nat-anchor authpf +rdr-anchor authpf +binat-anchor authpf +block in on $internal_if from any to any +pass in quick on $internal_if proto tcp from any to $gateway_addr \e + port = ssh +pass in quick on $internal_if proto udp from any to $gateway_addr \e + port = domain +anchor authpf +.Ed +.Pp +Example +.Pa /etc/authpf/authpf.rules : +.Bd -literal +# no real restrictions here, basically turn the network jack off or on. + +external_if = \&"xl0\&" +internal_if = \&"fxp0\&" + +pass in log quick on $internal_if proto tcp from $user_ip to any \e + keep state +pass in quick on $internal_if from $user_ip to any +.Ed +.Pp +Another example +.Pa /etc/authpf/authpf.rules +for an insecure network (such as a public wireless network) where +we might need to be a bit more restrictive. +.Bd -literal +internal_if=\&"fxp1\&" +ipsec_gw=\&"10.2.3.4\&" + +# rdr ftp for proxying by ftp-proxy(8) +rdr on $internal_if proto tcp from $user_ip to any port 21 \e + -> 127.0.0.1 port 8081 + +# allow out ftp, ssh, www and https only, and allow user to negotiate +# ipsec with the ipsec server. +pass in log quick on $internal_if proto tcp from $user_ip to any \e + port { 21, 22, 80, 443 } flags S/SA +pass in quick on $internal_if proto tcp from $user_ip to any \e + port { 21, 22, 80, 443 } +pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \e + keep state +pass in quick proto esp from $user_ip to $ipsec_gw +.Ed +.Sh FILES +.Bl -tag -width "/etc/authpf/authpf.conf" -compact +.It Pa /etc/authpf/authpf.conf +.It Pa /etc/authpf/authpf.allow +.It Pa /etc/authpf/authpf.rules +.It Pa /etc/authpf/authpf.message +.It Pa /etc/authpf/authpf.problem +.El +.Sh SEE ALSO +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr ftp-proxy 8 +.Sh HISTORY +The +.Nm +program first appeared in +.Ox 3.1 . +.Sh BUGS +Configuration issues are tricky. +The authenticating +.Xr ssh 1 +connection may be secured, but if the network is not secured the user may +expose insecure protocols to attackers on the same network, or enable other +attackers on the network to pretend to be the user by spoofing their IP +address. +.Pp +.Nm +is not designed to prevent users from denying service to other users. |
