contrib/pf/authpf/authpf.8

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