2 .\" $OpenBSD: authpf.8,v 1.47 2009/01/06 03:11:50 mcbride 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.
24 .Nd authenticating gateway user shell
30 is a user shell for authenticating gateways.
33 rules when a user authenticates and starts a session with
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
39 Combined with properly set up filter rules and secure switches,
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
44 only, and requires the
46 subsystem to be enabled.
50 which allows multiple connections to take
51 place from the same IP address.
52 It is useful primarily in cases where connections are tunneled via
53 the gateway system, and can be directly associated with the user name.
54 It cannot ensure accountability when
55 classifying connections by IP address;
56 in this case the client's IP address
57 is not provided to the packet filter via the
62 Additionally, states associated with the client IP address
63 are not purged when the session is ended.
69 the user's shell needs to be set to
72 .Pa /usr/sbin/authpf-noip .
77 syntax to change filter and translation rules for an individual
78 user or client IP address as long as a user maintains an active
80 session, and logs the successful start and end of a session to
83 retrieves the client's connecting IP address via the
85 environment variable and, after performing additional access checks,
86 reads a template file to determine what filter and translation rules
88 maintains the list of IP addresses of connected users in the
91 On session exit the same rules and table entries that were added at startup
92 are removed, and all states associated with the client's IP address are purged.
96 process stores its rules in a separate ruleset inside a
104 name "authpf" is used, and the ruleset names equal the username and PID of the
106 processes as "username(pid)".
107 The following rules need to be added to the main ruleset
109 in order to cause evaluation of any
112 .Bd -literal -offset indent
113 nat-anchor "authpf/*"
114 rdr-anchor "authpf/*"
115 binat-anchor "authpf/*"
119 The "/*" at the end of the anchor name is required for
121 to process the rulesets attached to the anchor by
123 .Sh FILTER AND TRANSLATION RULES
124 Filter and translation rules for
126 use the same format described in
128 The only difference is that these rules may (and probably should) use
131 which is assigned the connecting IP address whenever
134 Additionally, the macro
136 is assigned the user name.
138 Filter and translation rules are stored in a file called
140 This file will first be searched for in
141 .Pa /etc/authpf/users/$USER/
144 Only one of these files will be used if both are present.
146 Per-user rules from the
147 .Pa /etc/authpf/users/$USER/
148 directory are intended to be used when non-default rules
149 are needed on an individual user basis.
150 It is important to ensure that a user can not write or change
151 these configuration files.
155 file must exist in one of the above locations for
159 Options are controlled by the
160 .Pa /etc/authpf/authpf.conf
162 If the file is empty, defaults are used for all
163 configuration options.
164 The file consists of pairs of the form
167 Currently, the allowed values are as follows:
172 name instead of "authpf".
176 name instead of "authpf_users".
179 On successful invocation,
181 displays a message telling the user he or she has been authenticated.
182 It will additionally display the contents of the file
183 .Pa /etc/authpf/authpf.message
184 if the file exists and is readable.
186 There exist two methods for providing additional granularity to the control
189 - it is possible to set the gateway to explicitly allow users who have
192 and deny access to only a few troublesome individuals.
193 This is done by creating a file with the banned user's login name as the
195 .Pa /etc/authpf/banned/ .
196 The contents of this file will be displayed to a banned user, thus providing
197 a method for informing the user that they have been banned, and where they can
198 go and how to get there if they want to have their service restored.
199 This is the default behaviour.
201 It is also possible to configure
203 to only allow specific users access.
204 This is done by listing their login names, one per line, in
205 .Pa /etc/authpf/authpf.allow .
206 A group of users can also be indicated by prepending "%" to the group name,
207 and all members of a login class can be indicated by prepending "@" to the
209 If "*" is found on a line, then all usernames match.
212 is unable to verify the user's permission to use the gateway, it will
213 print a brief message and die.
214 It should be noted that a ban takes precedence over an allow.
216 On failure, messages will be logged to
218 for the system administrator.
219 The user does not see these, but will be told the system is unavailable due to
220 technical difficulties.
221 The contents of the file
222 .Pa /etc/authpf/authpf.problem
223 will also be displayed if the file exists and is readable.
224 .Sh CONFIGURATION ISSUES
226 maintains the changed filter rules as long as the user maintains an
228 It is important to remember however, that the existence
229 of this session means the user is authenticated.
230 Because of this, it is important to configure
232 to ensure the security of the session, and to ensure that the network
233 through which users connect is secure.
235 should be configured to use the
236 .Ar ClientAliveInterval
238 .Ar ClientAliveCountMax
239 parameters to ensure that a ssh session is terminated quickly if
240 it becomes unresponsive, or if arp or address spoofing is used to
242 Note that TCP keepalives are not sufficient for
243 this, since they are not secure.
244 Also note that the various SSH tunnelling mechanisms,
246 .Ar AllowTcpForwarding
249 should be disabled for
251 users to prevent them from circumventing restrictions imposed by the
252 packet filter ruleset.
255 will remove state table entries that were created during a user's
257 This ensures that there will be no unauthenticated traffic
258 allowed to pass after the controlling
260 session has been closed.
263 is designed for gateway machines which typically do not have regular
264 (non-administrative) users using the machine.
265 An administrator must remember that
267 can be used to modify the filter rules through the environment in
268 which it is run, and as such could be used to modify the filter rules
269 (based on the contents of the configuration files) by regular
271 In the case where a machine has regular users using it, as well
274 as their shell, the regular users should be prevented from running
277 .Pa /etc/authpf/authpf.allow
279 .Pa /etc/authpf/banned/
283 modifies the packet filter and address translation rules, and because
284 of this it needs to be configured carefully.
286 will not run and will exit silently if the
287 .Pa /etc/authpf/authpf.conf
289 After considering the effect
291 may have on the main packet filter rules, the system administrator may
294 by creating an appropriate
295 .Pa /etc/authpf/authpf.conf
299 \- To illustrate the user-specific access control
300 mechanisms, let us consider a typical user named bob.
301 Normally, as long as bob can authenticate himself, the
303 program will load the appropriate rules.
305 .Pa /etc/authpf/banned/
307 If bob has somehow fallen from grace in the eyes of the
308 powers-that-be, they can prohibit him from using the gateway by creating
310 .Pa /etc/authpf/banned/bob
311 containing a message about why he has been banned from using the network.
312 Once bob has done suitable penance, his access may be restored by moving or
314 .Pa /etc/authpf/banned/bob .
316 Now consider a workgroup containing alice, bob, carol and dave.
318 wireless network which they would like to protect from unauthorized use.
319 To accomplish this, they create the file
320 .Pa /etc/authpf/authpf.allow
321 which lists their login ids, group prepended with "%", or login class
322 prepended with "@", one per line.
323 At this point, even if eve could authenticate to
325 she would not be allowed to use the gateway.
326 Adding and removing users from
327 the work group is a simple matter of maintaining a list of allowed userids.
328 If bob once again manages to annoy the powers-that-be, they can ban him from
329 using the gateway by creating the familiar
330 .Pa /etc/authpf/banned/bob
332 Though bob is listed in the allow file, he is prevented from using
333 this gateway due to the existence of a ban file.
335 .Sy Distributed Authentication
336 \- It is often desirable to interface with a
337 distributed password system rather than forcing the sysadmins to keep a large
338 number of local password files in sync.
343 can be used to fork the right shell.
346 should have entries that look something like this:
347 .Bd -literal -offset indent
348 shell-default:shell=/bin/csh
352 :shell=/usr/sbin/authpf
365 Using a default password file, all users will get
367 as their shell except for root who will get
370 .Sy SSH Configuration
371 \- As stated earlier,
373 must be properly configured to detect and defeat network attacks.
374 To that end, the following options should be added to
376 .Bd -literal -offset indent
378 ClientAliveInterval 15
379 ClientAliveCountMax 3
382 This ensures that unresponsive or spoofed sessions are terminated within a
383 minute, since a hijacker should not be able to spoof ssh keepalive messages.
386 \- Once authenticated, the user is shown the contents of
387 .Pa /etc/authpf/authpf.message .
388 This message may be a screen-full of the appropriate use policy, the contents
391 or something as simple as the following:
392 .Bd -literal -offset indent
393 This means you will be held accountable by the powers that be
394 for traffic originating from your machine, so please play nice.
397 To tell the user where to go when the system is broken,
398 .Pa /etc/authpf/authpf.problem
399 could contain something like this:
400 .Bd -literal -offset indent
401 Sorry, there appears to be some system problem. To report this
402 problem so we can fix it, please phone 1-900-314-1597 or send
403 an email to remove@bulkmailerz.net.
406 .Sy Packet Filter Rules
407 \- In areas where this gateway is used to protect a
408 wireless network (a hub with several hundred ports), the default rule set as
409 well as the per-user rules should probably allow very few things beyond
410 encrypted protocols like
415 On a securely switched network, with plug-in jacks for visitors who are
416 given authentication accounts, you might want to allow out everything.
417 In this context, a secure switch is one that tries to prevent address table
423 # by default we allow internal clients to talk to us using
424 # ssh and use us as a dns server.
426 gateway_addr="10.0.1.1"
427 nat-anchor "authpf/*"
428 rdr-anchor "authpf/*"
429 binat-anchor "authpf/*"
430 block in on $internal_if from any to any
431 pass in quick on $internal_if proto tcp from any to $gateway_addr \e
433 pass in quick on $internal_if proto udp from any to $gateway_addr \e
438 .Sy For a switched, wired net
440 .Pa /etc/authpf/authpf.rules
441 makes no real restrictions; it turns the IP address on and off, logging
447 pass in log quick on $internal_if proto tcp from $user_ip to any
448 pass in quick on $internal_if from $user_ip to any
451 .Sy For a wireless or shared net
453 .Pa /etc/authpf/authpf.rules
454 could be used for an insecure network (such as a public wireless network) where
455 we might need to be a bit more restrictive.
460 # rdr ftp for proxying by ftp-proxy(8)
461 rdr on $internal_if proto tcp from $user_ip to any port 21 \e
462 -> 127.0.0.1 port 8021
464 # allow out ftp, ssh, www and https only, and allow user to negotiate
465 # ipsec with the ipsec server.
466 pass in log quick on $internal_if proto tcp from $user_ip to any \e
467 port { 21, 22, 80, 443 }
468 pass in quick on $internal_if proto tcp from $user_ip to any \e
469 port { 21, 22, 80, 443 }
470 pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp
471 pass in quick proto esp from $user_ip to $ipsec_gw
476 .Pa /etc/authpf/authpf.rules
477 shows how to deal with NAT, using tags:
480 ext_addr = 129.128.11.10
482 # nat and tag connections...
483 nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr
484 pass in quick on $int_if from $user_ip to any
485 pass out log quick on $ext_if tagged $user_ip
488 With the above rules added by
490 outbound connections corresponding to each users NAT'ed connections
491 will be logged as in the example below, where the user may be identified
492 from the ruleset name.
494 # tcpdump -n -e -ttt -i pflog0
495 Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \e
496 129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \e
497 16384 <mss 1460,nop,nop,sackOK> (DF)
500 .Sy Using the authpf_users table
503 settings can be implemented without an anchor by just using the "authpf_users"
505 For example, the following
507 lines will give SMTP and IMAP access to logged in users:
509 table <authpf_users> persist
510 pass in on $ext_if proto tcp from <authpf_users> \e
511 to port { smtp imap }
514 It is also possible to use the "authpf_users"
516 in combination with anchors.
519 processing can be sped up by looking up the anchor
520 only for packets coming from logged in users:
522 table <authpf_users> persist
523 anchor "authpf/*" from <authpf_users>
524 rdr-anchor "authpf/*" from <authpf_users>
530 allows only one session per client IP address.
531 However in some cases, such as when connections are tunneled via
535 the connections can be authorized based on the userid of the user instead of
536 the client IP address.
537 In this case it is appropriate to use
539 to allow multiple users behind a NAT gateway to connect.
541 .Pa /etc/authpf/authpf.rules
542 example below, the remote user could tunnel a remote desktop session to their
546 workstation_ip="10.2.3.4"
548 pass out on $internal_if from (self) to $workstation_ip port 3389 \e
552 .Bl -tag -width "/etc/authpf/authpf.conf" -compact
553 .It Pa /etc/authpf/authpf.conf
554 .It Pa /etc/authpf/authpf.allow
555 .It Pa /etc/authpf/authpf.rules
556 .It Pa /etc/authpf/authpf.message
557 .It Pa /etc/authpf/authpf.problem
567 program first appeared in
570 Configuration issues are tricky.
573 connection may be secured, but if the network is not secured the user may
574 expose insecure protocols to attackers on the same network, or enable other
575 attackers on the network to pretend to be the user by spoofing their IP
579 is not designed to prevent users from denying service to other users.