usr.sbin/authpf/authpf.8

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