diff options
-rw-r--r-- | doc/Makefile.am | 35 | ||||
-rw-r--r-- | doc/README.html.in | 269 | ||||
-rw-r--r-- | doc/TODO | 3 | ||||
-rw-r--r-- | doc/style.css | 32 |
4 files changed, 339 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..a3f55c7 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,35 @@ +# $Id$ + +# This file is part of seppl. +# +# seppl 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. +# +# seppl 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 seppl; if not, write to the Free Software Foundation, +# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. + +noinst_DATA = README.html README +EXTRA_DIST = $(noinst_DATA) style.css README.html.in + +MAINTAINERCLEANFILES = README README.html +CLEANFILES = + +if USE_LYNX +README: README.html + lynx --dump $^ | sed 's,file://localhost/.*/doc/README.html,README,' > $@ + +CLEANFILES += README +endif + +tidy: README.html + tidy -e < README.html + +.PHONY: tidy diff --git a/doc/README.html.in b/doc/README.html.in new file mode 100644 index 0000000..ea3b39e --- /dev/null +++ b/doc/README.html.in @@ -0,0 +1,269 @@ +<?xml version="1.0" encoding="iso-8895-15"?> <!-- -*-html-helper-*- --> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<!-- $Id$ --> + +<head> +<title>seppl @PACKAGE_VERSION@</title> +<link rel="stylesheet" type="text/css" href="style.css" /> +</head> + +<body> +<h1><a name="top">seppl @PACKAGE_VERSION@</a></h1> + +<p><i>Copyright 2003 Lennart Poettering <@PACKAGE_BUGREPORT@></i></p> + +<ul class="toc"> + <li><a href="#license">License</a></li> + <li><a href="#news">News</a></li> + <li><a href="#overview">Overview</a></li> + <li><a href="#status">Status</a></li> + <li><a href="#documentation">Documentation</a></li> + <li><a href="#requirements">Requirements</a></li> + <li><a href="#installation">Installation</a></li> + <li><a href="#acks">Acknowledgements</a></li> + <li><a href="#download">Download</a></li> +</ul> + +<h2><a name="license">License</a></h2> + +<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.</p> + +<p>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.</p> + +<p>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., 675 Mass Ave, Cambridge, MA 02139, USA.</p> + +<h2><a name="news">News</a></h2> + +<div class="news-date">Wed Nov 5 2003: </div> +<p class="news-text"><a href="@PACKAGE_URL@seppl-0.2.tar.gz">Version 0.2</a> released; changes include: ported to kernel 2.4.22, autoconf/automake based build system, init script</p> + +<h2><a name="overview">Overview</a></h2> + +<p><tt>seppl</tT> is both a protocol definition and a software implementation of a +new encryption layer for IPv4. It makes use of symmetric cryptography +for encrypting the whole traffic on a network. Its implementation +is designed around Linux <a href="http://netfilter.org"><tt>netfilter/iptables</tt></a>.</p> + +<p><tt>seppl</tt> introduces two new netfilter targets: <tt>CRYPT</tt> and <tt>DECRYPT</tt>. A +firewall rule may thus be used for encrypting/decrypting the incoming +and outgoing network traffic. This makes <tt>seppl</tt> extraordinarily easy to +use, since no daemons need to run for secure communication.</p> + +<p><tt>seppl</tt> uses the encryption engine of the <a +href="http://samba.org/~jamesm/crypto">Linux Cryptographic API</a> +which is available in kernel 2.4.22 and newer.</p> + +<p><tt>seppl</tt> is primarily intended for encrypting wireless LANs (as secure +replacement of the broken WEP encryption) and local ethernet networks +but may be used for large scale VPN solutions as well.</p> + +<p>The protocol <tt>seppl</tt> relies on is not compatible with any +other software. The protocol is open and well defined but there is no +implementation other than this reference software.</p> + +<h3>Why SEPPL, there are already IPSEC, CIPE,...?</h3> + +<p><tt>CIPE</tt> may be used for point-to-point connections only. It has tunnel +structure and thus introduces new IP addresses. This is not always +desirable. It requires a user space daemon.</p> + +<p><tt>IPSEC</tt>/FreeSwan is extremely complicated to use. Due to its +strange routing scheme it is nearly impossible to use together with +routing daemons. <tt>IPSEC</tt> is heavyweight.</p> + +<p><tt>seppl</tt> is truely peer-to-peer. It encrypts seamlessly all outgoing +traffic and it thus compatible with routing daemons. It is extremely +easy to use as well, as it makes no change to the normal routing +behaviour. <tt>seppl</tt> ist extremely leightweight.</p> + +<h2><a name="status">Status</a></h2> + +<p><tt>seppl</tt> @PACKAGE_VERSION@ is quite stable and feature complete</p> + +<h2><a name="documentation">Documentation</a></h2> + +<h3>The Implementation</h3> +<p>The implementation consists of three Linux kernel modules: <tt>seppl.o</tt>, +<tt>ipt_CRYPT.o</tt> and <tt>ipt_DECRYPT.o</tt>. The former is the in-kernel key +manager, the latter are the two new netfilter targets. Both depend on +<tt>seppl.o</tt>.</p> + +<p><tt>seppl.o</tt> must be inserted into kernel in first place. The +key manager may be accessed with the file +<tt>/proc/net/seppl_keyring</tt>. It contains binary key data, and is +initially empty. You may add a new key by writing it to that file.</p> + +<p>The two Python scripts <tt>seppl-ls</tt> and <tt>seppl-gen-key</tt> me be used for key +management. seppl-ls may be used for converting <tt>seppl</tt> keys between the +binary format used by <tt>/proc/net/seppl_keyring</tT> and a human readable XML +based format. Simply call <tt>seppl-ls</tt> for a list of all currently active +keys. <tt>seppl-gen-key</tt> generates a new key from <tt>/dev/urandom</tt>. By default +it will use the XML format. The parameter <tt>-x</tt> forces binary mode. You +may generate and activate two keys "linus" and "alan" by issuing the +following command lines:</p> + +<pre>seppl-gen-key -n linus -x > /proc/net/seppl_keyring +seppl-gen-key -n alan -x > /proc/net/seppl_keyring</pre> + +<p><tt>seppl-ls</tt> without argument lists the new keys saved in the kernel keyring. You may remove all (currently +unused) keys by issuing:</p> + +<pre>echo clear > /proc/net/seppl_keyring</pre> + +<p>Since <tt>seppl</tt> is based on symmetric cryptography using shared keys +you have to copy newly generated keys to every host you want to +connect to your <tt>seppl</tt> infrastructure. (preferably via SSH or any other +secure file transfer) You get a binary copy of your current keyring by +issuing:</p> + +<pre>cat /proc/net/seppl_keyring > keyring.save</pre> + +<p>Now copy that file <tt>keyring.save</tt> to all other hosts and issue the +following command there:</p> + +<pre>cat keyring.save > /proc/net/seppl_keyring</pre> + +<p>That is simple, isn't it?</p> + +<p>After doing so you may configure your firewall settings on each host:</p> + +<pre>iptables -t mangle -A POSTROUTING -o eth0 -j CRYPT --key linus +iptables -t mangle -A PREROUTING -i eth0 -j DECRYPT</pre> + +<p>This will encrypt all outgoing traffic on eth0 with the key "linus". All +incoming traffic is decrypted with either "linus" or "alan", depending on +the key name specified in the specific network packet. Unencrypted +incoming packets are silently dropped. Use</p> + +<pre>iptables -t mangle -A PREROUTING -p 177 -i eth0 -j DECRYPT</pre> + +<p>for allowing both crypted and unencrypted incoming traffic. </p> + +<p>That's it. You're done. All your traffic on the local subnet is now +crypted with <tt>seppl</tt>.</p> + +<p>The default cipher is AES-128. If you don't specify the name of the +used key it defaults to "def".</p> + +<p>An <tt>SysV</tt> init script <tt>/etc/init.d/seppl</tt> is provided. It will load +<tt>seppl</tt>'s kernel modules and write all keys from the directory +<tt>/etc/seppl</tt> to the kernel keyring. It will not add any +firewall rules, however.</p> + +<h3>Performance issues</h3> + +<p>The network packets are increased in size when they are crypted, since +two new headers and the IV are added. (36 bytes in average) This +conflicts on some way with the MTU management of the Linux kernel and +results in having all large packets (that is: package size near MTU) +fragmented in one large and another very small package. This will hurt +network performance. A work-around of this limitation is using the +TCPMSS target of netfilter to adjust the MSS value in the TCP header +to smaller values. This will increase TCP perfomance, since TCP +packets of the size of the MTU are no longer generated. Thus no +fragmentation is needed. However, TCPMSS is TCP specific, it won't +help on UDP or other IP protocols.</p> + +<p>Add the following line before encryption to your firewall setup:</p> + +<pre>iptables -t mangle -A POSTROUTING -p tcp --tcp-flags SYN,RST SYN -o eth0 -j TCPMSS --set-mss $((1500-40-8-16-6-15))</pre> + +<h3>The Protocol</h3> + +<p>For encryption every single unencrypted packet is taken and converted +to a crypted one. Not a single further packet is ever sent.</p> + +<pre> Original SEPPL counterpart ++------------+ +-----------------------+ \ +| IP-Header | | Modified IP-Header | | ++------------+ <==> +-----------------------+ | +| Payload | | SEPPL-Header | > Unencrypted ++------------+ +-----------------------+ | + | Initialization Vector | | + +-----------------------+ / + | SEPPL-Header | \ + +-----------------------+ | Crypted + | Payload | | + +-----------------------+ /</pre> + + +<p>The original IP header is kept as far as possible. Only three fields +are replaced with new values. The protocol number is set to 177, the +fragment offset is set to 0 and the total length is corrected to the +new length. All other fields are kept as is, including IP options.</p> + +<p>The unencrypted <tt>seppl</tt> header consists of a one-byte cipher number and +a key name. Currently only 0 and 1 are defined as cipher numbers for +AES with 128bit key, resp. AES with 192bit key. The key name (7 bytes) +may be used to select a specific key in a larger keyring.</p> + +<p>The IV is used for CBC coding of the cipher used. It differs from +packet to packet, but is not randomly generated. Due to perfomance +reasons, only the initial IV on system startup is randomized, all +following IVs are generated by incrementing the previous ones.</p> + +<p>The crypted <tt>seppl</tt> header consists of three saved fields of the +original IP header (protocol number, fragment offset, total length) +and a byte which is always 0 for detecting unmatching keys.</p> + +<p>The payload is the original IP-playload, from the TCP/UDP/other header +to the end.</p> + + +<h3>Disclaimer</h3> + +<p>This is my first Linux kernel project, I am new to kernel hacking, so +please be gracious!</p> + +<p>IANAC ("I Am Not A Cryptoanalist"), I cannot guarantee that I used the cryptographic routines +correctly. I think I did, but maybe I am plain stupid.</p> + +<h2><a name="requirements">Requirements</a></h2> + +<p><tt>seppl</tt> was developed and tested on Debian +GNU/Linux "testing" from Nov 2003, it should work on most other +Linux distributions and +Unix versions since it uses GNU Autoconf and GNU libtool for source +code configuration and shared library management.</p> + +<p><tt>seppl</tt> requires Linux 2.4.22 (sources installed) and +<tt>iptables</tt> 1.2.8 or newer.</p> + +<p>The userspace tools require Python 2.1 or newer</p> + +<h2><a name="installation">Installation</a></h2> + +<p>As this package is made with the GNU autotools you should run +<tt>./configure</tt> inside the distribution directory for configuring +the source tree. After that you should run <tt>make</tt> for +compilation and <tt>make install</tt> (as root) for installation of +<tt>seppl</tt>.</p> + +<h2><a name="acks">Acknowledgements</a></h2> + +<p>None so far</p> + +<h2><a name="download">Download</a></h2> + +<p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p> + +<p>The current release is <a href="@PACKAGE_URL@seppl-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p> + +<p>Get <tt>seppl</tt>'s development sources from the <a href="http://subversion.tigris.org/">Subversion</a> <a href="https://seth.intheinter.net:8081/svn/seppl/">repository</a>.</p> + +<hr/> +<address>Lennart Poettering <@PACKAGE_BUGREPORT@>, November 2003</address> +<div><i>$Id$</i></div> + +</body> +</html> diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 0000000..c1a5e97 --- /dev/null +++ b/doc/TODO @@ -0,0 +1,3 @@ +1. SEPPL matcher +2. Init script (done) +3. Support for mor ciphers diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..69f653a --- /dev/null +++ b/doc/style.css @@ -0,0 +1,32 @@ +/* $Id$ */ + +/*** + * This file is part of seppl. + * + * seppl 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. + * + * seppl 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 seppl; if not, write to the Free Software Foundation, + * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. + ***/ + +body { color: black; background-color: white; margin: 0.5cm; } +a:link, a:visited { color: #900000; } +p { margin-left: 0.5cm; margin-right: 0.5cm; } +div.news-date { margin-left: 0.5cm; font-size: 80%; color: #4f0000; } +p.news-text { margin-left: 1cm; } +ul { margin-left: 0.5cm; } +h1 { color: #00009F; } +h2 { color: #00009F; } +h3 { color: #00004F; margin-left: 0.5cm; } +ul { margin-left: .5cm; } +ol { margin-left: .5cm; } +pre { margin-left: .5cm; background-color: #f0f0f0; padding: 0.4cm;} |