.\" $OpenBSD: authpf.8,v 1.10 2002/04/15 05:55:48 pvalchev 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,
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 and nat rules will be searched for first 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 in
this case.
.Pp
Filter 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 loaded from the file
.Pa /etc/authpf/users/$USER/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 CONFIGURATION
Options are controlled by the
.Pa /etc/authpf/authpf.conf
file.
This file is required to be present and readable for
.Nm
to run.
It may be empty if the default behavior does not need 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 /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 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 which 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 /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 pennance, 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
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
.Pp
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
.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 .