contrib/pf/authpf/authpf.8

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