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