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

Intro:
======
Please make sure that you read all parts of this file. Make
sure that you understand the sections of this file relevant to you.

Legal:
======

This code is in the 'public domain' (*) under the GPL/LGPL,
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).
(*) 'public domain' is used here in the sense of the Wassenaar treaty.

The general legal notice valid for all elements of vpnd is:

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

The uppercase legal statement above was copied from
/usr/src/linux/drivers/char/random.c, I'm not a lawyer
and you have to cover yourself against some madness nowadays.

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 or /usr/local/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 or 18 byte message 
containing a data header (4 bytes in case of fast checksum,
18 bytes in case of HMAC-MD5 authentication and 22 bytes in
case of HMAC-SHA1 or HMAC-RIPEMD160 authentication) 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.

There are two master key file formats, the basic format
where the master key is stored in unencrypted form
and the extended format where the master key is stored
in encrypted form. For details see the appropriate
sections below.

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 session key and 
session 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...).

Basic Master Key File Format:
=============================

The master key is stored in unencrypted form in a mode
0400 file owned by root:root. This file is never modified
by vpnd. This key file format is for use for vpnd connections
between unattended firewall systems which do not allow any
remote access and do firewalling and routing only.
This key file format 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. 

Extended Master Key File Format:
================================

The master key is stored in encrypted form in a mode 0400
file owned by root:root. The encryption key is the four
character string 'vpnd'. The encryption mode is CBC
(cipher block chaining). The required IV (initialization
vector) for decryption of the local master key is
stored unencrypted in the remote master key file.
The format of the extended master key file is as follows:

Offset	Contents
----------------------------------------------------------
0       version identifier
1       reserved, 0
2       reserved, 0
3       transaction id
4-75    encrypted master secret for transaction id & 1 = 0
76-147  encrypted master secret for transaction id & 1 = 1
148-155 remote iv for transaction id & 1 = 0
156-163 remote iv for transaction id & 1 = 1
164-187 key identifier
188-255 reserved,0
----------------------------------------------------------

The session initialization mechanism in case the extended master key file
format is used is as follows after connection between client ans server
is established:

read master key file from disk, check version id, disconnect if wrong id
send transaction id and capabilities, client additionally sends identifier
receive transaction id and capabilities, server additionally receives identifier
server checks client identifier, disconnect if mismatch
compare remote and local transaction id:
        if identical continue
        if +-1 difference chose lower value and write syslog notice, continue
        if >+-1 difference disconnect and write syslog notice, disconnect
send remote iv according to selected transaction id
receive local iv
decrypt master key according to selected transaction id
server generates session key and server iv, sends it to client
client generates client iv and sends it to server
server reads client iv
client reads session key and server iv
session key setup as usual
increment selected transaction id by 1, write it to memory
create new local iv
encrypt master key with new local iv, write it to memory, send iv to peer
receive remote iv, write it to memory
xor local and remote ivs, send result to peer
receive xored iv, compare to local xor, disconnect if mismatch
write master key file to disk

All communication before the master key is decrypted is done unencrypted.
All communication for session key and isession iv transfer is done encrypted
with the master key and ivs generated from 'local' and 'remote' parameters.
All communication after session key and session iv transfer is done
encrypted in CFB mode with the session key/ivs.

There are advantages and disadvantages for this file format. The major and
only disadvantage is that both client and server vpnd do modify the key
file for every successfully established session. This is usually not
desired for unattended, failsafe and tripwired firewall systems. In this
case you should use the basic key file format.
There are several advantages:
1. key id: The key id is checked prior to any data transmission by the
   vpnd server. This helps to detect malicious connects even before
   any cryptographic setup is done. Furthermore this key id will
   be used for key management in a later software version.
2. capabilities: The capabilities exchanged between client and server
   enable the run time negotiation of vpnd features. Currently
   the enabling of compression as well as the method of message
   authentication (checksum, HMAC-MD5, HMAC-SHA1, HMAC-RIPEMD160)
   is negotiated.
   Note that even though it may look desirable at a first glance
   key length negotiation will never be implemented. First of all
   negotiation may result in the maximum number of key bits requested
   which may result in a legal problem for one of the two peers
   involved. And if the minimum key bits are selected it may well
   happen that accidentally no encryption at all takes place which
   would be a serious security problem. Finally the plaintext
   transfer of the key length used would make it very easy for
   any man in the middle sniffing the data packets to decide whether
   communication can be cracked (too short key length), or not.
3. stolen keys: First of all the master key can't be used without a
   connection to the server. Note that even as the master key is stored
   encrypted it is not stored encrypted in any legal sense as:
   a) it is encrypted with a fixed four character key which is 'vpnd'
   b) the required iv to decrypt the key is stored unencrypted
   c) the required iv to decrypt the key is transmitted unencrypted
   Still nobody can steal and actively use a master key file undetected:
   a) If a stolen master key file is used once a 'transaction id mismatch'
      syslog notice will be issued on client and server when the
      valid user or intruder connects. Note that this notice is possible, too,
      if the client or the server do crash before the modified master
      key file of a session is physically written back to disk but
      after all we're talking Unix here and even in case a system crashes
      this will not go unnotified, so a system administrator can
      distinguish between a crash and an attack.
   b) If a stolen key is used more than once by the intruder the valid
      user will no longer be able to connect to the server. This will
      for sure be detected.
   c) If a stolen key is used more than once by the valid user before
      the intruder uses the key the intruder will no longer be able to
      connect to the server. Any attempt will for sure be detected.
   The only means to use a stolen key file is to monitor all traffic
   between client and server and to extract the proper iv for the
   key file when the next session between client and server is established.
   The intruder then has the master key. What comes next is valid both
   for basic and extended key file format: Even though the intruder now
   has the master key all traffic between client and server must be monitored
   to extract the session key from the traffic. So any intruder must
   first gain root access to client or server and steal the key file.
   Then all traffic between client and server must be monitored.
   If an intruder has both capabilities the intruder will already
   have the capability to sniff all unencypted network traffic on
   either client or server so any further precautions against such
   passive attacks don't make much sense.

User Password for Extended Master Key File Format
=================================================

First things first: when extended master key files are created there
is no user password. The reason is that the key files are supposed
to be used in unattended mode. However it may be desired to set
a user password, either for transfer of the key to the peer or
if vpnd is started interactively or if e.g. a key server is used.
The basic mechanism for user passwords within vpnd is to create
the required key schedule directly from the given password and
then to clear the password. There is no need to hash the user
password first - as only the two master keys which consist of
random numbers are encrypted and there is no mechanism to verify
any password except than to connect to the peer and see, if
the local decryption actually was done with the right password
plaintext attacks are not possible. Furthermore decryption
attempts will be detected and logged on the peer system so
such an attempt will for sure be detected. The minor drawback
is that you will have to remember the password precisely, especially
when you use the password modifying feature of vpnd. Any combination
of old and new password is accepted but if you enter the wrong
values, you will never again be able to connect to the peer with
this key. I do believe this to be reasonable enough, you just have to
to be careful enough when remembering and entering the password.
Now for the practical side: use 'vpnd -c <pathname-of-keyfile>'
to set, modify or remove a user password for the given keyfile.
If you want to set a password for a key file with no password
just press the 'enter' key when prompted for the old password
and enter the new password when prompted for the new password.
If you want to remove a password for a key file with a password
enter the current password when prompted for the old password and
just press the 'enter' key when prompted for the new password.
If you want to modify a password for a key file with a password
enter the current password when prompted for the old password and
enter the new password when prompted for the new password.
Now that you have set a user password for the master key file
you need to start vpnd with and additional '-p' parameter as
vpnd has no way to detect if a user password has been set or not.
if you start vpnd with the additional '-p' parameter you are
prompted to enter the password except when standard input of vpnd
is a pipe. In this case the password is read from standard input
(this is useful in combination with any kind of key server).
The only way to find out if the password entered is correct is
when the next connection with the peer succeeds (see above).
For a short description of the '-c' and '-p' parameters
use 'vpnd -h'.

New Versions, Updates:
======================

Main site:   http://sunsite.auc.dk/vpnd/
Mirror site: http://www.crosswinds.net/~anstein/unix/vpnd.html

Current development versions may be retrieved through anonymous CVS.
See the URLs stated above for details.
A mailing list for vpnd is available, see the URLs above for details.

Author:
=======

Andreas Steinmetz, http://www.crosswinds.net/~anstein/

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

Andreas Steinmetz, http://www.crosswinds.net/~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.9 tested)
FreeBSD 3.3

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.
For FreeBSD you may need to use the rndcontrol utility to enable
some interrupts for random number generation as your system otherwise
may lack sufficient entrophy to generate a key.

Now generate a basic format master key with the vpnd -m command or
extended format master key files with the -x command (for key generation
vpnd will use only /dev/random as the random data source). In case
of -x you have to specify a directory where two files, vpnd.lcl.key
and vpnd.rmt.key are created. Use vpnd.lcl.key on the local system
and transport vpnd.rmt.key by secure means to the remote system.
Then use vpnd.rmt.key on the remote system. Note that except for
connections between unattended firewall systems the use of the
extended format master key files is strongly encouraged. Make sure
you read the user password section for this file format above.
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.

Some hints:

1.  Use the 'autoroute' option only for Linux 2.2.x kernels.
    This option is ignored for FreeBSD.
2.  If you all of sudden can't connect to the your peer anymore
    (crypto init failures) your system may lack entrophy, try
    to use 'randomdev /dev/urandom' in this case. This should
    be still secure enough (see the random.c source of the
    Linux kernel) and you won't have problems connection
    to your peer anymore.
3.  Make sure the 'keysize' option has the same value on both
    the client and the server system or that the option is
    not given on both systems.
4.  'local' and 'remote' relate to the local and remote ip
    of the slip interface created by vpnd whereas 'client'
    and 'server', if given as an ip, refer to the actual
    system network ips.
5.  For connects from a dynamic ip client to a fixed ip
    server use 0.0.0.0 for the client ip.
6.  You can't test vpnd client and server functionality on
    one system, two systems are required
7.  Have a look at the 'suspend', 'connwait' and 'sendbuf'
    options when you use vpnd on a dialup client system.
8.  See the configuration examples in the samples and the
    dynamic-ip-client directories
9.  If you get slip interface errors make sure that cslip
    is enabled together with slip in the kernel/slip module
    or use the 'nocslip' option
10. If you still have problems or want to report a bug
    preferably use the vpnd mailing list (vpnd@sunsite.auc.dk)
    as I'm not available from time to time and someone on the
    list may be able to help you.

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 painfully transfered encrypted can be easily
sniffed in the plain version. Secure your systems first, then use vpnd!
Use firewalls, passive and active intrusion warning and detection
systems, don't rely on a single layer of security, always assume that
a security layer can be penetrated. Use multiple layers and examine
your system logs carefully and regularly. Don't ignore any unusual
activity, investigate. And never, never log into your system as
root by default, su only when and if it is really necessary.