This is the 7.6 version of the TCP/IP daemon wrapper package, release A for
RISC OS (27 Jul 2001)

Introduction
============

tcp_wrappers is a Unix utility that allows access to servers running on the
local machine to be determined in a global way, so that it is possible to
centrally control who (what IP address) is allowed to use what services.  For
example, you may wish anyone on your local LAN to be able to connect to your
telnet server, but no-one else.  tcp_wrappers allows you to specify that
only people within a particular domain or IP address range can have access.

This is a port of the hosts_access part of tcp_wrappers to RISC OS.  On Unix,
the way tcp_wrappers works is it runs as one process (inetd) that sits and
listens to all the ports you might be interested in.  When someone connects
to (say) the telnet port, inetd logs it, checks whether they are allowed to
use the telnet service, then fires up the telnet server in.telnetd.  This
strategy won't work on RISC OS as running a separate process for every
connection would use up lots of memory.  So this port only implements the
checks to see whether a host is allowed access, which can then be included in
server programs (it cannot currently be retrofitted to those without source
code).  Documentation for the Unix version can be found in the Unix
directory, which you are advised to read.

Using
=====

tcp_wrappers is a C library file tcp_wrap.o, which you should link with your
server.  The interface is the same as that provided by the Unix hosts_access
functions, whose manpage is included in the file 'man_funcs'.  The control
files, which on Unix usually live in /etc/hosts.allow and /etc/hosts.deny
should be provided at Choices:Internet.HostsAllow
and Choices:Internet.HostsDeny, their format being documented in man_files
and example files can be found as ExmplAllow and ExmplDeny.  These files are
shared between all applications, a particular application's access
permissions being set by the lines beginning 'appname'.

A simple example of usage can be seen in tcpdtest.c and its binary tcpdtest.

tcpdchk is a utility to check your control files for any errors, while
tcpdmatch will query a particular daemon's entry for a specified hostname/IP,
to test whether that host would gain access.  These are more fully documented
in Unix.README, or their options can be displaying by calling them with the
flag --help.  It is advisable to run tcpdchk on your control files before
using them, and recommending this to users of your servers.


RISC OS specifics
=================

Logging
-------

Unix tcp_wrappers by default uses the system logging functionality.  RISC OS
tcp_wrappers will use Doggysoft's SysLog module for the same purposes if told
to do so, or can log results to the console using printf.  These are
controlled by the global structure tcpd_context:

int tcpd_context.use_syslog     = 0 (use printf) or 1 (use SysLog)
if SysLog is used:
char *tcpd_context.syslog_file  = pointer to the file to log into
int tcpd_context.syslog_error   = priority to log errors at
int tcpd_context.syslog_warning = priority to log warnings at

See tcpdtest.c for an example

Compiling, NetLib/UnixLib
-------------------------

By default, tcp_wrappers is supplied compiled with Acorn's NetLib.  To
compile it with UnixLib requires changing a few instances of NETLIB to
UNIXLIB in $(NETLIB_INCLUDE) and $(NETLIB_LIBS) in the Makefile. It is
compiled with Norcroft v5 - it should work with gcc but this has not been
tried.  OSLib is also required.


Hostname lookups
----------------

tcp_wrappers will by default use the non-multitasking gethostbyname and
getaddrbyname, as provided by the C library.  If compiling with UnixLib, the
UnixLib gethostbyname/getaddrbyname functions are called.  It appears the
gethostbyaddr in NetLib is broken (it won't talk to the DNS, only the local
hosts file), so the Internet_GetHostByAddr SWI is called directly instead,
based on code from UnixLib. 

However, ANT's resolver module (as most people using the Acorn or ANT
internet stacks will have) has put the multitasking gethostbyname SWI
(Resolver_GetHost) on the same SWI number as Internet_GetHostByAddr.  This
means a) there appears to be no multitasking gethostbyaddr and b) ANT's
resolver module has a kludge where it tries to work out from the arguments
whether you intended to call Internet_GetHostByAddr or Resolver_GetHost. 
Stewart Brodie's DNSResolver provides multitasking lookups for both host and
address, but on different SWIs to ANTs.

As it happens, tcp_wrapper anyway provides a mechanism where you can call
your own gethostby(name/addr) functions.  When you have a

struct request_info request;

calling
sock_methods(&request);
is a macro in tcpd.h which will set up tcp_wrappers to use the default
resolving functions sock_hostname() and sock_hostaddr(), which in turn call
the standard non-multitasking gethostby(name/addr) functions.

Alternatively, you can do:

request.hostname = my_hostname;
request.hostaddr = my_hostaddr;

where my_hostname() and my_hostaddr() are alternative functions based on
sock_*, but can call your own resolving functions.  You are strongly advised
for these functions to be identical to sock_hostname() and sock_hostaddr(),
with only the resolving calls changed, as they are security critical.


Why not a module?
-----------------

It might seem logical for this to have gone in a module.  The reasons for and
against this are as follows

For
---
Easier to upgrade all across all apps

Save space (but that's only a few K per app)

Against
-------
The above lookup functions would be harder to implement, as in
particular multitasking lookups would be difficult for the module to do in
supervisor mode.

If the service was compromised, running in supervisor mode is slightly more
dangerous (the fact of only slightly is a defect in RISC OS)

It makes it harder to intercept calls between tcp_wrappers and the servers,
which could be used to easily (say) grant everyone access to the machine.


Caveats
=======

It DOES NOT provide logging of connections (although it does log internal
inconsistencies), so you should do this yourself.

Note it will grant any access if the allow/deny files do not exist, so it is
up to your code to check for them and decide what to do if they don't exist.


Not supported on RISC OS in this release
========================================

rfc931 (identd)
Shell commands
NIS/YP lookups


Contacts
========

The original tcp_wrappers site is
ftp://ftp.porcupine.org/pub/security/index.html


The RISC OS port was performed by Theo Markettos, who can be contacted as
follows:

theo@markettos.org.uk
atm26@cam.ac.uk (until Jun 2002)

Theo Markettos
5 Willow Close
Liphook
Hants
GU30 7HX
UK

The latest version should always be available from
http://www.markettos.org.uk/
