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