1.\" $OpenBSD: authpf.8,v 1.31 2003/12/10 04:10:37 beck 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 April 21, 2018 28.Dt AUTHPF 8 29.Os 30.Sh NAME 31.Nm authpf 32.Nd authenticating gateway user shell 33.Sh SYNOPSIS 34.Nm 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 username and PID of the 88.Nm 89processes as "username(pid)". 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 FILES 266.Bl -tag -width "/etc/authpf/authpf.conf" -compact 267.It Pa /etc/authpf/authpf.conf 268.It Pa /etc/authpf/authpf.allow 269.It Pa /etc/authpf/authpf.rules 270.It Pa /etc/authpf/authpf.message 271.It Pa /etc/authpf/authpf.problem 272.El 273.Sh EXAMPLES 274.Sy Control Files 275\- To illustrate the user-specific access control 276mechanisms, let us consider a typical user named bob. 277Normally, as long as bob can authenticate himself, the 278.Nm 279program will load the appropriate rules. 280Enter the 281.Pa /etc/authpf/banned/ 282directory. 283If bob has somehow fallen from grace in the eyes of the 284powers-that-be, they can prohibit him from using the gateway by creating 285the file 286.Pa /etc/authpf/banned/bob 287containing a message about why he has been banned from using the network. 288Once bob has done suitable penance, his access may be restored by moving or 289removing the file 290.Pa /etc/authpf/banned/bob . 291.Pp 292Now consider a workgroup containing alice, bob, carol and dave. 293They have a 294wireless network which they would like to protect from unauthorized use. 295To accomplish this, they create the file 296.Pa /etc/authpf/authpf.allow 297which lists their login ids, one per line. 298At this point, even if eve could authenticate to 299.Xr sshd 8 , 300she would not be allowed to use the gateway. 301Adding and removing users from 302the work group is a simple matter of maintaining a list of allowed userids. 303If bob once again manages to annoy the powers-that-be, they can ban him from 304using the gateway by creating the familiar 305.Pa /etc/authpf/banned/bob 306file. 307Though bob is listed in the allow file, he is prevented from using 308this gateway due to the existence of a ban file. 309.Pp 310.Sy Distributed Authentication 311\- It is often desirable to interface with a 312distributed password system rather than forcing the sysadmins to keep a large 313number of local password files in sync. 314The 315.Xr login.conf 5 316mechanism in 317.Ox 318can be used to fork the right shell. 319To make that happen, 320.Xr login.conf 5 321should have entries that look something like this: 322.Bd -literal -offset indent 323shell-default:shell=/bin/csh 324 325default:\e 326 ... 327 :shell=/usr/sbin/authpf 328 329daemon:\e 330 ... 331 :shell=/bin/csh:\e 332 :tc=default: 333 334staff:\e 335 ... 336 :shell=/bin/csh:\e 337 :tc=default: 338.Ed 339.Pp 340Using a default password file, all users will get 341.Nm 342as their shell except for root who will get 343.Pa /bin/csh . 344.Pp 345.Sy SSH Configuration 346\- As stated earlier, 347.Xr sshd 8 348must be properly configured to detect and defeat network attacks. 349To that end, the following options should be added to 350.Xr sshd_config 5 : 351.Bd -literal -offset indent 352Protocol 2 353ClientAliveInterval 15 354ClientAliveCountMax 3 355.Ed 356.Pp 357This ensures that unresponsive or spoofed sessions are terminated within a 358minute, since a hijacker should not be able to spoof ssh keepalive messages. 359.Pp 360.Sy Banners 361\- Once authenticated, the user is shown the contents of 362.Pa /etc/authpf/authpf.message . 363This message may be a screen-full of the appropriate use policy, the contents 364of 365.Pa /etc/motd 366or something as simple as the following: 367.Bd -literal -offset indent 368This means you will be held accountable by the powers that be 369for traffic originating from your machine, so please play nice. 370.Ed 371.Pp 372To tell the user where to go when the system is broken, 373.Pa /etc/authpf/authpf.problem 374could contain something like this: 375.Bd -literal -offset indent 376Sorry, there appears to be some system problem. To report this 377problem so we can fix it, please phone 1-900-314-1597 or send 378an email to remove@bulkmailerz.net. 379.Ed 380.Pp 381.Sy Packet Filter Rules 382\- In areas where this gateway is used to protect a 383wireless network (a hub with several hundred ports), the default rule set as 384well as the per-user rules should probably allow very few things beyond 385encrypted protocols like 386.Xr ssh 1 387or 388.Xr ssl 8 . 389On a securely switched network, with plug-in jacks for visitors who are 390given authentication accounts, you might want to allow out everything. 391In this context, a secure switch is one that tries to prevent address table 392overflow attacks. 393.Pp 394Example 395.Pa /etc/pf.conf : 396.Bd -literal 397# by default we allow internal clients to talk to us using 398# ssh and use us as a dns server. 399internal_if="fxp1" 400gateway_addr="10.0.1.1" 401nat-anchor authpf 402rdr-anchor authpf 403binat-anchor authpf 404block in on $internal_if from any to any 405pass in quick on $internal_if proto tcp from any to $gateway_addr \e 406 port = ssh 407pass in quick on $internal_if proto udp from any to $gateway_addr \e 408 port = domain 409anchor authpf 410.Ed 411.Pp 412.Sy For a switched, wired net 413\- This example 414.Pa /etc/authpf/authpf.rules 415makes no real restrictions; it turns the IP address on and off, logging 416TCP connections. 417.Bd -literal 418external_if = "xl0" 419internal_if = "fxp0" 420 421pass in log quick on $internal_if proto tcp from $user_ip to any \e 422 keep state 423pass in quick on $internal_if from $user_ip to any 424.Ed 425.\".Pp 426.\".Sy For a wireless or shared net 427.\"\- This example 428.\".Pa /etc/authpf/authpf.rules 429.\"could be used for an insecure network (such as a public wireless network) where 430.\"we might need to be a bit more restrictive. 431.\".Bd -literal 432.\"internal_if="fxp1" 433.\"ipsec_gw="10.2.3.4" 434.\" 435.\"# rdr ftp for proxying by ftp-proxy(8) 436.\"rdr on $internal_if proto tcp from $user_ip to any port 21 \e 437.\" -> 127.0.0.1 port 8081 438.\" 439.\"# allow out ftp, ssh, www and https only, and allow user to negotiate 440.\"# ipsec with the ipsec server. 441.\"pass in log quick on $internal_if proto tcp from $user_ip to any \e 442.\" port { 21, 22, 80, 443 } flags S/SA 443.\"pass in quick on $internal_if proto tcp from $user_ip to any \e 444.\" port { 21, 22, 80, 443 } 445.\"pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \e 446.\" keep state 447.\"pass in quick proto esp from $user_ip to $ipsec_gw 448.\".Ed 449.Pp 450.Sy Dealing with NAT 451\- The following 452.Pa /etc/authpf/authpf.rules 453shows how to deal with NAT, using tags: 454.Bd -literal 455ext_if = "fxp1" 456ext_addr = 129.128.11.10 457int_if = "fxp0" 458# nat and tag connections... 459nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr 460pass in quick on $int_if from $user_ip to any 461pass out log quick on $ext_if tagged $user_ip keep state 462.Ed 463.Pp 464With the above rules added by 465.Nm , 466outbound connections corresponding to each users NAT'ed connections 467will be logged as in the example below, where the user may be identified 468from the ruleset name. 469.Bd -literal 470# tcpdump -n -e -ttt -i pflog0 471Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \e 472129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \e 47316384 <mss 1460,nop,nop,sackOK> (DF) 474.Ed 475.Sh SEE ALSO 476.Xr pf 4 , 477.Xr pf.conf 5 , 478.Xr ftp-proxy 8 479.Sh HISTORY 480The 481.Nm 482program first appeared in 483.Ox 3.1 . 484.Sh BUGS 485Configuration issues are tricky. 486The authenticating 487.Xr ssh 1 488connection may be secured, but if the network is not secured the user may 489expose insecure protocols to attackers on the same network, or enable other 490attackers on the network to pretend to be the user by spoofing their IP 491address. 492.Pp 493.Nm 494is not designed to prevent users from denying service to other users. 495