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