home | help
AUTHPF(8)		     System Manager's Manual		       AUTHPF(8)

NAME
     authpf -- authenticating gateway user shell

SYNOPSIS
     authpf

DESCRIPTION
     authpf  is  a user shell for authenticating gateways.  It is used to change
     pf(4) rules when a user authenticates and starts a session with 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 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.  authpf
     logs the successful start and end of a session to syslogd(8).   This,  com-
     bined with properly set up filter rules and secure switches, can be used to
     ensure users are held accountable for their network traffic.

     authpf  can  add filter and translation rules using the syntax described in
     pf.conf(5).  authpf requires that the pf(4) system be enabled before use.

     authpf is meant to be used with users who can connect via ssh(1) only.   On
     startup,  authpf  retrieves  the  client's  connecting  IP  address via the
     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.

     Each  authpf  process stores its rules in a separate ruleset inside a pf(4)
     anchor shared by all authpf processes.  By default, the  anchor  name  "au-
     thpf"  is	used,  and  the  ruleset names equal the username and PID of the
     authpf processes as "username(pid)".  The following rules need to be  added
     to the main ruleset /etc/pf.conf in order to cause evaluation of any authpf
     rules:

	   nat-anchor authpf
	   rdr-anchor authpf
	   binat-anchor authpf
	   anchor authpf

FILTER AND TRANSLATION RULES
     Filter  and  translation  rules for authpf use the same format described in
     pf.conf(5).  The only difference is that  these  rules  may  (and	probably
     should)  use the macro user_ip, which is assigned the connecting IP address
     whenever authpf is run.  Additionally, the macro user_id  is  assigned  the
     user name.

     Filter and nat rules will first be searched for in /etc/authpf/users/$USER/
     and then in /etc/authpf/.	Per-user rules from the /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.

     Filter   and   translation    rules    are    loaded    from    the    file
     /etc/authpf/users/$USER/authpf.rules.  If this file does not exist the file
     /etc/authpf/authpf.rules  is used.  The authpf.rules file must exist in one
     of the above locations for authpf to run.

     Translation rules are also loaded from this file.	The use  of  translation
     rules in an authpf.rules file is optional.

CONFIGURATION
     Options are controlled by the /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 name=value, one per line.  Currently, the allowed val-
     ues are as follows:

     anchor=name
	     Use the specified anchor name instead of "authpf".

USER MESSAGES
     On successful invocation, authpf displays a message telling the user he  or
     she  has  been authenticated.  It will additionally display the contents of
     the file /etc/authpf/authpf.message if the file exists and is readable.

     There exist two methods for providing additional granularity to the control
     offered by authpf - it is possible to set the gateway to  explicitly  allow
     users  who have authenticated to ssh(1) and deny access to only a few trou-
     blesome individuals.  This is done by  creating  a  file  with  the  banned
     user's  login name as the filename in /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.

     It  is  also  possible to configure authpf to only allow specific users ac-
     cess.  This is done  by  listing  their  login  names,  one  per  line,  in
     /etc/authpf/authpf.allow.	 If  "*"  is found on a line, then all usernames
     match.  If authpf 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.

     On failure, messages will be logged to syslogd(8) for the	system	adminis-
     trator.   The  user  does not see these, but will be told the system is un-
     available	due  to  technical  difficulties.   The  contents  of  the  file
     /etc/authpf/authpf.problem will also be displayed if the file exists and is
     readable.

CONFIGURATION ISSUES
     authpf  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  im-
     portant  to configure sshd(8) to ensure the security of the session, and to
     ensure that the network through which users  connect  is  secure.	 sshd(8)
     should be configured to use the ClientAliveInterval and 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.

     authpf  will  remove  statetable  entries that were created during a user's
     session.  This ensures that there will be no  unauthenticated  traffic  al-
     lowed to pass after the controlling ssh(1) session has been closed.

     authpf is designed for gateway machines which typically do not have regular
     (non-administrative) users using the machine.  An administrator must remem-
     ber that authpf can be used to modify the filter rules through the environ-
     ment  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 authpf as their shell, the regular users should be prevented from run-
     ning authpf by using the  /etc/authpf/authpf.allow  or  /etc/authpf/banned/
     facilities.

     authpf  modifies  the  packet filter and address translation rules, and be-
     cause of this it needs to be configured carefully.  authpf will not run and
     will exit silently if the /etc/authpf/authpf.conf file does not exist.  Af-
     ter considering the effect authpf may have on the main packet filter rules,
     the system administrator may  enable  authpf  by  creating  an  appropriate
     /etc/authpf/authpf.conf file.

EXAMPLES
     Control  Files - To illustrate the user-specific access control mechanisms,
     let us consider a typical user named bob.	Normally, as long as bob can au-
     thenticate himself, the authpf program will  load	the  appropriate  rules.
     Enter  the  /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 /etc/authpf/banned/bob containing a mes-
     sage 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 /etc/authpf/banned/bob.

     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 /etc/authpf/authpf.allow which
     lists their login ids, one per line.  At this point, even if eve could  au-
     thenticate to 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
     /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.

     Distributed Authentication - It is often desirable to interface with a dis-
     tributed password system rather than forcing the sysadmins to keep a  large
     number  of  local	password  files in sync.  The login.conf(5) mechanism in
     OpenBSD can be used to fork the right shell.   To	make  that  happen,  lo-
     gin.conf(5) should have entries that look something like this:

	   shell-default:shell=/bin/csh

	   default:\
		   ...
		   :shell=/usr/sbin/authpf

	   daemon:\
		   ...
		   :shell=/bin/csh:\
		   :tc=default:

	   staff:\
		   ...
		   :shell=/bin/csh:\
		   :tc=default:

     Using a default password file, all users will get authpf as their shell ex-
     cept for root who will get /bin/csh.

     SSH  Configuration - As stated earlier, sshd(8) must be properly configured
     to detect and defeat network attacks.  To that end, the  following  options
     should be added to sshd_config(5):

	   Protocol 2
	   ClientAliveInterval 15
	   ClientAliveCountMax 3

     This  ensures that unresponsive or spoofed sessions are terminated within a
     minute, since a hijacker should not be able to  spoof  ssh  keepalive  mes-
     sages.

     Banners   -   Once  authenticated,  the  user  is	shown  the  contents  of
     /etc/authpf/authpf.message.  This message may be a screen-full of	the  ap-
     propriate	use  policy, the contents of /etc/motd or something as simple as
     the following:

	   This means you will be held accountable by the powers that be
	   for traffic originating from your machine, so please play nice.

     To  tell  the   user   where   to	 go   when   the   system   is	 broken,
     /etc/authpf/authpf.problem could contain something like this:

	   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.

     Packet  Filter  Rules  -  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  ssh(1),	ssl(8),  or  ipsec(4).	 On  a	securely
     switched network, with plug-in jacks for visitors who are given authentica-
     tion  accounts, you might want to allow out everything.  In this context, a
     secure switch is one that tries to prevent address table overflow attacks.

     Example /etc/pf.conf:

     # 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 \
	   port = ssh
     pass in quick on $internal_if proto udp from any to $gateway_addr \
	   port = domain
     anchor authpf

     For a switched, wired net - This example /etc/authpf/authpf.rules makes  no
     real  restrictions; it turns the IP address on and off, logging TCP connec-
     tions.

     external_if = "xl0"
     internal_if = "fxp0"

     pass in log quick on $internal_if proto tcp from $user_ip to any \
	   keep state
     pass in quick on $internal_if from $user_ip to any

     For a wireless or shared net - This example /etc/authpf/authpf.rules  could
     be  used  for an insecure network (such as a public wireless network) where
     we might need to be a bit more restrictive.

     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 \
	   -> 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 \
	   port { 21, 22, 80, 443 } flags S/SA
     pass in quick on $internal_if proto tcp from $user_ip to any \
	   port { 21, 22, 80, 443 }
     pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \
	   keep state
     pass in quick proto esp from $user_ip to $ipsec_gw

     Dealing with NAT - The following /etc/authpf/authpf.rules shows how to deal
     with NAT, using tags:

     ext_if = "fxp1"
     ext_addr = 129.128.11.10
     int_if = "fxp0"
     # nat and tag connections...
     nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr
     pass in quick on $int_if from $user_ip to any
     pass out log quick on $ext_if tagged $user_ip keep state

     With the above rules added by authpf, outbound connections corresponding to
     each users NAT'ed connections will be logged as in the example below, where
     the user may be identified from the ruleset name.

     # tcpdump -n -e -ttt -i pflog0
     Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \
     129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \
     16384 <mss 1460,nop,nop,sackOK> (DF)

FILES
     /etc/authpf/authpf.conf
     /etc/authpf/authpf.allow
     /etc/authpf/authpf.rules
     /etc/authpf/authpf.message
     /etc/authpf/authpf.problem

SEE ALSO
     pf(4), pf.conf(5), ftp-proxy(8)

HISTORY
     The authpf program first appeared in OpenBSD 3.1.

BUGS
     Configuration issues are tricky.  The authenticating 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.

     authpf  is  not  designed	to  prevent  users from denying service to other
     users.

FreeBSD 5.3			January 10, 2002		       AUTHPF(8)

home | help