1.\" $OpenBSD: authpf.8,v 1.31 2003/12/10 04:10:37 beck Exp $ 2.\" $DragonFly: src/usr.sbin/authpf/authpf.8,v 1.3 2007/07/29 17:27:45 swildner Exp $ 3.\" 4.\" Copyright (c) 2002 Bob Beck (beck@openbsd.org>. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd January 10, 2002 29.Dt AUTHPF 8 30.Os 31.Sh NAME 32.Nm authpf 33.Nd authenticating gateway user shell 34.Sh SYNOPSIS 35.Nm 36.Sh DESCRIPTION 37.Nm 38is a user shell for authenticating gateways. 39It is used to change 40.Xr pf 4 41rules when a user authenticates and starts a session with 42.Xr sshd 8 43and to undo these changes when the user's session exits. 44It is designed for changing filter and translation rules for an individual 45source IP address as long as a user maintains an active 46.Xr ssh 1 47session. 48Typical use would be for a gateway that authenticates users before 49allowing them Internet use, or a gateway that allows different users into 50different places. 51.Nm 52logs the successful start and end of a session to 53.Xr syslogd 8 . 54This, combined with properly set up filter rules and secure switches, 55can be used to ensure users are held accountable for their network traffic. 56.Pp 57.Nm 58can add filter and translation rules using the syntax described in 59.Xr pf.conf 5 . 60.Nm 61requires that the 62.Xr pf 4 63system be enabled before use. 64.Pp 65.Nm 66is meant to be used with users who can connect via 67.Xr ssh 1 68only. 69On startup, 70.Nm 71retrieves the client's connecting IP address via the 72.Ev SSH_CLIENT 73environment variable and, after performing additional access checks, 74reads a template file to determine what filter and translation rules 75(if any) to add. 76On session exit the same rules that were added at startup are removed. 77.Pp 78Each 79.Nm 80process stores its rules in a separate ruleset inside a 81.Xr pf 4 82.Pa anchor 83shared by all 84.Nm 85processes. 86By default, the 87.Pa anchor 88name "authpf" is used, and the ruleset names equal the username and PID of the 89.Nm 90processes as "username(pid)". 91The following rules need to be added to the main ruleset 92.Pa /etc/pf.conf 93in order to cause evaluation of any 94.Nm 95rules: 96.Bd -literal -offset indent 97nat-anchor authpf 98rdr-anchor authpf 99binat-anchor authpf 100anchor authpf 101.Ed 102.Sh FILTER AND TRANSLATION RULES 103Filter and translation rules for 104.Nm 105use the same format described in 106.Xr pf.conf 5 . 107The only difference is that these rules may (and probably should) use 108the macro 109.Em user_ip , 110which is assigned the connecting IP address whenever 111.Nm 112is run. 113Additionally, the macro 114.Em user_id 115is assigned the user name. 116.Pp 117Filter and nat rules will first be searched for in 118.Pa /etc/authpf/users/$USER/ 119and then in 120.Pa /etc/authpf/ . 121Per-user rules from the 122.Pa /etc/authpf/users/$USER/ 123directory are intended to be used when non-default rules 124are needed on an individual user basis. 125It is important to ensure that a user can not write or change 126these configuration files. 127.Pp 128Filter and translation rules are loaded from the file 129.Pa /etc/authpf/users/$USER/authpf.rules . 130If this file does not exist the file 131.Pa /etc/authpf/authpf.rules 132is used. 133The 134.Pa authpf.rules 135file must exist in one of the above locations for 136.Nm 137to run. 138.Pp 139Translation rules are also loaded from this file. 140The use of translation rules in an 141.Pa authpf.rules 142file is optional. 143.Sh CONFIGURATION 144Options are controlled by the 145.Pa /etc/authpf/authpf.conf 146file. 147If the file is empty, defaults are used for all 148configuration options. 149The file consists of pairs of the form 150.Li name=value , 151one per line. 152Currently, the allowed values are as follows: 153.Bl -tag -width Ds 154.It anchor=name 155Use the specified 156.Pa anchor 157name instead of "authpf". 158.El 159.Sh USER MESSAGES 160On successful invocation, 161.Nm 162displays a message telling the user he or she has been authenticated. 163It will additionally display the contents of the file 164.Pa /etc/authpf/authpf.message 165if the file exists and is readable. 166.Pp 167There exist two methods for providing additional granularity to the control 168offered by 169.Nm 170- it is possible to set the gateway to explicitly allow users who have 171authenticated to 172.Xr ssh 1 173and deny access to only a few troublesome individuals. 174This is done by creating a file with the banned user's login name as the 175filename in 176.Pa /etc/authpf/banned/ . 177The contents of this file will be displayed to a banned user, thus providing 178a method for informing the user that they have been banned, and where they can 179go and how to get there if they want to have their service restored. 180This is the default behaviour. 181.Pp 182It is also possible to configure 183.Nm 184to only allow specific users access. 185This is done by listing their login names, one per line, in 186.Pa /etc/authpf/authpf.allow . 187If "*" is found on a line, then all usernames match. 188If 189.Nm 190is unable to verify the user's permission to use the gateway, it will 191print a brief message and die. 192It should be noted that a ban takes precedence over an allow. 193.Pp 194On failure, messages will be logged to 195.Xr syslogd 8 196for the system administrator. 197The user does not see these, but will be told the system is unavailable due to 198technical difficulties. 199The contents of the file 200.Pa /etc/authpf/authpf.problem 201will also be displayed if the file exists and is readable. 202.Sh CONFIGURATION ISSUES 203.Nm 204maintains the changed filter rules as long as the user maintains an 205active session. 206It is important to remember however, that the existence 207of this session means the user is authenticated. 208Because of this, it is important to configure 209.Xr sshd 8 210to ensure the security of the session, and to ensure that the network 211through which users connect is secure. 212.Xr sshd 8 213should be configured to use the 214.Ar ClientAliveInterval 215and 216.Ar ClientAliveCountMax 217parameters to ensure that a ssh session is terminated quickly if 218it becomes unresponsive, or if arp or address spoofing is used to 219hijack the session. 220Note that TCP keepalives are not sufficient for 221this, since they are not secure. 222.Pp 223.Nm 224will remove statetable entries that were created during a user's 225session. 226This ensures that there will be no unauthenticated traffic 227allowed to pass after the controlling 228.Xr ssh 1 229session has been closed. 230.Pp 231.Nm 232is designed for gateway machines which typically do not have regular 233(non-administrative) users using the machine. 234An administrator must remember that 235.Nm 236can be used to modify the filter rules through the environment in 237which it is run, and as such could be used to modify the filter rules 238(based on the contents of the configuration files) by regular 239users. 240In the case where a machine has regular users using it, as well 241as users with 242.Nm 243as their shell, the regular users should be prevented from running 244.Nm 245by using the 246.Pa /etc/authpf/authpf.allow 247or 248.Pa /etc/authpf/banned/ 249facilities. 250.Pp 251.Nm 252modifies the packet filter and address translation rules, and because 253of this it needs to be configured carefully. 254.Nm 255will not run and will exit silently if the 256.Pa /etc/authpf/authpf.conf 257file does not exist. 258After considering the effect 259.Nm 260may have on the main packet filter rules, the system administrator may 261enable 262.Nm 263by creating an appropriate 264.Pa /etc/authpf/authpf.conf 265file. 266.Sh FILES 267.Bl -tag -width "/etc/authpf/authpf.conf" -compact 268.It Pa /etc/authpf/authpf.conf 269.It Pa /etc/authpf/authpf.allow 270.It Pa /etc/authpf/authpf.rules 271.It Pa /etc/authpf/authpf.message 272.It Pa /etc/authpf/authpf.problem 273.El 274.Sh EXAMPLES 275.Sy Control Files 276\- To illustrate the user-specific access control 277mechanisms, let us consider a typical user named bob. 278Normally, as long as bob can authenticate himself, the 279.Nm 280program will load the appropriate rules. 281Enter the 282.Pa /etc/authpf/banned/ 283directory. 284If bob has somehow fallen from grace in the eyes of the 285powers-that-be, they can prohibit him from using the gateway by creating 286the file 287.Pa /etc/authpf/banned/bob 288containing a message about why he has been banned from using the network. 289Once bob has done suitable penance, his access may be restored by moving or 290removing the file 291.Pa /etc/authpf/banned/bob . 292.Pp 293Now consider a workgroup containing alice, bob, carol and dave. 294They have a 295wireless network which they would like to protect from unauthorized use. 296To accomplish this, they create the file 297.Pa /etc/authpf/authpf.allow 298which lists their login ids, one per line. 299At this point, even if eve could authenticate to 300.Xr sshd 8 , 301she would not be allowed to use the gateway. 302Adding and removing users from 303the work group is a simple matter of maintaining a list of allowed userids. 304If bob once again manages to annoy the powers-that-be, they can ban him from 305using the gateway by creating the familiar 306.Pa /etc/authpf/banned/bob 307file. 308Though bob is listed in the allow file, he is prevented from using 309this gateway due to the existence of a ban file. 310.Pp 311.Sy Distributed Authentication 312\- It is often desirable to interface with a 313distributed password system rather than forcing the sysadmins to keep a large 314number of local password files in sync. 315The 316.Xr login.conf 5 317mechanism in 318.Ox 319can be used to fork the right shell. 320To make that happen, 321.Xr login.conf 5 322should have entries that look something like this: 323.Bd -literal -offset indent 324shell-default:shell=/bin/csh 325 326default:\e 327 ... 328 :shell=/usr/sbin/authpf 329 330daemon:\e 331 ... 332 :shell=/bin/csh:\e 333 :tc=default: 334 335staff:\e 336 ... 337 :shell=/bin/csh:\e 338 :tc=default: 339.Ed 340.Pp 341Using a default password file, all users will get 342.Nm 343as their shell except for root who will get 344.Pa /bin/csh . 345.Pp 346.Sy SSH Configuration 347\- As stated earlier, 348.Xr sshd 8 349must be properly configured to detect and defeat network attacks. 350To that end, the following options should be added to 351.Xr sshd_config 5 : 352.Bd -literal -offset indent 353Protocol 2 354ClientAliveInterval 15 355ClientAliveCountMax 3 356.Ed 357.Pp 358This ensures that unresponsive or spoofed sessions are terminated within a 359minute, since a hijacker should not be able to spoof ssh keepalive messages. 360.Pp 361.Sy Banners 362\- Once authenticated, the user is shown the contents of 363.Pa /etc/authpf/authpf.message . 364This message may be a screen-full of the appropriate use policy, the contents 365of 366.Pa /etc/motd 367or something as simple as the following: 368.Bd -literal -offset indent 369This means you will be held accountable by the powers that be 370for traffic originating from your machine, so please play nice. 371.Ed 372.Pp 373To tell the user where to go when the system is broken, 374.Pa /etc/authpf/authpf.problem 375could contain something like this: 376.Bd -literal -offset indent 377Sorry, there appears to be some system problem. To report this 378problem so we can fix it, please phone 1-900-314-1597 or send 379an email to remove@bulkmailerz.net. 380.Ed 381.Pp 382.Sy Packet Filter Rules 383\- In areas where this gateway is used to protect a 384wireless network (a hub with several hundred ports), the default rule set as 385well as the per-user rules should probably allow very few things beyond 386encrypted protocols like 387.Xr ssh 1 , 388.Xr ssl 8 , 389or 390.Xr ipsec 4 . 391On a securely switched network, with plug-in jacks for visitors who are 392given authentication accounts, you might want to allow out everything. 393In this context, a secure switch is one that tries to prevent address table 394overflow attacks. 395.Pp 396Example 397.Pa /etc/pf.conf : 398.Bd -literal 399# by default we allow internal clients to talk to us using 400# ssh and use us as a dns server. 401internal_if="fxp1" 402gateway_addr="10.0.1.1" 403nat-anchor authpf 404rdr-anchor authpf 405binat-anchor authpf 406block in on $internal_if from any to any 407pass in quick on $internal_if proto tcp from any to $gateway_addr \e 408 port = ssh 409pass in quick on $internal_if proto udp from any to $gateway_addr \e 410 port = domain 411anchor authpf 412.Ed 413.Pp 414.Sy For a switched, wired net 415\- This example 416.Pa /etc/authpf/authpf.rules 417makes no real restrictions; it turns the IP address on and off, logging 418TCP connections. 419.Bd -literal 420external_if = "xl0" 421internal_if = "fxp0" 422 423pass in log quick on $internal_if proto tcp from $user_ip to any \e 424 keep state 425pass in quick on $internal_if from $user_ip to any 426.Ed 427.Pp 428.Sy For a wireless or shared net 429\- This example 430.Pa /etc/authpf/authpf.rules 431could be used for an insecure network (such as a public wireless network) where 432we might need to be a bit more restrictive. 433.Bd -literal 434internal_if="fxp1" 435ipsec_gw="10.2.3.4" 436 437# rdr ftp for proxying by ftp-proxy(8) 438rdr on $internal_if proto tcp from $user_ip to any port 21 \e 439 -> 127.0.0.1 port 8081 440 441# allow out ftp, ssh, www and https only, and allow user to negotiate 442# ipsec with the ipsec server. 443pass in log quick on $internal_if proto tcp from $user_ip to any \e 444 port { 21, 22, 80, 443 } flags S/SA 445pass in quick on $internal_if proto tcp from $user_ip to any \e 446 port { 21, 22, 80, 443 } 447pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \e 448 keep state 449pass in quick proto esp from $user_ip to $ipsec_gw 450.Ed 451.Pp 452.Sy Dealing with NAT 453\- The following 454.Pa /etc/authpf/authpf.rules 455shows how to deal with NAT, using tags: 456.Bd -literal 457ext_if = "fxp1" 458ext_addr = 129.128.11.10 459int_if = "fxp0" 460# nat and tag connections... 461nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr 462pass in quick on $int_if from $user_ip to any 463pass out log quick on $ext_if tagged $user_ip keep state 464.Ed 465.Pp 466With the above rules added by 467.Nm , 468outbound connections corresponding to each users NAT'ed connections 469will be logged as in the example below, where the user may be identified 470from the ruleset name. 471.Bd -literal 472# tcpdump -n -e -ttt -i pflog0 473Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \e 474129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \e 47516384 <mss 1460,nop,nop,sackOK> (DF) 476.Ed 477.Sh SEE ALSO 478.Xr pf 4 , 479.Xr pf.conf 5 , 480.Xr ftp-proxy 8 481.Sh HISTORY 482The 483.Nm 484program first appeared in 485.Ox 3.1 . 486.Sh BUGS 487Configuration issues are tricky. 488The authenticating 489.Xr ssh 1 490connection may be secured, but if the network is not secured the user may 491expose insecure protocols to attackers on the same network, or enable other 492attackers on the network to pretend to be the user by spoofing their IP 493address. 494.Pp 495.Nm 496is not designed to prevent users from denying service to other users. 497