authpf - authenticating gateway shell for use with ssh(1) to make

authenticating gateway type firewalls.

caveats - needs to be setuid to opertate (but does not install that way)
consult the man page for configuration issues.

1 files changed, 424 insertions, 0 deletions

diff --git a/usr.sbin/authpf/authpf.8 b/usr.sbin/authpf/authpf.8
new file mode 100644
index 00000000000..f3e49281665
--- /dev/null
+++ b/usr.sbin/authpf/authpf.8
@@ -0,0 +1,424 @@
+\" $OpenBSD: authpf.8,v 1.1 2002/04/01 17:43:42 beck 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 Jan 10, 2002
+.Dt AUTHPF 8
+.Os
+.Sh NAME
+.Nm authpf
+.Nd authenticating gateway user shell
+.Sh SYNOPSIS
+.Nm authpf
+.Sh DESCRIPTION
+.Nm
+is used as 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 then undo the 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 syslog 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 and filter rules using the syntax of
+.Xr pf.conf 5
+and translation rules using the syntax of 
+.Xr nat.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 filter rule template file is read to determine what filter rules to add.
+Optionally, a translation rule template file is read to determine translation
+rules to add. On session exit the same rules that were added at startup are
+removed. By default, filter rules are added at the end of the active
+.Xr pf 4
+filter list, and translation rules are added at the start of the active
+.Xr pf 4
+nat and rdr lists.
+.Sh FILTER AND TRANSLATION RULES
+Filter and Translation rules for 
+.Nm
+use the same format described in 
+.Xr pf.conf 5
+and 
+.Xr nat.conf 5 .
+The only difference is that these rules may (and probably should) use
+the macro 
+.Em user_ip
+which is defined to the connecting ip address whenever
+.Nm
+is run.
+.Pp
+Filter rules are loaded from the file
+.Pa $HOME/.authpf/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 either the user's
+.Pa $HOME/.authpf/
+directory, or in 
+.Pa /etc/authpf ,
+for
+.Nm
+to run.
+.Pp
+Translation rules are loaded from the file
+.Pa $HOME/.authpf/authpf.nat .
+If this file does not exist the file 
+.Pa /etc/authpf/authpf.nat
+is used. The use of translation rules in an
+.Pa authpf.nat
+file is optional.
+.Sh OPTIONS
+Options are controlled by the 
+.Pa /etc/authpf/authpf.conf
+file. This file is optional, is not needed unless the default behavior
+needs to be changed. 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 rule_action=[head|tail]
+controls where filter rules are added, the default behavior is "tail"
+meaning filter rules are added to the end of the active filter list. 
+.It Dv nat_action=[head|tail]
+controls where nat rules are added, the default behavior is "head"
+meaning filter rules are added to the start of the active nat list.
+.It Dv rdr_action=[head|tail]
+controls where rdr rules are added, the default behavior is "head"
+meaning filter rules are added to the start of the active rdr list.
+.El
+.Sh USER MESSAGES
+On successful invocation, 
+.Nm
+displays a message telling the user they have 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 in
+.Pa /var/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 syslog 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 both configure 
+.Xr sshd 8
+to ensure the security of the session, and to ensure that the network
+by which users connect to use. 
+.Xr sshd 8
+should be configured to use the 
+.Dv ClientAliveInterval
+and 
+.Dv ClientAliveCountMax
+parameters to ensure than an 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 state table 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 with don't typically 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 /var/authpf/banned/
+facilities.
+.Pp
+.Nm
+must be setuid-root in order to modify the packet filter and translation
+rules, though it is not installed with the setuid bit turned on. After
+considering the effect
+.Nm
+may have on the main packet filter rules, the system administrator may run
+the following command to enable
+.Nm
+: "chmod +s /usr/sbin/authpf" .
+.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 /var/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 /var/authpf/banned/bob
+containing a message about why he has been banned from using the network.
+Once bob has done suitable pennance, his access may be restored by moving or
+removing the file
+.Pa /var/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 /var/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
+shell-default:shell=/bin/csh
+
+default:\\
+	...
+	:shell=/usr/sbin/authpf
+
+daemon:\\
+	...
+	:shell=/bin/csh:\\
+	:tc=default:
+
+staff:\\
+	...
+	:shell=/bin/csh:\\
+	: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
+.Pa sshd_config :
+.Bd -literal
+ClientAliveInterval 15  
+ClientAliveCountMax 3
+
+.Ed
+This ensures that unresponsive or spoofed session are terminated in under a
+minute, since a hijacker should not be able to spoof ssh keepalive messages.
+.Pp
+.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
+
+    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
+	
+    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"
+block in on $internal_if from any to any
+pass in quick on $internal_if proto tcp from any to $gateway_addr/32 \\
+ port = ssh
+pass in quick on $internal_if proto udp from any to $gateway_addr/32 \\
+ port = domain
+.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 quick log on $internal_if proto tcp from $user_ip/32 to any \\
+ keep state
+pass in quick on $internal_if from $user_ip/32 to any
+.Ed
+.Pp
+Example
+.Pa /etc/authpf/authpf.nat :
+.Bd -literal
+# When the user authenticates, rdr ftp for proxying by ftp-proxy(8)
+internal_if="fxp1"
+rdr on $internal_if proto tcp from $user_ip/32 to any port 21 \\
+ -> 127.0.0.1 port 8081 
+.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"
+# allow out ftp, ssh, www and https only, and allow user to negotiate
+# ipsec with the ipsec server.
+pass in quick log on $internal_if proto tcp from $user_ip/32 to any \\
+ { port 21, 22, 80, 443 } flags S/SA
+pass in quick on $internal_if proto tcp from $user_ip/32 to any \\
+ { port 21, 22, 80, 443 } 
+pass in quick proto udp from $user_ip/32 to $ipsec_gw/32 port = isakmp \\
+ keep-state
+pass in quick proto esp from $user_ip/32 to $ipsec_gw/32
+.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.nat
+.It Pa /etc/authpf/authpf.message
+.It Pa /etc/authpf/authpf.problem
+.El
+.Sh SEE ALSO
+.Xr pf 4 ,
+.Xr nat.conf 5 ,
+.Xr pf.conf 5 ,
+.Xr ftp-proxy 8
+.Sh BUGS
+.Pp
+.Nm
+does not support binat translation rules.
+.Pp
+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 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.  
+.Sh HISTORY
+The
+.Nm
+program first appeared in
+.Ox 3.1 .