.. footer:: $Id: tperimeter.txt,v 1.104 2006/05/02 04:22:23 tundra Exp $


=====================================================
``tperimeter`` - A Dynamic TCP Wrapper Control System
=====================================================


OVERVIEW
--------

``tperimeter`` is a system that provides a secure mechanism for remotely
opening access to internet services under TCP Wrapper control.  Consider the
following very typical scenario:

  An internet-facing server is configured with a variety of services that
  observe TCP Wrapper (``/etc/hosts.allow``) access control rules.  It is
  common to use this mechanism to very strictly limit which external IP
  addresses may even attempt connection to these services.  For instance, we
  may choose to limit ``ssh` logins from IPs of hosts known to us. The
  problem with this is that legitimate users whose IP addresses may change
  will not be able to connect.  This is common when a user travels and uses
  internet connections in airports, hotels, or other places where ``dhcp``
  is used for dynamic IP assignment.  In this case, the user has no *a
  priori* knowledge of what his IP address will be and thus cannot have it
  added to ``/etc/hosts.allow`` to enable remote system access.

``tperimeter`` is designed to specifically address this problem.  A
traveling user or a user whose IP address changes regularly simply logs into
a secure web page and informs the system of their current IP address and
which services they'd like to have enabled for them.  ``tperimeter`` then
fulfills the request - typically within 5 minutes or so - and grants access
to the system for that service from that IP address for a small window in
time - again, 5 minutes it typical.  This gives the user time to access the
desired service before TCP Wrappers once again close the system to its
default state.  These semantics thus provide flexible remote access with
an automatic reset to system default access control.


HOW ``tperimeter`` WORKS
------------------------


HOW TO INSTALL ``tperimeter``
-----------------------------


CUSTOMIZING ``tperimeter``
--------------------------


SECURITY RISKS
--------------

Any system that permits remote changes to the security environment of a
server has the inherent risk that it can be compromised.  The key to
minimizing such exposure is careful customization, integration, and testing. 
TundraWare Inc. makes **no** claims that this software will work without
security risks or compromise.  The software is **experimental** and is
provided **AS-IS**.  It is up to you to take the necessary steps to ensure
this system is appropriate for your environment.

There are several areas you should take particular care to audit to ensure
your system security isn't going to get clobbered by ``tperimeter``:

  1) The web page the user accesses to make ``tperimeter`` requests
     should be both encrypted (SSL/hhtps) **and** be password protected.
     You have to make a policy decision whether to offer all authorized
     users the same ``tperimeter`` login name and password or give them
     each their own individual login credentials.  Either way, it's a good
     idea to watch the system log for ``tperimeter`` requests to see
     how often and from where requests are showing up.

  2) If you customize the programs, make sure you've not introduced coding
     errors that might cause it to cobble up your ``/etc/hosts.allow`` file.

  3) Similarly take great care to construct the file tree that describes
     your desired default environment carefully.

  4) Make sure that file and directory permissions are correct.  The
     requestor components (``tperimiter-ui.html`` and ``tperimeter.py``)
     should be owned by the web daemon user (usually ``www``) and have
     permissions of 740 or even 700.  ``rebuild-hosts.allow.sh`` should
     be owned by root, again with permissions of 740 or 700.

  5) It is common for dhcp-served users to exist behind a NATing firewall.
     That is, the dynamic IP address they are assigned is commonly
     non-routable and is NATed via public routable IP.  This means that when
     they request access via ``tperimeter`` they are providing the public IP
     address **that is serving many NATed users**.  In effect, the access
     control "hole" ``tperimeter`` is opening will be available to
     **everyone** behind that NATed IP.  This is why ``tperimeter`` only
     offers a brief window of connection for requested services.  It always
     "snaps back" to the system defaults for access.


OTHER NOTES
-----------

``tperimeter`` requires a fairly current version of the ``python``
programming language.

``tperimeter`` was developed and minimally tested on FreeBSD 4.x.  It should
work without modification (other than the customizations noted above) on
other FreeBSD, Linux, and Apple OS/X systems, but has not been tested at all
in these environments.


COPYRIGHT AND LICENSING
-----------------------


``tperimeter`` is Copyright(c) 2006 TundraWare Inc.  For  terms  of  use,
see the ``tperimeter-license.txt`` file in the program distribution.  If you
install twander on a FreeBSD system using the 'ports' mechanism, you will
also find this file in /usr/local/share/doc/twander.


AUTHOR
------

Tim Daneliuk

tperimeter@tundraware.com