| blob | 31f88b66230453616151ca5c55dd1b8893d85de3 |
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.2 2006/02/17 19:40:12 swildner 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 FILES
267 .Bl -tag -width "/etc/authpf/authpf.conf" -compact
268 .It Pa /etc/authpf/authpf.conf
269 .It Pa /etc/authpf/authpf.allow
270 .It Pa /etc/authpf/authpf.rules
271 .It Pa /etc/authpf/authpf.message
272 .It Pa /etc/authpf/authpf.problem
273 .El
274 .Sh EXAMPLES
275 .Sy Control Files
276 \- To illustrate the user-specific access control
277 mechanisms, let us consider a typical user named bob.
278 Normally, as long as bob can authenticate himself, the
279 .Nm
280 program will load the appropriate rules.
281 Enter the
282 .Pa /etc/authpf/banned/
283 directory.
284 If bob has somehow fallen from grace in the eyes of the
285 powers-that-be, they can prohibit him from using the gateway by creating
286 the file
287 .Pa /etc/authpf/banned/bob
288 containing a message about why he has been banned from using the network.
289 Once bob has done suitable penance, his access may be restored by moving or
290 removing the file
291 .Pa /etc/authpf/banned/bob .
292 .Pp
293 Now consider a workgroup containing alice, bob, carol and dave.
294 They have a
295 wireless network which they would like to protect from unauthorized use.
296 To accomplish this, they create the file
297 .Pa /etc/authpf/authpf.allow
298 which lists their login ids, one per line.
299 At this point, even if eve could authenticate to
300 .Xr sshd 8 ,
301 she would not be allowed to use the gateway.
302 Adding and removing users from
303 the work group is a simple matter of maintaining a list of allowed userids.
304 If bob once again manages to annoy the powers-that-be, they can ban him from
305 using the gateway by creating the familiar
306 .Pa /etc/authpf/banned/bob
307 file.
308 Though bob is listed in the allow file, he is prevented from using
309 this gateway due to the existence of a ban file.
310 .Pp
311 .Sy Distributed Authentication
312 \- It is often desirable to interface with a
313 distributed password system rather than forcing the sysadmins to keep a large
314 number of local password files in sync.
315 The
316 .Xr login.conf 5
317 mechanism in
318 .Ox
319 can be used to fork the right shell.
320 To make that happen,
321 .Xr login.conf 5
322 should have entries that look something like this:
323 .Bd -literal -offset indent
324 shell-default:shell=/bin/csh
326 default:\e
327 ...
328 :shell=/usr/sbin/authpf
330 daemon:\e
331 ...
332 :shell=/bin/csh:\e
333 :tc=default:
335 staff:\e
336 ...
337 :shell=/bin/csh:\e
338 :tc=default:
339 .Ed
340 .Pp
341 Using a default password file, all users will get
342 .Nm
343 as their shell except for root who will get
344 .Pa /bin/csh .
345 .Pp
346 .Sy SSH Configuration
347 \- As stated earlier,
348 .Xr sshd 8
349 must be properly configured to detect and defeat network attacks.
350 To that end, the following options should be added to
351 .Xr sshd_config 5 :
352 .Bd -literal -offset indent
353 Protocol 2
354 ClientAliveInterval 15
355 ClientAliveCountMax 3
356 .Ed
357 .Pp
358 This ensures that unresponsive or spoofed sessions are terminated within a
359 minute, since a hijacker should not be able to spoof ssh keepalive messages.
360 .Pp
361 .Sy Banners
362 \- Once authenticated, the user is shown the contents of
363 .Pa /etc/authpf/authpf.message .
364 This message may be a screen-full of the appropriate use policy, the contents
365 of
366 .Pa /etc/motd
367 or something as simple as the following:
368 .Bd -literal -offset indent
369 This means you will be held accountable by the powers that be
370 for traffic originating from your machine, so please play nice.
371 .Ed
372 .Pp
373 To tell the user where to go when the system is broken,
374 .Pa /etc/authpf/authpf.problem
375 could contain something like this:
376 .Bd -literal -offset indent
377 Sorry, there appears to be some system problem. To report this
378 problem so we can fix it, please phone 1-900-314-1597 or send
379 an email to remove@bulkmailerz.net.
380 .Ed
381 .Pp
382 .Sy Packet Filter Rules
383 \- In areas where this gateway is used to protect a
384 wireless network (a hub with several hundred ports), the default rule set as
385 well as the per-user rules should probably allow very few things beyond
386 encrypted protocols like
387 .Xr ssh 1 ,
388 .Xr ssl 8 ,
389 or
390 .Xr ipsec 4 .
391 On a securely switched network, with plug-in jacks for visitors who are
392 given authentication accounts, you might want to allow out everything.
393 In this context, a secure switch is one that tries to prevent address table
394 overflow attacks.
395 .Pp
396 Example
397 .Pa /etc/pf.conf :
398 .Bd -literal
399 # by default we allow internal clients to talk to us using
400 # ssh and use us as a dns server.
401 internal_if="fxp1"
402 gateway_addr="10.0.1.1"
403 nat-anchor authpf
404 rdr-anchor authpf
405 binat-anchor authpf
406 block in on $internal_if from any to any
407 pass in quick on $internal_if proto tcp from any to $gateway_addr \e
408 port = ssh
409 pass in quick on $internal_if proto udp from any to $gateway_addr \e
410 port = domain
411 anchor authpf
412 .Ed
413 .Pp
414 .Sy For a switched, wired net
415 \- This example
416 .Pa /etc/authpf/authpf.rules
417 makes no real restrictions; it turns the IP address on and off, logging
418 TCP connections.
419 .Bd -literal
420 external_if = "xl0"
421 internal_if = "fxp0"
423 pass in log quick on $internal_if proto tcp from $user_ip to any \e
424 keep state
425 pass in quick on $internal_if from $user_ip to any
426 .Ed
427 .Pp
428 .Sy For a wireless or shared net
429 \- This example
430 .Pa /etc/authpf/authpf.rules
431 could be used for an insecure network (such as a public wireless network) where
432 we might need to be a bit more restrictive.
433 .Bd -literal
434 internal_if="fxp1"
435 ipsec_gw="10.2.3.4"
437 # rdr ftp for proxying by ftp-proxy(8)
438 rdr on $internal_if proto tcp from $user_ip to any port 21 \e
439 -> 127.0.0.1 port 8081
441 # allow out ftp, ssh, www and https only, and allow user to negotiate
442 # ipsec with the ipsec server.
443 pass in log quick on $internal_if proto tcp from $user_ip to any \e
444 port { 21, 22, 80, 443 } flags S/SA
445 pass in quick on $internal_if proto tcp from $user_ip to any \e
446 port { 21, 22, 80, 443 }
447 pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \e
448 keep state
449 pass in quick proto esp from $user_ip to $ipsec_gw
450 .Ed
451 .Pp
452 .Sy Dealing with NAT
453 \- The following
454 .Pa /etc/authpf/authpf.rules
455 shows how to deal with NAT, using tags:
456 .Bd -literal
457 ext_if = "fxp1"
458 ext_addr = 129.128.11.10
459 int_if = "fxp0"
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 keep state
464 .Ed
465 .Pp
466 With the above rules added by
467 .Nm ,
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.
471 .Bd -literal
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)
476 .Ed
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.