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