============================================
Virtual Private Network Daemon (vpnd) README
============================================

Legal:
======

This code is in the public domain, see the headers of the
source files for per source details. Use in commercial
environments is explicitely granted as long as all sources
and this README are made directly available (i.e. no
'send mail to foo@bar.com for sources' or suchlike).

Purpose:
========

vpnd is a daemon which connects two networks on network
level either via TCP/IP or a (virtual) leased line attached
to a serial interface. All data transfered between the two 
networks are encrypted using the unpatented free Blowfish 
encryption algorithm (see http://www.counterpane.com/) with 
a key length of up to 576 bits (may be downgraded to a 
minimum of 0 bits to suit any legal restrictions).

vpnd is not intended as a replacement of existing secured
communications software like ssh or tunneling facilities
of the operating system. It is, however, intended as a
means of securing transparent network interconnection
across potentially insecure channels.

Features:
=========

Supports data compression when you have any of libgz.a
or libz.a on your system either in /usr/lib or /usr/local/lib,
as well as /usr/include/zlib.h, the zlib package home page
is located at http://www.cdrom.com/pub/infozip/zlib/,
use version 1.1.3 or later.

For Linux 1.x systems a simple random number generating
daemon is provided for systems which do not have any
other random number daemon running.

Details:
========

vpnd creates a SLIP interface on the local system and adds
up to nine static routes to hosts and/or networks to the
interface. It connects to its remote peer either over TCP/IP
or a serial line. 

It transfers data blocks encrypted with Blowfish in CFB mode
and uses a 256 byte whitening ring buffer to make brute
force plaintext/ciphertext attacks more difficult.

A message is encrypted such that 64 bit CFB is used for
all complete 64 bit blocks of the message and 8 bit CFB
is used for the remaining bits of the message.

All bytes of the message are whitened by a 256 byte
whitening ring buffer after encryption. The contents of this
ring buffer is derived from the master key.

All data blocks transfered consists of a 4 byte message 
containing a data header and another message containing
the data.

To make things a bit harder for the potential analyst
the header datablock contains the low byte of the data
checksum as the first byte. This value will frequently
change and as it affects the encryption of the further
bytes of the header this offers in conjunction with
whitening some protection against attacks.

The master key is used only to to set up the whitening
ring buffer and then to secure the transfer of a random
key and random initialization vectors which actually
are then used for the session.

The master key is stored in unencrypted form in a mode
0400 file owned by root:root. This can be seen as a serious
security problem but let me tell you: if your system already
got compromised as far as root access the attacker doesn't
need the master key file but is already able to sniff
the paintext network traffic. vpnd is designed to be started
without manual input from the system startup scripts on
secure systems, it is not a replacement for ssh!

Session keys are only generated by the server. The client
just generates its own initialization vector and sends
it to the server. All random data used for key and 
initialization vectors is encrypted first in ECB mode
with the current key before usage to harden any weakness
that may be incorporated in the sytem's random number
generator.

vpnd uses rather hard means of synchronization: If any
error is detected the session is terminated and creation
of a new session is tried. This should be no problem
for communicaion over TCP/IP where the underlying
protocol takes care of securing the session. The same goes
for virtual leased lines over ISDN or real leased lines
as there are very low bit error rates. In case the
session is dropped vpnd usually builds the next session
fast enough for the transfered encrypted IP traffic
to resynchronize and continue.

Logging is performend by using the syslog with
facility daemon and priorities info and notice.

If you see any weakness in the protocol described above
except for root compromise please inform me (astmail@yahoo.com)
immediately. I will try to make this daemon as secure
as reasonable (best security is no data at all...).

Author:
=======

Andreas Steinmetz, http://www2.crosswinds.net/nuremberg/~anstein/

Copyright:
==========

Andreas Steinmetz, http://www2.crosswinds.net/nuremberg/~anstein/
D.O.M. Datenverarbeitung GmbH, http://www.domdv.de/

Contact:
========

Please send any bug reports, enhancements or ports to astmail@yahoo.com

Operating Systems:
==================

Linux 1.2.x (1.2.9 tested)
Linux 2.0.x (2.0.35 tested)
Linux 2.2.x (2.2.1 tested)

Porting:
========

If you want to port vpnd to any other Unix system feel free to do so.
Please contact me (astmail@yahoo.com) so that the sources can be
merged. If you want to port to a non-Unix system still feel free to
do so but be warned: I will merge sources in this case only if you
can convince me that the system you port to can be secured sufficiently
against attacks which is, in my opinion, not the case for all M$
operating systems.

Build:
======

Do a ./configure, then do a make. The resulting file will be named vpnd.
If you use a Linux 1.x system an additional file named randomd will be created.

Install:
========

Copy vpnd (and randomd if it is required) to any directory you like.
Copy vpnd.conf and vpnd.chat to /etc or copy those files to any other 
directory when you use the -f option of vpnd (see later). Note that
vpnd.conf and vpnd.chat must be at least mode 644 and be owned by
root:root.

Configuration:
==============

For Linux 1.x systems without any other random number
generator you must start randomd before vpnd can be used. In this
case you must create a soft link from /dev/random to /dev/randomd.
For Linux 2.x systems make sure that /dev/random (character device,
major 1, minor 8) exists.

Now generate a master key with the vpnd -m command (in this case
vpnd will use only /dev/random as the random data source).
Configure vpnd.conf and vpnd.chat to suit your requirements, see
the documentation included in these files as well as the examples
provided in the samples directory.

Note: do never use the key provided in the samples directory except
maybe for an initial test. Otherwise anyone can decrypt all the
data transfered by your vpnd.

Use:
====

Execute vpnd -h for a list of available options. You should first try
the TCP/IP communication version of vpnd to learn how to configure
vpnd properly. When you use vpnd with a (virtual) leased line
attached to a serial interface the -t option allows you to test
the modem initialization chat script.

A final word:
=============

When you rely only on vpnd to secure your communications - just better
don't use vpnd at all. If one of the two systems involved in the vpnd
communication gets compromised the whole bridged LAN may be compromised
and at least all traffic painlessly transfered encrypted can be easily
sniffed in the plain version. Secure your systems first, then use vpnd!
