usr.sbin/authpf/authpf.8

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