1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<?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,2004 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">Thu Jan 22 2004: </div> <p class="news-text"><a
href="@PACKAGE_URL@seppl-0.4.tar.gz">Version 0.4</a> released; changes
include: port to Linux 2.6, no other changes. <b>Version 0.4 is no
longer compatible with kernel 2.4. Use version 0.3 for kernel 2.4, it
is functionally equivalent.</b> </p>
<div class="news-date">Sat Dec 6 2003: </div> <p class="news-text"><a
href="@PACKAGE_URL@seppl-0.3.tar.gz">Version 0.3</a> released; changes
include: IV are no longer simply increased from packet to packet, a C
implementation of <tt>seppl-gen-key</tt> was added, the
<tt>iptables</tt> release is automatically detected now, support for
kernels with versioned symbols.</p>
<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> is extremely lightweight.</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>Limitations</h3>
<p><tt>seppl</tt> interferes with netfilter's connection tracking in
some way. Thus you will not be able to use NAT in conjunction with
<tt>seppl</tt>. If you use connection tracking in some other way
together with <tt>seppl</tt> your mileage may vary.</p>
<p><tt>seppl</tt> is tested with Linux 2.6.1. Use version 0.3 for Linux 2.4.</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.6.{0,1} (configured sources installed) and
<tt>iptables</tt> 1.2.8 or newer.</p>
<p>The complete userspace tool set requires Python 2.1 or newer. A stripped down set in C is available as well.</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>Donald J Bindner for many patches</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 class="grey">Lennart Poettering <@PACKAGE_BUGREPORT@>, January 2004</address>
<div class="grey"><i>$Id$</i></div>
</body>
</html>
|
