<!--
 $Id: ftp-proxy.sgml,v 1.3 1999/10/04 11:51:54 wiegand Exp $

 FTP-Proxy Documentation (SGML source for use with LinuxDoc DTD)

 Author(s): Jens-Gero Boehm <jens-gero.boehm@suse.de>
            Pieter Hollants <pieter.hollants@suse.de>
            Marius Tomaschewski <mt@suse.de>
            Volker Wiegand <volker.wiegand@suse.de>

 This file is part of the SuSE Proxy Suite
            See http://proxy-suite.suse.de/

 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version
 2 of the License, or (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the

  Free Software Foundation, Inc.
  59 Temple Place - Suite 330,
  Boston, MA 02111-1307, USA.

 A history log can be found at the end of this file.
-->

<!DOCTYPE linuxdoc system>

<article>

<!-- Title information -->

<title>
The FTP-Proxy White Paper
</title>

<author>
The SuSE Proxy-Suite Core Development Team
</author>

<date>
$Revision: 1.3 $ ($Date: 1999/10/04 11:51:54 $)
</date>

<abstract>
FTP-Proxy is SuSE Proxy-Suite's application-level proxy for FTP
connections.  It provides support for both active and passive transfers
and for user-specific configuration directives.  Configuration data
can be obtained either from a local configuration file or from an
LDAP directory.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin of document -->

<!-- ##################################################### -->
<!-- Introduction -->
<sect>Introduction
<label id="introduction">

<p>
*** Note: this document is work in progress and by no means
complete.  It is included just for the sake of "Release early
and often." ***

<p>
FTP-Proxy is a transparent, application-level proxy server for FTP
connections, designed to protect FTP servers against attacks based
on the FTP protocol.

Due to the dual TCP connection nature of the FTP protocol, special
handling is required to allow secure transfers.  Data connections are
usually opened by the FTP server (the FTP protocol specification calls
this "active" transfers) or optionally by the FTP client ("passive"
transfers).  The data ports to be used are determined dynamically and
announced as part of the protocol.  This makes it very difficult for
static packet filters to handle FTP correctly.

Most routers and firewalls know about this procedure when NAT is
performed.  E.g. Linux provides a special kernel module for FTP (and
other protocols).  However such code usually only works in "outbound"
direction, allowing FTP access from the inner network to FTP servers
on the outer network, but not in the other direction.

This is a design restriction: TCP/IP packets originating from the
inner network can be marked with special information that allows
for correct routing of response packets from the outer network.
For instance, if a WWW client on host 192.168.168.27 on your internal
network requests a web page from Web server 194.112.123.200, the
router maintains internal information when it rewrites the headers
of the request packets.  If a response packet arrives (with a "From"
address of 194.112.123.200), the router is then able to replace the
public IP address in the "To" field with the private IP address of
the appropriate client, in this case 192.168.168.27.

Of course, if a connection originates from the outer network, the
router does not have this additional information and it can't forward
incoming IP packets since it has no idea which host on the inner
network is to be addressed.  One solution could be to enable port
forwarding on the router (if supported), so that FTP clients on the
outer network could connect to port X on the router to reach server Y
on the inner network, however this fails because of the restrictions
in the FTP protocol outlined above.

A proxy server is an elegant way to circumvent these restrictions,
but there are other benefits of using FTP-Proxy as well:

<p>
<itemize>

<item>
Simple forwarding of all traffic destined for the inner FTP server
renders that server nearly as vulnerable as if it had a "direct"
connection to the outer network (without the firewall in front of it).
In that case the FTP server would still be open to Denial-of-Service
and similar attacks on the IP level.

As FTP-Proxy runs on the application level, it doesn't forward
the original IP packets but maintains the information within.
For instance, a packet containing not only a valid FTP command but
also information to exploit an FTP server's bugs will never reach
the server because only the FTP command itself is forwarded, within
a completely new IP packet.

Of course, FTP-Proxy could be subject to an attack itself.  However,
FTP-Proxy is much less complex than any current FTP server, has been
designed with great care and performs chroot(), setuid() and setgid()
to avoid such vulnerability.

<p>
<item>
Using a circuit-level proxy server like SOCKS requires that all FTP
clients support SOCKS.  A requirement which, although fulfilled by
many modern clients, should not be relied upon.  FTP-Proxy, on the
other hand, is completely transparent to FTP clients because it it
is fully RFC 959 compliant.

<p>
<item>
Using a proxy server such as FTP-Proxy offers increased flexibility:
if you had different FTP servers for different customers, you could
still provide them with a single IP address to connect to, since
FTP-Proxy is able to select the destination FTP server based on who's
actually connecting.

Such user-specific configuration can be defined either in the local
configuration file or using an LDAP server which allows for increased
flexibility, especially if the number of customers grows.

</itemize>

<!-- ##################################################### -->
<!-- Installation and Configuration -->

<sect>Installation and Configuration
<label id="installation">

<p>
The following discussion assumes that you have obtained the
tarball distribution and want to compile and install the FTP-Proxy
package from ground up.  Let's assume you have received a file named
<tt>proxy-suite-x.y.tar.gz</tt>, where 'x' is the major and 'y'
is the minor version number.

<enum>

<item>
Decide where to install and compile the source code.  Say you want
to install it in <tt>/usr/src/proxy-suite-x.y</tt>.  Then do the
following to unpack the source:

<verb>
cd /usr/src
gunzip -c proxy-suite-x.y.tar.gz | tar xvf -
</verb>

If you do not have a copy of GZIP, look at the
<htmlurl url="ftp://ftp.gnu.org/pub/gnu/gzip/" name="GNU">
archive or one of its numerous mirrors.  It's free.

<p>
<item>
Once you have unpacked the source, you will want to run the
<tt>configure</tt> shell script which performs the customization
for you operating system and local environment.  This script is
based upon the GNU AutoConf package.  Change your current directory
to be the root of the Proxy-Suite:

<verb>
cd proxy-suite-x.y
</verb>

The <tt>configure</tt> script understands a number of options
which control the customization process.  To see a complete list
of all options simply run:

<verb>
./configure --help
</verb>

The following options are most likely to be involved:

<verb>
--prefix=&lt;directory&gt;
</verb>
<quote>
This is the root directory for the installation.  If none of the
other directory related directives further down is also given,
all files will be installed in subdirectories under this one.
The default is <tt>/usr/local/proxy-suite/</tt>.
</quote>

<verb>
--exec-prefix=&lt;directory&gt;
</verb>
<quote>
A second top level installation directory, this one is used as
the basis for all executables.  Defaults to the same as PREFIX.
</quote>

<verb>
--mandir=&lt;directory&gt;
</verb>
<quote>
The FTP-Proxy comes with two manual pages:
<em>ftp-proxy(8)</em> for the program
and <em>ftp-proxy.conf(5)</em> for the configuration file format.
These will be installed under the <tt>man5</tt> and <tt>man8</tt>
subdirectories of the given one, or under <tt>PREFIX/man</tt> if
not specified.
</quote>

<verb>
--sbindir=&lt;directory&gt;
</verb>
<quote>
The next directory specifies the location where the
<tt>ftp-proxy</tt> executable itself will be installed.  The
default is <tt>EXEC-PREFIX/sbin</tt> if this option does not
request otherwise.
</quote>

<verb>
--sysconfdir=&lt;directory&gt;
</verb>
<quote>
The last directory related option (others may be given, but
have no effect) deals with the <tt>ftp-proxy.conf</tt>
configuration file.  Again there is a default if the option is
not provided, <tt>PREFIX/etc</tt>.
Please note that the location of the config file can be selected
at run time with the <em>-f</em> flag, but if the file is
installed at the default location, this flag is redundant.
</quote>

<verb>
--enable-debug
</verb>
<quote>
This option allows the generation of debugging output and
is mainly included for evaluation (and development) purposes.
It is recommended not to specify this option for deployment
of the FTP-Proxy into production environments.
</quote>

<verb>
--enable-warnings
</verb>
<quote>
If compiling with the GNU GCC compiler, this flag increases
the warning level.  This is useful to detect programming
errors or incompatibilities with the target platform.  Our
recommendation is to enable it anyway.
</quote>

<verb>
--enable-proc-mods
</verb>
<quote>
This is a special option for the Linux operating system.  It
enables the compilation and use of a special module that will
be installed into the Linux kernel and installs a
<tt>/proc/net/ftp_proxy</tt> file where FTP-Proxy will write
status to.  Other applications can read this file and see
a snapshot of current FTP-Proxy activities and statistics.
</quote>

<verb>
--enable-so-linger
</verb>
<quote>
It is strongly recommended to enable this option for all systems.
Only if the target does have problems with <em>SO_LINGER</em>
handling, it should be disabled.
</quote>

<verb>
--enable-rfc1579
</verb>
<quote>
RFC 1579 is the "Firewall Friendly FTP" proposal.  A new command
<em>APSV</em> (All Passive Mode) is introduced, which permanently
switches the server into passive mode.  Clients do not have to
specify <em>PORT</em> or <em>PASV</em> commands any more, and a
new response code for transfer commands is defined: <em>151</em>.
This code carries the port assignment which would normally be
announcd with the <em>227</em> response code.
</quote>

<verb>
--enable-rfc2428
</verb>
<quote>
RFC 2428 deals with <em>IPv6</em> protocol elements and defines
two new commands, <em>EPRT</em> and <em>EPSV</em>, which stand for
"Extended Port" and "Extended Passive" and define the IP address
and port formats to be used in an IPv6 environment.
</quote>

<verb>
--with-regex[=PATH]
</verb>
<quote>
This option is mainly needed to provide the location of the
POSIX 1002.3 regular expression library if it is not included
in the standard C library.  Regular expressions are used to
scan the arguments of the various FTP commands received from
clients.  If your system does not include the required support,
you can download the latest version from the
<htmlurl url="ftp://ftp.gnu.org/pub/gnu/regex/" name="GNU">
archive.  Again, it's free.  GNU RegEx is known to work with
FTP-Proxy.  If the option is not given, regular expression
support is not installed at all and arguments will not be
investigated any further.
</quote>

<verb>
--with-libwrap[=PATH]
</verb>
<quote>
If running as a standalone background daemon, FTP-Proxy can be
instructed to make use of the <em>TCP Wrapper</em> library.
If this is compiled in and enabled in the configuration file,
the <tt>/etc/hosts.allow</tt> and <tt>/etc/hosts.deny</tt>
files will be consulted to decide if a client will be served.
</quote>

<verb>
--with-libldap[=PATH]
</verb>
<quote>
If you want to supply the user specific configuration values
(not the basic ones) via an LDAP directory, compile in LDAP
support.  The <tt>configure</tt> script can determine without
further manual intervention whether to use the <em>University
of Michigan</em> or the <em>Netscape</em> version of the API.
</quote>

<item>
After <tt>configure</tt> has completed successfully, it is now
time to run <tt>make</tt>.  It will read the <tt>Makefile</tt>
generated by <tt>configure</tt> in the previous step and perform
the compilation process.  The program should not display any
warnings or errors.

<p>
<item>
When the executables have been generated, a final call to
<tt>make install</tt> will copy the FTP-Proxy files into their
appropriate places.  Usually root privileges are required in
order to install the files in their proper places.

<p>
<item>
Currently, you'll have to modify your system manually so that
ftp-proxy is run at system bootup or from inetd (depending on
which mode you choose in the configuration file or command line).

<p>
<item>
The last step is the configuration of the installed FTP-Proxy.
For a list of the valid configuration options consult the
<em>ftp-proxy.conf(5)</em> manual page and the sample
configuration file <em>ftp-proxy.conf.sample</em> file which
comes with the distribution.

</enum>

<!-- ##################################################### -->
<!-- Local System Security -->

<sect>Local System Security
<label id="security">

<p>
FTP-Proxy comes with several configuration features that help
to increase local system security, namely <tt>ServerRoot</tt>,
<tt>User</tt> and <tt>Group</tt>.

<p>
The way FTP-Proxy is being called needs to be considered.  One
possible way is via the system's inetd (or xinetd) Internet Super
Daemon.  In this case FTP-Proxy will not fork or become a daemon.
It will serve the client and terminate itself after delivery.
When configuring (x)inetd to include the ftp-proxy executable,
<tt>ServerRoot</tt> should be used.  The <tt>User</tt> and
<tt>Group</tt> need not be given since they are normally handled
by the inetd configuration itself.

<p>
The latter two options should actually be considered for standalone
operations.  In this case ftp-proxy will detach itself from the
controlling terminal and run as daemon.  The <tt>User</tt> and
<tt>Group</tt> directives will be acted upon by the daemon process,
while <tt>ServerRoot</tt> will only be evaluated by the client
processes after they have forked.

<p>
It might be a good idea to create a new user (e.g. "ftpproxy") in
order to reach a better granularity for the user administration.

<p>
When using <tt>ServerRoot</tt>, please note that in certain cases
other files may have to be installed into the runtime environment
as well, e.g. libc.a and possibly other libraries (e.g. libcrypt.a
under AIX 4.3) and possibly /etc/passwd and /etc/group files.

<!-- ##################################################### -->
<!-- Logging -->

<sect>Logging and Auditing
<label id="logging">

<p>
All possible log messages with their exact wording have been
collected and listed in the file <em>SYSLOG</em> which is part
of the FTP-Proxy distribution.  You can find it in the
<em>ftp-proxy</em> subdirectory.

<p>
The FTP-Proxy logs can be sent to a file, to a pipe, or to the
<em>syslogd(8)</em> daemon for further evaluation and handling.
It is strongly recommended to use syslog because it is the only
way to send logging messages to another machine as they are
generated.

<p>
This off shore logging is especially important for FTP-Proxy
servers located in exposed areas, like the Demilitarized Zone
of a firewall.  Anything that is stored on the computer itself
can easily be manipulated in the case of a hostile takeover.
And when the auditor stops by on his weekly audit tour, all
traces have long since been wiped out.
In order to implement remote logging the <em>syslog.conf(5)</em>
file has to include an entry for the selected facility using a
target starting with the letter '@' followed by the DNS name
or IP address of the external log host.  Usually this loghost
will not be part of the DMZ, but be located on the intranet.
The UDP syslog traffic is then allowed to pass through the
internal firewall router.  Note that the syslogd on the log
host usually has to be started with the "<em>-r</em>" option
to enable the reception of logging information from another
machine.

<p>
The FTP-Proxy syslog messages have been created in a way that
should ease the task of scanning and evaluating.  Each message
contains a tag that can easily be recognized.  It consists
of a prefix that is either <em>TECH</em> or <em>USER</em>,
followed by a hyphen and one of <em>INF</em>, <em>WRN</em>,
<em>ERR</em>, or <em>FTL</em>.

<p>
The possible combinations can be interpreted as follows:

<verb>
TECH-INF
</verb>
<quote>
Messages with this tag carry some technical information with
no need to react to them.  They might display the contents of
the configuration file or the start or stop of the program.
These messages are generated with the <em>INFO</em> syslog
severity.
</quote>

<verb>
TECH-WRN
</verb>
<quote>
Messages with this tag display some mild technical problem
or inconsistency.  E.g. a configuration variable with no
value given or a temporary resource shortage would be sent
in this context.  Also if an FTP server closed a connection
without being instructed by the client or proxy would generate
this kind of message.  These messages are generated with the
<em>WARNING</em> syslog severity.
</quote>

<verb>
TECH-ERR
</verb>
<quote>
Messages with this tag usually mean a severe error condition
that will lead to the termination of the emitting process.
Problems that fall under this category include the inability
to open the configuration file, internal security handling,
network problems like ports already in use by other processes,
input/output errors or other communication faults.  It is
strongly advised that all such messages shall be investigated
and further action is taken.  These messages are generated with
the <em>ERROR</em> syslog severity.
</quote>

<verb>
TECH-FTL
</verb>
<quote>
Messages with this tag should be very rare.  They are reserved
for really weird situations which reveal bugs in the internal
FTP-Proxy programming.  Please report any such occurrance to
the Proxy-Suite development team, it requires the programmer's
attention.  These messages are generated with the <em>CRIT</em>
syslog severity.
</quote>

<verb>
USER-INF
</verb>
<quote>
Messages with this tag will be the majority of all messages.
They are generated for all regular user actions like logging
in, sending commands and transfer statistics.  Their main
purpose is to provide a complete audit trail for every user
interaction.  These messages are generated with the <em>INFO</em>
syslog severity.
</quote>

<verb>
USER-WRN
</verb>
<quote>
Messages with this tag indicate some sort of unforeseen user
action, but need not be taken too seriously.  Only if there is
a pattern of regular or frequent messages of this kind, you
might want to look a bit closer.  These messages are generated
with the <em>WARNING</em> syslog severity.
</quote>

<verb>
USER-ERR
</verb>
<quote>
Messages with this tag mean that the user has been rejected.
Currently no other message has been defined with this tag,
although this might be changed in the future. These messages
are generated with the <em>ERROR</em> syslog severity.
</quote>

<verb>
USER-FTL
</verb>
<quote>
Messages with this tag are currently not being used.
</quote>

<!-- ##################################################### -->
<!-- Inbound and Outbound FTP Traffic -->

<sect>Inbound and Outbound FTP Traffic
<label id="traffic">

<p>
The most common use of FTP-Proxy will probably be "inbound" FTP
traffic.  This means that clients from an "outside" world seek
access to a "local" FTP server.  Nevertheless, FTP-Proxy supports
also an "outbound" mode, where clients have more control over the
FTP connections.

<p>
The concept of "outbound" traffic is based on the increased level
of trust that users enjoy.  When setting the <tt>AllowMagicUser</tt>
config option to "yes" and allowing the "@" and ":" characters as
part of the USER command argument, users can determine the
destination server's address and port with the USER command.  All
they have to do is to append the host name, separated by the "@" sign,
optionally followed by a colon and the port.  These compartments will
be removed from the name and evaluated as destination.

<!-- ##################################################### -->
<!-- Using an LDAP Directory -->

<sect>Using an LDAP Directory
<label id="ldap">

<p>
In order to gain more flexibiliy for the user management, the
user dependent parts of the configuration can also be supplied
with an LDAP directory.

<p>
*** to be supplied ***

<!-- ##################################################### -->
<!-- Command Restriction -->

<sect>Command Restriction
<label id="commandrestriction">

<p>
*** to be supplied ***

<!-- ##################################################### -->
<!-- Copyright and License -->

<sect>Copyright and License
<label id="copyright">

<p>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the

<quote>
Free Software Foundation, Inc.
59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
</quote>

<!-- ##################################################### -->
<!-- Authors -->

<sect>Authors
<label id="authors">

<p>
FTP-Proxy is part of the SuSE Proxy-Suite project and was
written by

<p>
Volker Wiegand (programming,
    <htmlurl url="mailto:Volker.Wiegand@suse.de"
    name="Volker.Wiegand@suse.de">),
<p>
Jens-Gero Boehm (project management,
    <htmlurl url="mailto:Jens-Gero.Boehm@suse.de"
    name="Jens-Gero.Boehm@suse.de">),
<p>
Pieter Hollants (documentation,
    <htmlurl url="mailto:Pieter.Hollants@suse.de"
    name="Pieter.Hollants@suse.de">), and
<p>
Marius Tomaschewski (test environment,
    <htmlurl url="mailto:mt@suse.de"
    name="mt@suse.de">).

<p>
A Mailing List has been installed for the discussion of SuSE
Proxy-Suite.  To subscribe, send an E-Mail with the subject
"<tt>subscribe proxy-suite</tt>" to
<htmlurl url="mailto:majordomo@suse.com" name="SuSE MajorDomo">.

<p>
Please visit the SuSE Proxy-Suite Homepage at
<htmlurl url="http://proxy-suite.suse.de/"
    name="http://proxy-suite.suse.de/">.

</article>

<!--
############################################################
# $Log: ftp-proxy.sgml,v $
# Revision 1.3  1999/10/04 11:51:54  wiegand
# still work in progress
#
# Revision 1.2  1999/09/24 17:53:16  wiegand
# documentation snapshot, "work in progress"
#
# Revision 1.1  1999/09/21 08:07:45  wiegand
# initial checkin
#
############################################################
-->

