contrib/pf/authpf/authpf.8

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