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