2 .\" $OpenBSD: authpf.8,v 1.43 2007/02/24 17:21:04 beck Exp $
4 .\" Copyright (c) 1998-2007 Bob Beck (beck@openbsd.org>. All rights reserved.
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.
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.
23 .Nd authenticating gateway user shell
28 is a user shell for authenticating gateways.
31 rules when a user authenticates and starts a session with
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
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
42 logs the successful start and end of a session to
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.
48 can add filter and translation rules using the syntax described in
53 system be enabled and a
55 file system be mounted at
59 can also maintain the list of IP address of connected users
64 is meant to be used with users who can connect via
69 retrieves the client's connecting IP address via the
71 environment variable and, after performing additional access checks,
72 reads a template file to determine what filter and translation rules
74 On session exit the same rules that were added at startup are removed.
78 process stores its rules in a separate ruleset inside a
86 name "authpf" is used, and the ruleset names equal the username and PID of the
88 processes as "username(pid)".
89 The following rules need to be added to the main ruleset
91 in order to cause evaluation of any
94 .Bd -literal -offset indent
97 binat-anchor "authpf/*"
101 The "/*" at the end of the anchor name is required for
103 to process the rulesets attached to the anchor by
105 .Sh FILTER AND TRANSLATION RULES
106 Filter and translation rules for
108 use the same format described in
110 The only difference is that these rules may (and probably should) use
113 which is assigned the connecting IP address whenever
116 Additionally, the macro
118 is assigned the user name.
120 Filter and translation rules are stored in a file called
122 This file will first be searched for in
123 .Pa /etc/authpf/users/$USER/
126 Only one of these files will be used if both are present.
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.
137 file must exist in one of the above locations for
141 Options are controlled by the
142 .Pa /etc/authpf/authpf.conf
144 If the file is empty, defaults are used for all
145 configuration options.
146 The file consists of pairs of the form
149 Currently, the allowed values are as follows:
154 name instead of "authpf".
158 name instead of "authpf_users".
161 On successful invocation,
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.
168 There exist two methods for providing additional granularity to the control
171 - it is possible to set the gateway to explicitly allow users who have
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
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.
183 It is also possible to configure
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.
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.
195 On failure, messages will be logged to
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
205 maintains the changed filter rules as long as the user maintains an
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
211 to ensure the security of the session, and to ensure that the network
212 through which users connect is secure.
214 should be configured to use the
215 .Ar ClientAliveInterval
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
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,
225 .Ar AllowTcpForwarding
228 should be disabled for
230 users to prevent them from circumventing restrictions imposed by the
231 packet filter ruleset.
234 will remove state table entries that were created during a user's
236 This ensures that there will be no unauthenticated traffic
237 allowed to pass after the controlling
239 session has been closed.
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
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
250 In the case where a machine has regular users using it, as well
253 as their shell, the regular users should be prevented from running
256 .Pa /etc/authpf/authpf.allow
258 .Pa /etc/authpf/banned/
262 modifies the packet filter and address translation rules, and because
263 of this it needs to be configured carefully.
265 will not run and will exit silently if the
266 .Pa /etc/authpf/authpf.conf
268 After considering the effect
270 may have on the main packet filter rules, the system administrator may
273 by creating an appropriate
274 .Pa /etc/authpf/authpf.conf
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
282 program will load the appropriate rules.
284 .Pa /etc/authpf/banned/
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
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
293 .Pa /etc/authpf/banned/bob .
295 Now consider a workgroup containing alice, bob, carol and dave.
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
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
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.
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.
321 can be used to fork the right shell.
324 should have entries that look something like this:
325 .Bd -literal -offset indent
326 shell-default:shell=/bin/csh
330 :shell=/usr/sbin/authpf
343 Using a default password file, all users will get
345 as their shell except for root who will get
348 .Sy SSH Configuration
349 \- As stated earlier,
351 must be properly configured to detect and defeat network attacks.
352 To that end, the following options should be added to
354 .Bd -literal -offset indent
356 ClientAliveInterval 15
357 ClientAliveCountMax 3
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.
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
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.
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.
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
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
401 # by default we allow internal clients to talk to us using
402 # ssh and use us as a dns server.
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
411 pass in quick on $internal_if proto udp from any to $gateway_addr \e
416 .Sy For a switched, wired net
418 .Pa /etc/authpf/authpf.rules
419 makes no real restrictions; it turns the IP address on and off, logging
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
429 .Sy For a wireless or shared net
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.
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
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
454 .Pa /etc/authpf/authpf.rules
455 shows how to deal with NAT, using tags:
458 ext_addr = 129.128.11.10
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
466 With the above rules added by
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.
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)
478 .Sy Using the authpf_users table
481 settings can be implemented without an anchor by just using the "authpf_users"
483 For example, the following
485 lines will give SMTP and IMAP access to logged in users:
487 table <authpf_users> persist
488 pass in on $ext_if proto tcp from <authpf_users> \e
489 to port { smtp imap }
492 It is also possible to use the "authpf_users"
494 in combination with anchors.
497 processing can be sped up by looking up the anchor
498 only for packets coming from logged in users:
500 table <authpf_users> persist
501 anchor "authpf/*" from <authpf_users>
502 rdr-anchor "authpf/*" from <authpf_users>
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
521 program first appeared in
524 Configuration issues are tricky.
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
533 is not designed to prevent users from denying service to other users.