
ENskip USER'S GUIDE
===================

>> Please refer to userguide.ps for an enhanced version of this document, <<
>> including performance measurements and implementation details.         <<

Contents
========

1. Installing ENskip
   1.1 Linux
   1.2 Solaris
2. Configuring ENskip
   2.1 Creating certificates
   2.1.1 cert_gen
   2.1.2 cert_make
   2.2 Changing the startup script
   2.2.1 Linux
   2.2.2 Solaris
   2.2.3 Both systems
   2.3 Configuring the daemon
   2.3.1 Configuration examples
   2.3.2 ENskip and Sun SKIP for Solaris
   2.3.3 Certificate Discovery Protocol (CDP)
   2.3.4 Manual keying, VPNet products
   2.3.2 Configuration file syntax
3. How to test ENskip
   3.1 tcpdump
4. Troubleshooting
5. Latest versions
6. Trademarks

SEE "BUGS" for last minute bugs! 

1. Installing ENskip
====================

First, ensure your system clock is set correctly and the system knows its time
zone (this is important because ENskip depends on GMT time for certain
calculations).

1.1 Linux
---------

This version of ENskip for Linux depends on a kernel patch. Please carefully 
read this entire document to check whether you have everything that's needed. 
Of course, you need root permissions to install the software.

  1. Get and install Linux 2.0.26, 2.0.27 or 2.0.28 and a current set of tools 
     and C libraries.
  2. Install GNU g++ and the GNU g++ library (used by Sun's X.509 certificate
     library).
  3. Change to your favorite src directory and unpack the ENskip source
     package ("enskip path").
  4. Change to /usr/src and patch -p0 < "enskip path"/linux/ENskip-linux.diff
  5. Change to /usr/src/linux/ and make clean
  6. make menuconfig
     The following options are REQUIRED:
     * Code maturity level options:
       + Prompt for development drivers
     * Loadable module support
       + Enable loadable module support
     * Networking options:
       + IP: forwarding/gatewaying
       + Network firewalls
       + IP: firewalling
       + IP: always defragment
       + Optimize as router not host [important!]
       - NO masquerading
  7. Save the kernel configuration and
     make dep; make zImage; make modules; make modules_install
     [ignore the three warnings in ip_fw.c]
     cp arch/i386/boot/zImage /vmlinuz
     lilo
  8. reboot
  9. Change to "enskip path". Then,
       make
     Ignore the compiler warnings.
 10. make install
              creates /dev/enskip
              copies enskip.o to /lib/modules/misc
              copies skipd, cert_gen, skip_attach, skip_detach, skip_dump 
                and skip_stat to /usr/local/sbin
              creates /etc/cert/, secret/, public/, cache/


1.2 Solaris
-----------

=============
W A R N I N G 
=============
Please DON'T try to install an ENskip version that was compiled on
another release of your operating system, IT MAY CRASH YOUR KERNEL AND
YOUR HARD DISK!

Before beginning to install the software, please carefully read this entire 
document to check whether you have everything that's needed. Of course, you 
need root permissions to install the software.

  1. Install GNU g++ and the GNU g++ library (used by Sun's X.509 certificate
     library).
  2. Change to your favorite src directory and unpack the ENskip source
     package ("enskip path").
  3. Change to "enskip path". Then,
       make
     Ignore the compiler warnings.
  4. make install
  5. Don't reboot yet, first configure ENskip (see below).


2. Configuring ENskip
=====================

2.1 Creating certificates
-------------------------

Please read the SKIP draft (draft/*.txt) for more information about name 
spaces and name space identifiers (NSIDs).

It is assumed that you will work with NSID 08 certificates, i.e. unsigned
Diffie-Hellman (UDH) certificates.

To generate UDH certificates which interoperate with other SKIP
implementations, use the cert_gen utility. Certificates are stored 
in the CERT directory, normally /etc/cert (defined in config.h).

2.1.1 cert_gen
--------------

cert_gen is designed to automate the certification generation.

After starting cert_gen, you will first have to enter the modulus size 
(i.e. the length of the certificate). Because of export restrictions which 
prevent interoperation with certain export crippled SKIP implementations if 
the modulus length is too large, I recommend generating two certificates, 
one with a 512-bit length modulus and one with 2048. Use the 512-bit
certificate for interoperability with export crippled software only!

Under Solaris, you will also be asked for a secret value (the Linux 
implementation uses the Linux random number generator).

The certificates are automatically saved in your CERT directory. Please
note the certificate names, you will need them when configuring the daemon.

Example session:

# cert_gen
Please enter the modulus size (512, 1024 or 2048): 2048
Generating random value...
If the program suspends here, please switch tasks and generate
some keyboard input.
Random generation succeeded.
Public CERT saved as /etc/cert/public/08-67193A592E4026EC8F1AE7882E7CA258-1
Secret CERT saved as /etc/cert/secret/08-67193A592E4026EC8F1AE7882E7CA258-1
#
Now write down "08-67193A592E4026EC8F1AE7882E7CA258", this is the value you
will need for skipd.conf (leave out the serial number appendix "-1").

2.1.2 cert_make
---------------

If you want to use your own parameters, create a file in the same format as 
the secret file made by cert_gen and feed it to cert/cert_make. cert_make will
return the corresponding public file.


2.2 Changing the startup script
-------------------------------

2.2.1 Linux
-----------

On system startup, you must
  insmod /lib/modules/misc/enskip.o
and start
  /usr/local/sbin/skipd -d [-v]

ENskip automatically attaches to all INET interfaces except loopback.
To add or remove interfaces from ENskip, use "skip_attach IPaddr" or
"skip_detach IPaddr", e.g.
  skip_attach 127.0.0.1
to attach to the loopback interface.

2.2.2 Solaris
-------------

'make install' installs ENskip in the standard startup procedure of
the system. This can cause small holes in the coverage of packet
transmission during the system startup. Modify the startup process
manually to get rid of this problem.

To get rid of ENskip under Solaris, use 'make uninstall'.

2.2.3 Both systems
------------------

I advise you to add a cron job which restarts the daemon every five
minutes (no harm if it is already running). Since the module has a cache
of its own (the primary cache), it is likely that you will not notice
a dead daemon for some time.  In addition, you should kill and reload both
module and daemon at least daily (because of possible memory leaks in
the module and missing garbage collection in the daemon).

WARNING: Both module and daemon must be located on a local drive, not on
an NFS server -- after insertion of the module and before startup of the 
daemon, no network communication is possible. If the daemon is located on 
an NFS drive, you won't be able to load it.


2.3 Configuring the daemon
--------------------------

The daemon configuration file is /etc/skipd.conf. The default configuration 
does not enforce authentication, nor encryption. Be careful not to exclude 
access to your NFS server...

The daemon re-reads its configuration file whenever you send a SIGHUP
(killall -HUP skipd).


2.3.1 Configuration examples
----------------------------

For working examples (including those used for SWAN testing), please
see samples/skipd.conf.


2.3.2 ENskip and Sun SKIP for Solaris
-------------------------------------

Suppose you want to exchange authenticated, unencrypted IP packets with
a remote host running ENskip or Sun SKIP for Solaris.

First get the UDH key ID of both hosts (see above). You don't need to
copy any files, the name (which is the key ID) is enough. For our host, we 
will use the certificate created in the sample session above. Acquire the 
certificate name of the remote host (e.g. by telephone conversation, 
authenticated e-Mail, etc.).

Example: The key ID of our host is 08-67193A592E4026EC8F1AE7882E7CA258,
the key ID of the remote host is 08-94B11E5374827381AF8611CC62FCEE64.
The IP address of our host is 193.99.253.34, the IP address of the remote
host is 193.99.253.62.

In skipd.conf, add two sections after the "default" section.

Outgoing traffic:

  08-67193A592E4026EC8F1AE7882E7CA258, 08-94B11E5374827381AF8611CC62FCEE64:
        src ip = 193.99.253.34
        dst ip = 193.99.253.62
        input filter before = IP
        input deskip policy = AUTH
	Kij algorithm = 3DES-3
	MAC algorithm = MD5
        Crypt algorithm = NONE
        output filter after = IP
        output enskip mode = ALL
        flags = NONE

and incoming traffic:

  08-94B11E5374827381AF8611CC62FCEE64, 08-67193A592E4026EC8F1AE7882E7CA258:
        src ip = 193.99.253.62
        dst ip = 193.99.253.34
        input filter before = IP
        input deskip policy = AUTH
	Kij algorithm = 3DES-3
	MAC algorithm = MD5
        Crypt algorithm = NONE
        output filter after = IP
        output enskip mode = ALL
        flags = NONE

The "src ip" and "dst ip" sections link IP addresses to the key IDs. You
can also add more than one IP address if your host has more than one
interface or if you share secret keys.

Note: ENskip supports asymmetric use of encryption algorithms, but Sun SKIP
for Solaris does not, so I advise you not to use this feature. Also, the 
above example specifies unneeded switches in the "inbound traffic" section. 
ENskip will always accept ANY algorithm. However, it easier to copy 
configuration files from host to host and to change entries if both inbound 
and outbound sections are identical.


2.3.3 Certificate Discovery Protocol (CDP)
------------------------------------------

Certain SKIP implementations don't support the certificate discovery
protocol (CDP), which uses transparent UDP to acquire the public keys of
remote hosts and stores them in the CERT/cache directory.

Using CDP has the advantage that you can configure a system to ask all remote 
hosts for keys first, communicate securely if the keys are available and fall
back to unencrypted communication only if the remote host does not support
the SKIP protocol. To achieve this, set "flags = NONE" in the "default" 
section of your skipd.conf and soft link the UDH certificate files to their
corresponding IPv4 names. In the example given above, ln -s
 CERT/public/08-67193A592E4026EC8F1AE7882E7CA258-1 to
 CERT/public/01-193.99.253.34
and
 CERT/secret/08-67193A592E4026EC8F1AE7882E7CA258-1 to
 CERT/secret/01-193.99.253.34

In addition, CDP has the advantage that you will not have to worry about
the format of certificate files and how to make ENskip recognize them.

If the remote host does not support CDP, you can store the public keys 
on a key server. The ENskip daemon can act as a key server if the public
keys are in the CERT/public or CERT/cache directories (use cert_server if 
you want to run a key server without the ENskip module and daemon).
Add remote servers to the "lookuphosts=" directive in skipd.conf.


2.3.4 Manual keying, VPNet products
-----------------------------------

Certain SKIP implementations do not support the calculation of UDH values.
For these implementations (e.g. VPNet), ENskip supports "manual secrets" (i.e.
symmetric keys instead of asymmetric UDH).

These implementations might support the notion of key IDs (NSID/MKID) and
even include them in the SKIP packets, but nevertheless be unable to 
calculate DH values. In the following example, we will use NSID 1, i.e. plain 
IPv4 addresses.

First get the IP address of the remote host and secretly exchange a secret
value with the remote system administrator (although ENskip supports the
hashing of strings for key generation, the remote implementation might not,
so we will use a hex value in this example, 0x123456789ABCDEF0123456789ABCDEF0).
The maximum length of a hex value is 256 bit.

Check whether the remote implementation requires NSID 1/MKID pairs to
be present in the SKIP packets (you will have to use the "src mkid=YES" and
"dst mkid=YES" directives), or whether it is capable of deriving them from
the packet IP addresses (default for ENskip, corresponding to "src mkid=AUTO", 
"dst mkid=AUTO").

Example: They key ID of our host is 01-193.99.253.34 (01- plus IP address),
the key ID of the remote host is 01-193.99.253.62. NSID/MKID must be 
present in the packets, we don't authenticate packets, but encrypt only.

In skipd.conf, add two sections after the "default" section.

Outgoing traffic:

  01-193.99.253.34, 01-193.99.253.62:
	src mkid=YES
	dst mkid=YES
        input filter before = IP
        input deskip policy = CRYPT
	Kij algorithm = 3DES-3
	MAC algorithm = NONE
        Crypt algorithm = RC4-128
        output filter after = IP
        output enskip mode = ALL
	manual secret = 0x123456789ABCDEF0123456789ABCDEF0
        flags = NONE

and incoming traffic:

  01-193.99.253.62, 01-193.99.253.34:
        input filter before = IP
        input deskip policy = CRYPT
	Kij algorithm = 3DES-3
	MAC algorithm = NONE
        Crypt algorithm = RC4-128
        output filter after = IP
        output enskip mode = ALL
	manual secret = 0x123456789ABCDEF0123456789ABCDEF0
        flags = NONE


2.3.5 Configuration file syntax
-------------------------------

This section is an attempt to explain the configuration language
(to really understand the parser, I advise you to study lib/parser.c).

The configuration file should begin with a default entry.

  # I am a comment
  default:
     option1 = value_a
     option2 = value_b

To set options for specific hosts, specify their IP addresses using
NSID 1 (name space ID one, i.e. IP addresses) or NSID 8 (UDH certificates):

  01-127.0.0.1, 01-127.0.0.1:
     option1 = value_c
     option3 = value_d
would apply to packets from localhost to localhost. To cover both
directions of a connection, you would have to specify forward and
reverse direction:
  01-193.99.253.34, 01-193.99.253.62:
     option... = value...

  01-193.99.253.62, 01-193.99.253.34:
     option... = value...

You can temporarily disable a block of options. Change the "01-x, 01-x:"
to "ignore:".

You can also specify IDs in other name spaces. However, these IDs must
be given in hex.

The following configuration file options currently make sense
(please don't change other options, you might get weird results) --
note: { xx } means more than one value can be specified at a time.

  output enskip mode = { NONE | TCP | UDP | ICMP | OTHER | ALL }
     ENskip will only authenticate/encrypt the specified IP packet
     types. It is still possible that ENskip will send a plain packet
     if no key is found (if filters permit, see below).
     To disable ENskip for a destination address, use
        output enskip mode = NONE

  Kij algorithm = DES | 3DES-3 | 3DES-2 | IDEA | RC2-40 | RC2-128 | SAFER-SK128
     Sets the packet key encryption algorithm (only block ciphers are
     permitted).
     To calculate the Kij field in the SKIP packet header, both a block cipher
     and a hash algorithm are needed. In this implementation, the hash algorithm
     is always MD5 (don't confuse this with the MAC hash, see below).
     Without this entry, ENskip cannot authenticate or encrypt. For this
     reason, "NONE" is not permitted.
     Most of the algorithms are implemented for interoperability with other
     SKIP implementations only, in particular RC2-40. RC2-40 is not faster
     than RC2-128, only a lot less secure.
     For secure communication, I recommend IDEA or 3DES-3.

  Crypt algorithm = NONE | DES | RC2-40 | RC2-128 | RC4-40 | RC4-128 | 3DES-2 |
                    3DES-3 | IDEA | SAFER-SK128 | SIMPLE
     Uses the specified algorithm to encrypt the packet (or NONE if you
     want authentication only). Again, some algorithms are not recommended,
     namely SIMPLE, RC2-40 and RC4-40. SIMPLE is a simple XOR and RC2-40 and
     RC4-40 are the export restricted versions of their strong 128-bit brethren.
     For secure communication, I suggest 3DES-3, IDEA or RC4-128. Since
     RC4-128 is about three to five times faster than the other algorithms,
     use RC4-128 for best performance.

  MAC algorithm = NONE | MD5
     Uses the specified algorithm to authenticate packets (or NONE if you
     do not want authentication).

  input deskip mode = NONE | DESKIP
     Set to DESKIP if you want ENskip to process any packets at all.

  input deskip policy = { NONE | CRYPT | AUTH }
     If an incoming packet is not processed with all the given modes, it
     will be discarded.
       NONE:  accept all packets
       CRYPT: packet must be encrypted
       AUTH:  packet must be authenticated

  input filter before = NONE | IP | SKIP
  output filter before = NONE | IP | SKIP
     Filters applied to received/sent packets before processing. These
     filters can be used to prevent packets within packets within....
     (the Linux implementation can cope with this).
       SKIP: all SKIP packets will be discarded.
       IP:   all clear text IP packets will be discarded.

  input filter after = NONE | IP | SKIP
  output filter after = NONE | IP | SKIP
     Filters applied to successfully processed packets.

     To prevent ENskip from sending cleartext (unsigned and/or unencrypted)
     to a given host, e.g. because it could not resolve a key, use
       output filter after = IP

     To discard SKIP packets within SKIP, use
       input filter after = SKIP

  manual secret = "any unguessable secret" | hex number
     A manually configured shared secret (i.e. a symmetric key).
     If you specify a string, the string is hashed to obtain a key. If
     you specify a hex number, the hex number is used (256 bit at maximum).
     It is better to use the cert mode instead (see above),
     which uses a public key scheme.

     Examples:
       string: manual secret = "There are mountains in Switzerland"
       hex:    manual secret = 0x123456

  flags = { NONE | NO_KEY | VALID_KEY | TUNNEL }
      NO_KEY:    The entry does not contain a shared secret. Don't bother
                 looking for one, send plaintext (if filters permit). This
                 is normally used in the "default" section.
      NONE:	 No flags apply. Should be used in normal configuration
                 entries.
      VALID_KEY: The entry DOES contain a valid secret. VALID_KEY should
                 not be specified by the user, it is set automatically
                 by ENskip.
      TUNNEL:    Encapsulate whole IP packets instead of payload data
                 only (network layer mode instead of transport layer
                 mode). As the packets become larger, the performance
                 decreases. Tunnel mode is however useful for virtual
                 private networks and the like.

  src ip = { IPaddress }
  dst ip = { IPaddress }
      Maps the given source/destination IP addresses to the specified
      entry. These entries are vital if you use NSIDs other than
      NSID 1 (= IPv4 addresses).

  ttl = integer
      Minimum time-to-live in seconds for entries in the primary cache 
      (the cache in the loadable module). The time-to-live of the cache
      entry grows up to maxttl if the key is used (see below).

  maxttl = integer
      Purge entries from the primary cache if older than maxttl seconds.
      If both ttl and maxttl are set to zero, the entry will remain
      in the primary cache forever.

  keyttl = integer
      Absolute time-to-live of a key in seconds. Warning! If you use manual
      keys, the key will be discarded after keyttl seconds and ENskip will no
      longer be able to send authenticated and encrypted data. If you don't
      specify filters, ENskip will then communicate in plain text mode...

  key change time = integer
  key change bytes = integer
      The lifetime of a transient packet key (Kp) in seconds,
      and the maximal number of encrypted data bytes. Kp will change after
      key change time seconds or key change bytes worth of data, whichever
      comes first.

  lookuphosts = { IPaddress }
      Servers for public keys. Ask them in addition to the packet
      destination/source.

  src mkid = AUTO | YES | NO
  dst mkid = AUTO | YES | NO
      AUTO: Per default, ENskip does not include NSID/MKID in packets where 
            NSID and MKID can be derived from the packet IP source and 
            destination (NSID 1 = IPv4 addresses, MKIDs = packet source and 
            destination).
      YES:  Include NSID/MKID even if redundant.
      NO:   Don't include NSID/MKID (don't use this if the remote host 
            runs ENskip).


3. How to test ENskip
=====================

Install it on more than one machine and connect... Sun SKIP for Solaris is OK 
for testing, too (see samples/skipd.conf).

3.1 tcpdump
-----------

In the tcpdump/ directory, you will find a patch for tcpdump. The
tcpdump package is available from
	ftp://ftp.ee.lbl.gov/

Use tcpdump -k to display the contents of SKIP IP packets (and note that,
under Linux, you will see incoming traffic both encrypted and unencrypted).


4. Troubleshooting
==================

To detect wrong configurations run the skip_stat tool to query error counters
and statistics. skip_dump dumps the primary cache.


5. Latest versions
==================

The latest ENskip version can be obtained from
  ftp://ftp.tik.ee.ethz.ch/pub/packages/skip/


6. Trademarks
=============

Sun, Sun Microsystems, Solaris, SunOP, and the Sun logo are trademarks or 
registered trademarks of Sun Microsystems, Inc. SunScreen is a trademark of 
the Internet Commerce Group, a division of Sun Microsystems, Inc. All SPARC 
trademarks, are trademarks or registered trademarks of SPARC International, 
Inc. All other product names mentioned herein are the trademarks of their 
respective owners.


// 25 Feb 1997 Robert Muchsel <muchsel@acm.org>

