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