Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / tcp_wrappers / README
1 @(#) README 1.30 97/03/21 19:27:21
2
3 This is the 7.6 version of the TCP/IP daemon wrapper package.
4
5 Thank you for using this program. If you like it, send me a postcard.
6 My postal address is at the bottom of this file.
7
8 Read the BLURB file for a brief summary of what is new. The CHANGES
9 file gives a complete account of differences with respect to previous
10 releases.
11
12 Announcements of new releases of this software are posted to Usenet
13 (comp.security.unix, comp.unix.admin), to the cert-tools mailing list,
14 and to a dedicated mailing list.  You can subscribe to the dedicated
15 mailing list by sending an email message to majordomo@wzv.win.tue.nl
16 with in the body (not subject):  subscribe tcp-wrappers-announce.
17
18 Table of contents
19 -----------------
20
21     1 - Introduction
22     2 - Disclaimer
23     3 - Tutorials
24                 3.1 - How it works
25                 3.2 - Where the logging information goes
26     4 - Features
27                 4.1 - Access control
28                 4.2 - Host name spoofing
29                 4.3 - Host address spoofing
30                 4.4 - Client username lookups
31                 4.5 - Language extensions
32                 4.6 - Multiple ftp/gopher/www archives on one host
33                 4.7 - Banner messages
34                 4.8 - Sequence number guessing
35     5 - Other works
36                 5.1 - Related documents
37                 5.2 - Related software
38     6 - Limitations
39                 6.1 - Known wrapper limitations
40                 6.2 - Known system software bugs
41     7 - Configuration and installation
42                 7.1 - Easy configuration and installation
43                 7.2 - Advanced configuration and installation
44                 7.3 - Daemons with arbitrary path names
45                 7.4 - Building and testing the access control rules
46                 7.5 - Other applications
47     8 - Acknowledgements
48
49 1 - Introduction
50 ----------------
51
52 With this package you can monitor and filter incoming requests for the
53 SYSTAT, FINGER, FTP, TELNET, RLOGIN, RSH, EXEC, TFTP, TALK, and other
54 network services.
55
56 It supports both 4.3BSD-style sockets and System V.4-style TLI. Praise
57 yourself lucky if you don't know what that means.
58
59 The package provides tiny daemon wrapper programs that can be installed
60 without any changes to existing software or to existing configuration
61 files.  The wrappers report the name of the client host and of the
62 requested service; the wrappers do not exchange information with the
63 client or server applications, and impose no overhead on the actual
64 conversation between the client and server applications.
65
66 Optional features are: access control to restrict what systems can
67 connect to what network daemons; client user name lookups with the RFC
68 931 etc. protocol; additional protection against hosts that pretend to
69 have someone elses host name; additional protection against hosts that
70 pretend to have someone elses host address.
71
72 The programs are very portable. Build procedures are provided for many
73 common (and not so common) environments, and guidelines are provided in
74 case your environment is not among them.
75
76 Requirements are that network daemons are spawned by a super server
77 such as the inetd; a 4.3BSD-style socket programming interface and/or
78 System V.4-style TLI programming interface; and the availability of a
79 syslog(3) library and of a syslogd(8) daemon.  The wrappers should run
80 without modification on any system that satisfies these requirements.
81 Workarounds have been implemented for several common bugs in systems
82 software.
83
84 What to do if this is your first encounter with the wrapper programs:
85 1) read the tutorial sections for an introduction to the relevant
86 concepts and terminology; 2) glance over the security feature sections
87 in this document; 3) follow the installation instructions (easy or
88 advanced). I recommend that you first use the default security feature
89 settings.  Run the wrappers for a few days to become familiar with
90 their logs, before doing anything drastic such as cutting off access or
91 installing booby traps.
92
93 2 - Disclaimer
94 --------------
95
96 The wrapper programs rely on source address information obtained from
97 network packets. This information is provided by the client host. It is
98 not 100 percent reliable, although the wrappers do their best to expose
99 forgeries.
100
101 In the absence of cryptographic protection of message contents, and of
102 cryptographic authentication of message originators, all data from the
103 network should be treated with sound scepticism.
104
105 THIS RESTRICTION IS BY NO MEANS SPECIFIC TO THE TCP/IP PROTOCOLS.
106
107 3 - Tutorials
108 -------------
109
110 The tutorial sections give a gentle introduction to the operation of
111 the wrapper programs, and introduce some of the terminology that is
112 used in the remainder of the document: client, server, the inetd and
113 syslogd daemons, and their configuration files.
114
115 3.1 - How it works
116 ------------------
117
118 Almost every application of the TCP/IP protocols is based on a client-
119 server model. For example, when a user invokes the telnet command to
120 connect to one of your systems, a telnet server process is executed on
121 the target host. The telnet server process connects the user to a login
122 process. A few examples of client and server programs are shown in the
123 table below:
124
125               client   server    application
126               --------------------------------
127               telnet   telnetd   remote login
128               ftp      ftpd      file transfer
129               finger   fingerd   show users
130
131 The usual approach is to run one single daemon process that waits for
132 all kinds of incoming network connections. Whenever a connection is
133 established, this daemon (usually called inetd) runs the appropriate
134 server program and goes back to sleep, waiting for other connections.
135
136 The wrapper programs rely on a simple, but powerful mechanism.  Instead
137 of directly running the desired server program, the inetd is tricked
138 into running a small wrapper program. The wrapper logs the client host
139 name or address and performs some additional checks.  When all is well,
140 the wrapper executes the desired server program and goes away.
141
142 The wrapper programs have no interaction with the client user (or with
143 the client process).  Nor do the wrappers interact with the server
144 application. This has two major advantages: 1) the wrappers are
145 application-independent, so that the same program can protect many
146 kinds of network services; 2) no interaction also means that the
147 wrappers are invisible from outside (at least for authorized users).
148
149 Another important property is that the wrapper programs are active only
150 when the initial contact between client and server is established. Once
151 a wrapper has done its work there is no overhead on the client-server
152 conversation.
153
154 The simple mechanism has one major drawback: the wrappers go away after
155 the initial contact between client and server processes, so the
156 wrappers are of little use with network daemons that service more than
157 one client.  The wrappers would only see the first client attempt to
158 contact such a server. The NFS mount daemon is a typical example of a
159 daemon that services requests from multiple clients. See the section on
160 related software for ways to deal with such server programs.
161
162 There are two ways to use the wrapper programs:
163
164 1) The easy way: move network daemons to some other directory and fill
165    the resulting holes with copies of the wrapper programs.  This
166    approach involves no changes to system configuration files, so there
167    is very little risk of breaking things.
168
169 2) The advanced way: leave the network daemons alone and modify the
170    inetd configuration file.  For example, an entry such as:
171
172      tftp  dgram  udp  wait  root  /usr/etc/tcpd  in.tftpd -s /tftpboot
173
174    When a tftp request arrives, inetd will run the wrapper program
175    (tcpd) with a process name `in.tftpd'.  This is the name that the
176    wrapper will use when logging the request and when scanning the
177    optional access control tables.  `in.tftpd' is also the name of the
178    server program that the wrapper will attempt to run when all is
179    well.  Any arguments (`-s /tftpboot' in this particular example) are
180    transparently passed on to the server program.
181
182 For an account of the history of the wrapper programs, with real-life
183 examples, see the section below on related documents.
184
185 3.2 - Where the logging information goes
186 ----------------------------------------
187
188 The wrapper programs send their logging information to the syslog
189 daemon (syslogd). The disposition of the wrapper logs is determined by
190 the syslog configuration file (usually /etc/syslog.conf). Messages are
191 written to files, to the console, or are forwarded to a @loghost. Some
192 syslogd versions can even forward messages down a |pipeline.
193
194 Older syslog implementations (still found on Ultrix systems) only
195 support priority levels ranging from 9 (debug-level messages) to 0
196 (alerts). All logging information of the specified priority level or
197 more urgent is written to the same destination.  In the syslog.conf
198 file, priority levels are specified in numerical form.  For example,
199
200     8/usr/spool/mqueue/syslog
201
202 causes all messages with priority 8 (informational messages), and
203 anything that is more urgent, to be appended to the file
204 /usr/spool/mqueue/syslog.
205
206 Newer syslog implementations support message classes in addition to
207 priority levels.  Examples of message classes are: mail, daemon, auth
208 and news. In the syslog.conf file, priority levels are specified with
209 symbolic names: debug, info, notice, ..., emerg. For example,
210
211     mail.debug                  /var/log/syslog
212
213 causes all messages of class mail with priority debug (or more urgent)
214 to be appended to the /var/log/syslog file.
215
216 By default, the wrapper logs go to the same place as the transaction
217 logs of the sendmail daemon. The disposition can be changed by editing
218 the Makefile and/or the syslog.conf file. Send a `kill -HUP' to the
219 syslogd after changing its configuration file. Remember that syslogd,
220 just like sendmail, insists on one or more TABs between the left-hand
221 side and the right-hand side expressions in its configuration file.
222
223 Solaris 2.x note: the syslog daemon depends on the m4 macro processor.
224 The m4 program is installed as part of the software developer packages.
225
226 Trouble shooting note: when the syslogging does not work as expected,
227 run the program by hand (`syslogd -d') and see what really happens.
228
229 4 - Features
230 ------------
231
232 4.1 - Access control
233 --------------------
234
235 When compiled with -DHOSTS_ACCESS, the wrapper programs support a
236 simple form of access control.  Access can be controlled per host, per
237 service, or combinations thereof. The software provides hooks for the
238 execution of shell commands when an access control rule fires; this
239 feature may be used to install "booby traps".  For details, see the
240 hosts_access.5 manual page, which is in `nroff -man' format. A later
241 section describes how you can test your access control rules.
242
243 Access control can also be used to connect clients to the "right"
244 service. What is right may depend on the requested service, the origin
245 of the request, and what host address the client connects to. Examples:
246
247 (1) A gopher or www database speaks native language when contacted from
248     within the country, otherwise it speaks English.
249
250 (2) A service provider offers different ftp, gopher or www services
251     with different internet hostnames from one host (section 4.6).
252
253 Access control is enabled by default. It can be turned off by editing
254 the Makefile, or by providing no access control tables. The install
255 instructions below describe the Makefile editing process.
256
257 The hosts_options.5 manual page (`nroff -man' format) documents an
258 extended version of the access control language. The extensions are
259 disabled by default. See the section below on language extensions.
260
261 Later System V implementations provide the Transport Level Interface
262 (TLI), a network programming interface that performs functions similar
263 to the Berkeley socket programming interface.  Like Berkeley sockets,
264 TLI was designed to cover multiple protocols, not just Internet.
265
266 When the wrapper discovers that the TLI interface sits on top of a
267 TCP/IP or UDP/IP conversation it uses this knowledge to provide the
268 same functions as with traditional socket-based applications.  When
269 some other protocol is used underneath TLI, the host address will be
270 some universal magic cookie that may not even be usable for access
271 control purposes.
272
273 4.2 - Host name spoofing
274 ------------------------
275
276 With some network applications, such as RSH or RLOGIN, the client host
277 name plays an important role in the authentication process. Host name
278 information can be reliable when lookups are done from a _local_ hosts
279 table, provided that the client IP address can be trusted.
280
281 With _distributed_ name services, authentication schemes that rely on
282 host names become more problematic. The security of your system now may
283 depend on some far-away DNS (domain name server) outside your own
284 control. 
285
286 The wrapper programs verify the client host name that is returned by
287 the address->name DNS server, by asking for a second opinion.  To this
288 end, the programs look at the name and addresses that are returned by
289 the name->address DNS server, which may be an entirely different host. 
290
291 If any name or address discrepancies are found, or if the second DNS
292 opinion is not available, the wrappers assume that one of the two name
293 servers is lying, and assume that the client host pretends to have
294 someone elses host name.
295
296 When compiled with -DPARANOID, the wrappers will always attempt to look
297 up and double check the client host name, and will always refuse
298 service in case of a host name/address discrepancy.  This is a
299 reasonable policy for most systems.
300
301 When compiled without -DPARANOID, the wrappers by default still perform
302 hostname lookup. You can match hosts with a name/address discrepancy
303 with the PARANOID wildcard and decide whether or not to grant service.
304
305 Automatic hostname verification is enabled by default. Automatic
306 hostname lookups and verification can be turned off by editing the
307 Makefile. The configuration and installation section below describes
308 the Makefile editing process.
309
310 4.3 - Host address spoofing
311 ---------------------------
312
313 While host name spoofing can be found out by asking a second opinion,
314 it is much harder to find out that a host claims to have someone elses
315 network address. And since host names are deduced from network
316 addresses, address spoofing is at least as effective as name spoofing.
317
318 The wrapper programs can give additional protection against hosts that
319 claim to have an address that lies outside their own network.  For
320 example, some far-away host that claims to be a trusted host within
321 your own network. Such things are possible even while the impersonated
322 system is up and running.
323
324 This additional protection is not an invention of my own; it has been
325 present for at least five years in the BSD rsh and rlogin daemons.
326 Unfortunately, that feature was added *after* 4.3 BSD came out, so that
327 very few, if any, UNIX vendors have adopted it.  Our site, and many
328 other ones, has been running these enhanced daemons for several years,
329 and without any ill effects.
330
331 When the wrapper programs are compiled with -DKILL_IP_OPTIONS, the
332 programs refuse to service TCP connections with IP source routing
333 options. -DKILL_IP_OPTIONS is not needed on modern UNIX systems
334 that can stop source-routed traffic in the kernel. Examples are
335 4.4BSD derivatives, Solaris 2.x, and Linux. See your system manuals
336 for details.
337
338 If you are going to use this feature on SunOS 4.1.x you should apply
339 patch 100804-03+ or 101790-something depending on your SunOS version.
340 Otherwise you may experience "BAD TRAP" and "Data fault" panics when
341 the getsockopt() system call is executed after a TCP RESET has been
342 received. This is a kernel bug, it is not the fault of the wrappers.
343
344 The feature is disabled by default. It can be turned on by editing the
345 Makefile.  The configuration and installation section below describes
346 the Makefile editing process.
347
348 UDP services do not benefit from this additional protection. With UDP,
349 all you can be certain of is the network packet's destination address.
350
351 4.4 - Client username lookups
352 -----------------------------
353
354 The protocol proposed in RFC 931 provides a means to obtain the client
355 user name from the client host.  The requirement is that the client
356 host runs an RFC 931-compliant daemon. The information provided by such
357 a daemon is not intended to be used for authentication purposes, but it
358 can provide additional information about the owner of a TCP connection.
359
360 The RFC 931 protocol has diverged into different directions (IDENT,
361 TAP, RFC 1413). To add to the confusion, they all use the same network
362 port.  The daemon wrappers implement a common subset of the protocols.
363
364 There are some limitations: the number of hosts that run an RFC 931 (or
365 compatible) daemon is limited (but growing); client user name lookups
366 do not work for datagram (UDP) services. More seriously, client user
367 name lookups can cause noticeable delays with connections from non-UNIX
368 PCs. Recent PC software seem to have fixed this (for example NCSA
369 telnet). The wrappers use a 10-second timeout for RFC931 lookups, to
370 accommodate slow networks and slow hosts.
371
372 By default, the wrappers will do username lookup only when the access
373 control rules require them to do so (via user@host client patterns, see
374 the hosts_access.5 manual page) or when the username is needed for
375 %<letter> expansions.
376
377 You can configure the wrappers to always perform client username
378 lookups, by editing the Makefile.  The client username lookup timeout
379 period (10 seconds default) can be changed by editing the Makefile. The
380 installation sections below describe the Makefile editing process.
381
382 On System V with TLI-based network services, client username lookups
383 will be possible only when the underlying network protocol is TCP/IP.
384
385 4.5 - Language extensions
386 -------------------------
387
388 The wrappers sport only a limited number of features. This is for a
389 good reason: programs that run at high privilege levels must be easy to
390 verify. And the smaller a program, the easier to verify. There is,
391 however, a provision to add features.
392
393 The options.c module provides a framework for language extensions.
394 Quite a few extensions have already been implemented; they are
395 documented in the hosts_options.5 document, which is in `nroff -man'
396 format. Examples: changing the severity level at which a request for
397 service is logged; "allow" and "deny" keywords; running a customized
398 server instead of the standard one; many others.
399
400 The language extensions are not enabled by default because they
401 introduce an incompatible change to the access control language
402 syntax.  Instructions to enable the extensions are given in the
403 Makefile.
404
405 4.6 - Multiple ftp/gopher/www archives on one host
406 --------------------------------------------------
407
408 Imagine one host with multiple internet addresses. These addresses do
409 not need to have the same internet hostname. Thus, it is possible to
410 offer services with different internet hostnames from just one host.
411
412 Service providers can use this to offer organizations a presence on the
413 "net" with their own internet hostname, even when those organizations
414 aren't connected to the Internet at all.  To the end user it makes no
415 difference, because applications use internet hostnames.
416
417 There are several ways to assign multiple addresses to one machine.
418 The nice way is to take an existing network interface and to assign
419 additional internet addresses with the `ifconfig' command. Examples:
420
421     Solaris 2:  ifconfig le0:1 <address> netmask <mask> up
422     4.4 BSD:    ifconfig en0 alias <address> netmask <mask>
423
424 On other systems one has to increase the number of network interfaces:
425 either with hardware interfaces, or with pseudo interfaces like SLIP or
426 PPP.  The interfaces do not need to be attached to anything. They just
427 need to be up and to be assigned a suitable internet address and mask.
428
429 With the wrapper software, `daemon@host' access control patterns can be
430 used to distinguish requests by the network address that they are aimed
431 at.  Judicious use of the `twist' option (see the hosts_options.5 file,
432 `nroff -man' format) can guide the requests to the right server.  These
433 can be servers that live in separate chroot areas, or servers modified
434 to take additional context from the command line, or a combination.
435
436 Another way is to modify gopher or www listeners so that they bind to
437 only one specific network address. Multiple gopher or www servers can
438 then be run side by side, each taking requests sent to its respective
439 network address.
440
441 4.7 - Banner messages
442 ---------------------
443
444 Some sites are required to present an informational message to users
445 before they attempt to login.  Banner messages can also be useful when
446 denying service:  instead of simply dropping the connection a polite
447 explanation is given first. Finally, banners can be used to give your
448 system a more personal touch.
449
450 The wrapper software provides easy-to-use tools to generate pre-login
451 banners for ftp, telnet, rlogin etc. from a single prototype banner
452 textfile.  Details on banners and on-the-fly %<letter> expansions are
453 given in the hosts_options.5 manual page (`nroff -man' format). An
454 example is given in the file Banners.Makefile.
455
456 In order to support banner messages the wrappers have to be built with
457 language extensions enabled. See the section on language extensions.
458
459 4.8 - Sequence number guessing
460 ------------------------------
461
462 Recently, systems came under attack from intruders that exploited a
463 well-known weakness in TCP/IP sequence number generators.  This
464 weakness allows intruders to impersonate trusted hosts. Break-ins have
465 been reported via the rsh service. In fact, any network service can be
466 exploited that trusts the client host name or address.
467
468 A long-term solution is to stop using network services that trust the
469 client host name or address, and to use data encryption instead.
470
471 A short-term solution, as outlined in in CERT advisory CA-95:01, is to
472 configure network routers so that they discard datagrams from "outside"
473 with an "inside" source address. This approach is most fruitful when
474 you do not trust any hosts outside your local network.
475
476 The IDENT (RFC931 etc.) client username lookup protocol can help to
477 detect host impersonation attacks.  Before accepting a client request,
478 the wrappers can query the client's IDENT server and find out that the
479 client never sent that request.
480
481 When the client host provides IDENT service, a negative IDENT lookup
482 result (the client matches `UNKNOWN@host') is strong evidence of a host
483 impersonation attack.
484
485 A positive IDENT lookup result (the client matches `KNOWN@host') is
486 less trustworthy.  It is possible for an attacker to spoof both the
487 client request and the IDENT lookup connection, although doing so
488 should be much harder than spoofing just a client request. Another
489 possibility is that the client's IDENT server is lying.
490
491 Client username lookups are described in more detail in a previous
492 section. Pointers to IDENT daemon software are described in the section
493 on related software.
494
495 5 - Other works
496 ---------------
497
498 5.1 - Related documents
499 -----------------------
500
501 The war story behind the tcp wrapper tools is described in:
502
503     W.Z. Venema, "TCP WRAPPER, network monitoring, access control and
504     booby traps", UNIX Security Symposium III Proceedings (Baltimore),
505     September 1992. 
506
507     ftp.win.tue.nl:/pub/security/tcp_wrapper.ps.Z (postscript)
508     ftp.win.tue.nl:/pub/security/tcp_wrapper.txt.Z (flat text)
509
510 The same cracker is also described in:
511
512     W.R. Cheswick, "An Evening with Berferd, In Which a Cracker is
513     Lured, Endured, and Studied", Proceedings of the Winter USENIX
514     Conference (San Francisco), January 1992.
515
516     research.att.com:/dist/internet_security/berferd.ps
517
518 An updated version of the latter paper appeared in:
519
520     W.R. Cheswick, S.M. Bellovin, "Firewalls and Internet Security",
521     Addison-Wesley, 1994.
522
523 Discussions on internet firewalls are archived on ftp.greatcircle.com.
524 Subscribe to the mailing list by sending a message to 
525
526     majordomo@greatcircle.com
527
528 With in the body (not subject): subscribe firewalls.
529
530 5.2 - Related software
531 ----------------------
532
533 Network daemons etc. with enhanced logging capabilities can generate
534 massive amounts of information: our 150+ workstations generate several
535 hundred kbytes each day. egrep-based filters can help to suppress some
536 of the noise.  A more powerful tool is the Swatch monitoring system by
537 Stephen E. Hansen and E. Todd Atkins. Swatch can process log files in
538 real time and can associate arbitrary actions with patterns; its
539 applications are by no means restricted to security.  Swatch is
540 available ftp.stanford.edu, directory /general/security-tools/swatch.
541
542 Socks, described in the UNIX Security III proceedings, can be used to
543 control network traffic from hosts on an internal network, through a
544 firewall host, to the outer world. Socks consists of a daemon that is
545 run on the firewall host, and of a library with routines that redirect
546 application socket calls through the firewall daemon.  Socks is
547 available from s1.gov in /pub/firewalls/socks.tar.Z.
548
549 For a modified Socks version by Ying-Da Lee (ylee@syl.dl.nec.com) try
550 ftp.nec.com, directory /pub/security/socks.cstc.
551
552 Tcpr is a set of perl scripts by Paul Ziemba that enable you to run ftp
553 and telnet commands across a firewall. Unlike socks it can be used with
554 unmodified client software. Available from ftp.alantec.com, /pub/tcpr.
555
556 The TIS firewall toolkit provides a multitude of tools to build your
557 own internet firewall system. ftp.tis.com, directory /pub/firewalls.
558
559 Versions of rshd and rlogind, modified to report the client user name
560 in addition to the client host name, are available for anonymous ftp
561 (ftp.win.tue.nl:/pub/security/logdaemon-XX.tar.Z).  These programs are
562 drop-in replacements for SunOS 4.x, Ultrix 4.x, SunOS 5.x and HP-UX
563 9.x. This archive also contains ftpd/rexecd/login versions that support
564 S/Key or SecureNet one-time passwords in addition to traditional UNIX
565 reusable passwords.
566
567 The securelib shared library by William LeFebvre can be used to control
568 access to network daemons that are not run under control of the inetd
569 or that serve more than one client, such as the NFS mount daemon that
570 runs until the machine goes down.  Available from eecs.nwu.edu, file
571 /pub/securelib.tar.
572
573 xinetd (posted to comp.sources.unix) is an inetd replacement that
574 provides, among others, logging, username lookup and access control.
575 However, it does not support the System V TLI services, and involves
576 much more source code than the daemon wrapper programs. Available
577 from ftp.uu.net, directory /usenet/comp.sources.unix.
578
579 netlog from Texas A&M relies on the SunOS 4.x /dev/nit interface to
580 passively watch all TCP and UDP network traffic on a network.  The
581 current version is on net.tamu.edu in /pub/security/TAMU.
582
583 Where shared libraries or router-based packet filtering are not an
584 option, an alternative portmap daemon can help to prevent hackers
585 from mounting your NFS file systems using the proxy RPC facility.
586 ftp.win.tue.nl:/pub/security/portmap-X.shar.Z was tested with SunOS
587 4.1.X Ultrix 3.0 and Ultrix 4.x, HP-UX 8.x and some version of AIX. The
588 protection is less effective than that of the securelib library because
589 portmap is mostly a dictionary service.
590
591 An rpcbind replacement (the Solaris 2.x moral equivalent of portmap)
592 can be found on ftp.win.tue.nl in /pub/security. It prevents hackers
593 from mounting your NFS file systems by using the proxy RPC facility.
594
595 Source for a portable RFC 931 (TAP, IDENT, RFC 1413) daemon by Peter
596 Eriksson is available from ftp.lysator.liu.se:/pub/ident/servers.
597
598 Some TCP/IP implementations come without syslog library. Some come with
599 the library but have no syslog daemon. A replacement can be found in
600 ftp.win.tue.nl:/pub/security/surrogate-syslog.tar.Z.  The fakesyslog
601 library that comes with the nntp sources reportedly works well, too.
602
603 6 - Limitations
604 ---------------
605
606 6.1 - Known wrapper limitations
607 -------------------------------
608
609 Many UDP (and rpc/udp) daemons linger around for a while after they
610 have serviced a request, just in case another request comes in.  In the
611 inetd configuration file these daemons are registered with the `wait'
612 option. Only the request that started such a daemon will be seen by the
613 wrappers.  Such daemons are better protected with the securelib shared
614 library (see: Related software).
615
616 The wrappers do not work with RPC services over TCP. These services are
617 registered as rpc/tcp in the inetd configuration file. The only non-
618 trivial service that is affected by this limitation is rexd, which is
619 used by the on(1) command. This is no great loss.  On most systems,
620 rexd is less secure than a wildcard in /etc/hosts.equiv.
621
622 Some RPC requests (for example: rwall, rup, rusers) appear to come from
623 the server host. What happens is that the client broadcasts its request
624 to all portmap daemons on its network; each portmap daemon forwards the
625 request to a daemon on its own system. As far as the rwall etc.  daemons
626 know, the request comes from the local host.
627
628 Portmap and RPC (e.g. NIS and NFS) (in)security is a topic in itself.
629 See the section in this document on related software.
630
631 6.2 - Known system software bugs
632 --------------------------------
633
634 Workarounds have been implemented for several bugs in system software.
635 They are described in the Makefile. Unfortunately, some system software
636 bugs cannot be worked around. The result is loss of functionality.
637
638 IRIX has so many bugs that it has its own README.IRIX file.
639
640 Older ConvexOS versions come with a broken recvfrom(2) implementation.
641 This makes it impossible for the daemon wrappers to look up the
642 client host address (and hence, the name) in case of UDP requests.
643 A patch is available for ConvexOS 10.1; later releases should be OK.
644
645 With early Solaris (SunOS 5) versions, the syslog daemon will leave
646 behind zombie processes when writing to logged-in users.  Workaround:
647 increase the syslogd threshold for logging to users, or reduce the
648 wrapper's logging severity.
649
650 On some systems, the optional RFC 931 etc. client username lookups may
651 trigger a kernel bug.  When a client host connects to your system, and
652 the RFC 931 connection from your system to that client is rejected by a
653 router, your kernel may drop all connections with that client.  This is
654 not a bug in the wrapper programs: complain to your vendor, and don't
655 enable client user name lookups until the bug has been fixed.
656
657 Reportedly, SunOS 4.1.1, Next 2.0a, ISC 3.0 with TCP 1.3, and AIX 3.2.2
658 and later are OK.
659
660 Sony News/OS 4.51, HP-UX 8-something and Ultrix 4.3 still have the bug.
661 Reportedly, a fix for Ultrix is available (CXO-8919).
662
663 The following procedure can be used (from outside the tue.nl domain) to
664 find out if your kernel has the bug. From the system under test, do:
665
666         % ftp 131.155.70.19
667
668 This command attempts to make an ftp connection to our anonymous ftp
669 server (ftp.win.tue.nl).  When the connection has been established, run
670 the following command from the same system under test, while keeping
671 the ftp connection open:
672
673         % telnet 131.155.70.19 111
674
675 Do not forget the `111' at the end of the command. This telnet command
676 attempts to connect to our portmap process.  The telnet command should
677 fail with:  "host not reachable", or with a timeout error. If your ftp
678 connection gets messed up, you have the bug. If the telnet command does
679 not fail, please let me know a.s.a.p.!
680
681 For those who care, the bug is that the BSD kernel code was not careful
682 enough with incoming ICMP UNREACHABLE control messages (it ignored the
683 local and remote port numbers, and therefore zapped *all* connections
684 with the remote system). The bug is still present in the BSD NET/1
685 source release (1989) but apparently has been fixed in BSD NET/2 (1991). 
686
687 7 - Configuration and installation
688 ----------------------------------
689
690 7.1 - Easy configuration and installation
691 -----------------------------------------
692
693 The "easy" recipe requires no changes to existing software or
694 configuration files.  Basically, you move the daemons that you want to
695 protect to a different directory and plug the resulting holes with
696 copies of the wrapper programs.
697
698 If you don't run Ultrix, you won't need the miscd wrapper program.  The
699 miscd daemon implements among others the SYSTAT service, which produces
700 the same output as the WHO command.
701
702 Type `make' and follow the instructions.  The Makefile comes with
703 ready-to-use templates for many common UNIX implementations (sun,
704 ultrix, hp-ux, aix, irix,...). 
705
706 IRIX has so many bugs that it has its own README.IRIX file.
707
708 When the `make' succeeds the result is five executables (six in case of
709 Ultrix).
710
711 You can use the `tcpdchk' program to identify the most common problems
712 in your wrapper and inetd configuration files.  
713
714 With the `tcpdmatch' program you can examine how the wrapper would
715 react to specific requests for service.  
716
717 The `safe_finger' command should be used when you implement booby
718 traps:  it gives better protection against nasty stuff that remote
719 hosts may do in response to your finger probes.
720
721 The `try-from' program tests the host and username lookup code.  Run it
722 from a remote shell command (`rsh host /some/where/try-from') and it
723 should be able to figure out from what system it is being called.
724
725 The tcpd program can be used to monitor the telnet, finger, ftp, exec,
726 rsh, rlogin, tftp, talk, comsat and other tcp or udp services that have
727 a one-to-one mapping onto executable files.
728
729 The tcpd program can also be used for services that are marked as
730 rpc/udp in the inetd configuration file, but not for rpc/tcp services
731 such as rexd.  You probably do not want to run rexd anyway. On most
732 systems it is even less secure than a wildcard in /etc/hosts.equiv.
733
734 With System V.4-style systems, the tcpd program can also handle TLI
735 services. When TCP/IP or UDP/IP is used underneath TLI, tcpd provides
736 the same functions as with socket-based applications. When some other
737 protocol is used underneath TLI, functionality will be limited (no
738 client username lookups, weird network address formats).
739
740 Decide which services you want to monitor. Move the corresponding
741 vendor-provided daemon programs to the location specified by the
742 REAL_DAEMON_DIR constant in the Makefile, and fill the holes with
743 copies of the tcpd program. That is, one copy of (or link to) the tcpd
744 program for each service that you want to monitor. For example, to
745 monitor the use of your finger service:
746
747     # mkdir REAL_DAEMON_DIR
748     # mv /usr/etc/in.fingerd REAL_DAEMON_DIR
749     # cp tcpd /usr/etc/in.fingerd
750
751 The example applies to SunOS 4. With other UNIX implementations the
752 network daemons live in /usr/libexec, /usr/sbin or in /etc, or have no
753 "in." prefix to their names, but you get the idea.
754
755 File protections: the wrapper, all files used by the wrapper, and all
756 directories in the path leading to those files, should be accessible
757 but not writable for unprivileged users (mode 755 or mode 555). Do not
758 install the wrapper set-uid.
759
760 Ultrix only:  If you want to monitor the SYSTAT service, move the
761 vendor-provided miscd daemon to the location specified by the
762 REAL_DAEMON_DIR macro in the Makefile, and install the miscd wrapper
763 at the original miscd location.
764
765 In the absence of any access-control tables, the daemon wrappers
766 will just maintain a record of network connections made to your system.
767
768 7.2 - Advanced configuration and installation
769 ---------------------------------------------
770
771 The advanced recipe leaves your daemon executables alone, but involves
772 simple modifications to the inetd configuration file.
773
774 Type `make' and follow the instructions.  The Makefile comes with
775 ready-to-use templates for many common UNIX implementations (sun,
776 ultrix, hp-ux, aix, irix, ...). 
777
778 IRIX users should read the warnings in the README.IRIX file first.
779
780 When the `make' succeeds the result is five executables (six in case of
781 Ultrix).
782
783 You can use the `tcpdchk' program to identify the most common problems
784 in your wrapper and inetd configuration files.  
785
786 With the `tcpdmatch' program you can examine how the wrapper would
787 react to specific requests for service.  
788
789 The `try-from' program tests the host and username lookup code.  Run it
790 from a remote shell command (`rsh host /some/where/try-from') and it
791 should be able to figure out from what system it is being called.
792
793 The `safe_finger' command should be used when you implement a booby
794 trap:  it gives better protection against nasty stuff that remote hosts
795 may do in response to your finger probes.
796
797 The tcpd program can be used to monitor the telnet, finger, ftp, exec,
798 rsh, rlogin, tftp, talk, comsat and other tcp or udp services that have
799 a one-to-one mapping onto executable files.
800
801 With System V.4-style systems, the tcpd program can also handle TLI
802 services. When TCP/IP or UDP/IP is used underneath TLI, tcpd provides
803 the same functions as with socket-based applications. When some other
804 protocol is used underneath TLI, functionality will be limited (no
805 client username lookups, weird network address formats).
806
807 The tcpd program can also be used for services that are marked as
808 rpc/udp in the inetd configuration file, but not for rpc/tcp services
809 such as rexd.  You probably do not want to run rexd anyway. On most
810 systems it is even less secure than a wildcard in /etc/hosts.equiv.
811
812 Install the tcpd command in a suitable place. Apollo UNIX users will
813 want to install it under a different name because the name "tcpd" is
814 already taken; a suitable name would be "frontd".  
815
816 File protections: the wrapper, all files used by the wrapper, and all
817 directories in the path leading to those files, should be accessible
818 but not writable for unprivileged users (mode 755 or mode 555). Do not
819 install the wrapper set-uid.
820
821 Then perform the following edits on the inetd configuration file
822 (usually /etc/inetd.conf or /etc/inet/inetd.conf):
823
824     finger  stream  tcp     nowait  nobody  /usr/etc/in.fingerd     in.fingerd
825                                             ^^^^^^^^^^^^^^^^^^^
826 becomes:
827
828     finger  stream  tcp     nowait  nobody  /usr/etc/tcpd           in.fingerd
829                                             ^^^^^^^^^^^^^
830 Send a `kill -HUP' to the inetd process to make the change effective.
831 Some IRIX inetd implementations require that you first disable the
832 finger service (comment out the finger service and `kill -HUP' the
833 inetd) before you can turn on the modified version. Sending a HUP
834 twice seems to work just as well for IRIX 5.3, 6.0, 6.0.1 and 6.1.
835
836 AIX note: you may have to execute the `inetimp' command after changing
837 the inetd configuration file.
838
839 The example applies to SunOS 4. With other UNIX implementations the
840 network daemons live in /usr/libexec, /usr/sbin, or /etc, the network
841 daemons have no "in." prefix to their names, or the username field in
842 the inetd configuration file may be missing.
843
844 When the finger service works as expected you can perform similar
845 changes for other network services. Do not forget the `kill -HUP'.
846
847 The miscd daemon that comes with Ultrix implements several network
848 services. It decides what to do by looking at its process name. One of
849 the services is systat, which is a kind of limited finger service.  If
850 you want to monitor the systat service, install the miscd wrapper in a
851 suitable place and update the inetd configuration file:
852
853     systat  stream  tcp     nowait  /suitable/place/miscd      systatd
854
855 Ultrix 4.3 allows you to specify a user id under which the daemon will
856 be executed. This feature is not documented in the manual pages.  Thus,
857 the example would become:
858
859     systat  stream  tcp     nowait  nobody /suitable/place/miscd    systatd
860
861 Older Ultrix systems still run all their network daemons as root.
862
863 In the absence of any access-control tables, the daemon wrappers
864 will just maintain a record of network connections made to your system.
865
866 7.3 - Daemons with arbitrary path names
867 ---------------------------------------
868
869 The above tcpd examples work fine with network daemons that live in a
870 common directory, but sometimes that is not practical. Having soft
871 links all over your file system is not a clean solution, either.
872
873 Instead you can specify, in the inetd configuration file, an absolute
874 path name for the daemon process name.  For example,
875
876     ntalk   dgram   udp     wait    root    /usr/etc/tcpd /usr/local/lib/ntalkd
877
878 When the daemon process name is an absolute path name, tcpd ignores the
879 value of the REAL_DAEMON_DIR constant, and uses the last path component
880 of the daemon process name for logging and for access control.
881
882 7.4 - Building and testing the access control rules
883 ---------------------------------------------------
884
885 In order to support access control the wrappers must be compiled with
886 the -DHOSTS_ACCESS option. The access control policy is given in the
887 form of two tables (default: /etc/hosts.allow and /etc/hosts.deny).
888 Access control is disabled when there are no access control tables, or
889 when the tables are empty.
890
891 If you haven't used the wrappers before I recommend that you first run
892 them a couple of days without any access control restrictions. The
893 logfile records should give you an idea of the process names and of the
894 host names that you will have to build into your access control rules.
895
896 The syntax of the access control rules is documented in the file
897 hosts_access.5, which is in `nroff -man' format. This is a lengthy
898 document, and no-one expects you to read it right away from beginning
899 to end.  Instead, after reading the introductory section, skip to the
900 examples at the end so that you get a general idea of the language.
901 Then you can appreciate the detailed reference sections near the
902 beginning of the document.
903
904 The examples in the hosts_access.5 document (`nroff -man' format) show
905 two specific types of access control policy:  1) mostly closed (only
906 permitting access from a limited number of systems) and 2) mostly open
907 (permitting access from everyone except a limited number of trouble
908 makers). You will have to choose what model suits your situation best.
909 Implementing a mixed policy should not be overly difficult either.
910
911 Optional extensions to the access control language are described in the
912 hosts_options.5 document (`nroff -man' format).
913
914 The `tcpdchk' program examines all rules in your access control files
915 and reports any problems it can find. `tcpdchk -v' writes to standard
916 output a pretty-printed list of all rules. `tcpdchk -d' examines the
917 hosts.access and hosts.allow files in the current directory. This
918 program is described in the tcpdchk.8 document (`nroff -man' format).
919
920 The `tcpdmatch' command can be used to try out your local access
921 control files.  The command syntax is:
922
923     tcpdmatch process_name hostname (e.g.: tcpdmatch in.tftpd localhost)
924
925     tcpdmatch process_name address  (e.g.: tcpdmatch in.tftpd 127.0.0.1)
926
927 This way you can simulate what decisions will be made, and what actions
928 will be taken, when hosts connect to your own system. The program is
929 described in the tcpdmatch.8 document (`nroff -man' format).
930
931 Note 1: `tcpdmatch -d' will look for hosts.{allow,deny} tables in the
932 current working directory. This is useful for testing new rules without
933 bothering your users.
934
935 Note 2: you cannot use the `tcpdmatch' command to simulate what happens
936 when the local system connects to other hosts.
937
938 In order to find out what process name to use, just use the service and
939 watch the process name that shows up in the logfile.  Alternatively,
940 you can look up the name from the inetd configuration file. Coming back
941 to the tftp example in the tutorial section above:
942
943     tftp  dgram  udp  wait  root  /usr/etc/tcpd  in.tftpd -s /tftpboot
944
945 This entry causes the inetd to run the wrapper program (tcpd) with a
946 process name `in.tftpd'.  This is the name that the wrapper will use
947 when scanning the access control tables. Therefore, `in.tftpd' is the
948 process name that should be given to the `tcpdmatch' command. On your
949 system the actual inetd.conf entry may differ (tftpd instead of
950 in.tftpd, and no `root' field), but you get the idea.
951
952 When you specify a host name, the `tcpdmatch' program will use both the
953 host name and address. This way you can simulate the most common case
954 where the wrappers know both the host address and the host name.  The
955 `tcpdmatch' program will iterate over all addresses that it can find
956 for the given host name.
957
958 When you specify a host address instead of a host name, the `tcpdmatch'
959 program will pretend that the host name is unknown, so that you can
960 simulate what happens when the wrapper is unable to look up the client
961 host name.
962
963 7.5 - Other applications
964 ------------------------
965
966 The access control routines can easily be integrated with other
967 programs.  The hosts_access.3 manual page (`nroff -man' format)
968 describes the external interface of the libwrap.a library.
969
970 The tcpd program can even be used to control access to the mail
971 service.  This can be useful when you suspect that someone is trying
972 out some obscure sendmail bug, or when a remote site is misconfigured
973 and keeps hammering your mail daemon.
974
975 In that case, sendmail should not be run as a stand-alone network
976 listener, but it should be registered in the inetd configuration file.
977 For example:
978
979     smtp    stream  tcp     nowait  root    /usr/etc/tcpd /usr/lib/sendmail -bs
980
981 You will still need to run one sendmail background process to handle
982 queued-up outgoing mail. A command like:
983
984     /usr/lib/sendmail -q15m
985
986 (no `-bd' flag) should take care of that. You cannot really prevent
987 people from posting forged mail this way, because there are many
988 unprotected smtp daemons on the network.
989
990 8 - Acknowledgements
991 --------------------
992
993 Many people contributed to the evolution of the programs, by asking
994 inspiring questions, by suggesting features or bugfixes, or by
995 submitting source code.  Nevertheless, all mistakes and bugs in the
996 wrappers are my own.
997
998 Thanks to Brendan Kehoe (cs.widener.edu), Heimir Sverrisson (hafro.is)
999 and Dan Bernstein (kramden.acf.nyu.edu) for feedback on an early
1000 release of this product.  The host name/address check was suggested by
1001 John Kimball (src.honeywell.com).  Apollo's UNIX environment has some
1002 peculiar quirks: Willem-Jan Withagen (eb.ele.tue.nl), Pieter
1003 Schoenmakers (es.ele.tue.nl) and Charles S. Fuller (wccs.psc.edu)
1004 provided assistance.  Hal R.  Brand (addvax.llnl.gov) told me how to
1005 get the client IP address in case of datagram-oriented services, and
1006 suggested the optional shell command feature.  Shabbir Safdar
1007 (mentor.cc.purdue.edu) provided a first version of a much-needed manual
1008 page.  Granville Boman Goza, IV (sei.cmu.edu) suggested to use the
1009 client IP address even when the host name is available.  Casper H.S.
1010 Dik (fwi.uva.nl) provided additional insight into DNS spoofing
1011 techniques.  The bogus daemon feature was inspired by code from Andrew
1012 Macpherson (BNR Europe Ltd).  Steve Bellovin (research.att.com)
1013 confirmed some of my suspicions about the darker sides of TCP/IP
1014 insecurity. Risks of automated fingers were pointed out by Borja Marcos
1015 (we.lc.ehu.es). Brad Plecs (jhuspo.ca.jhu.edu) was kind enough to try
1016 my early TLI code and to work out how DG/UX differs from Solaris.
1017
1018 John P.  Rouillard (cs.umb.edu) deserves special mention for his
1019 persistent, but constructive, nagging about wrong or missing things,
1020 and for trying out and discussing embryonic code or ideas.
1021
1022 Last but not least, Howard Chu (hanauma.jpl.nasa.gov), Darren Reed
1023 (coombs.anu.edu.au), Icarus Sparry (gdr.bath.ac.uk), Scott Schwartz
1024 (cs.psu.edu), John A. Kunze (violet.berkeley.edu), Daniel Len Schales
1025 (engr.latech.edu), Chris Turbeville (cse.uta.edu), Paul Kranenburg
1026 (cs.few.eur.nl), Marc Boucher (cam.org), Dave Mitchell
1027 (dcs.shef.ac.uk), Andrew Maffei, Adrian van Bloois, Rop Gonggrijp, John
1028 C. Wingenbach, Everett F. Batey  and many, many others provided fixes,
1029 code fragments, or ideas for improvements.
1030
1031         Wietse Venema (wietse@wzv.win.tue.nl)
1032         Department of Mathematics and Computing Science
1033         Eindhoven University of Technology
1034         P.O. Box 513
1035         5600 MB Eindhoven
1036         The Netherlands
1037
1038         Currently visiting IBM T.J. Watson Research, Hawthorne NY, USA.