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