1 .\" netsniff-ng - the packet sniffing beast
2 .\" Copyright 2013 Daniel Borkmann.
3 .\" Subject to the GPL, version 2.
5 .TH CURVETUN 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
7 curvetun \- a lightweight curve25519 ip4/6 tunnel
11 \fB curvetun\fR [\fIoptions\fR]
14 curvetun is a lightweight, high-speed ECDH multiuser IP tunnel for Linux
15 that is based on epoll(2). curvetun uses the Linux TUN/TAP interface and
16 supports {IPv4, IPv6} over {IPv4, IPv6} with UDP or TCP as carrier protocols.
18 It has an integrated packet forwarding tree, thus multiple users with
19 different IPs can be handled via a single tunnel device on the server side
20 and flows are scheduled for processing in a CPU efficient way, at least in the
21 case of TCP as the carrier protocol.
23 For key management, public-key cryptography based on elliptic curves are being
24 used and packets are encrypted end-to-end by the symmetric stream cipher
25 Salsa20 and authenticated by the MAC Poly1305, where keys have previously
26 been computed with the ECDH key agreement protocol Curve25519.
28 Cryptography is based on Daniel J. Bernstein's networking and cryptography
29 library \[lq]NaCl\[rq]. By design, curvetun does not provide any particular pattern
30 or default port numbers that gives certainty that the connection from a
31 particular flow is actually running curvetun.
33 However, if you have a further need to bypass censorship, you can try using
34 curvetun in combination with Tor's obfsproxy or Telex. Furthermore, curvetun
35 also protects you against replay attacks and DH man-in-the-middle attacks.
36 Additionally, server-side syslog event logging can also be disabled to not
37 reveal any critical user connection data.
40 obfsproxy from the TOR project
42 \%https://www.torproject.org/projects/obfsproxy.html.en
46 Telex, anti-censorship in the network infrastructure
53 .SS -d <tundev>, --dev <tundev>
54 Defines the name of the tunnel device that is being created. If this option
55 is not set, then the default names for curves{0,1,2,..} for a curvetun server
56 and curvec{0,1,2,...} for a curvetun client are used.
58 .SS -p <num>, --port <num>
59 Defines the port the curvetun server should listen on. There is no default port
60 for curvetun in general, so setting this option for server bootstrap is
61 mandatory. This option is for servers only.
63 .SS -t <server>, --stun <server>
64 If needed, this options enables an STUN lookup in order to show public IP/port
65 mapping and to punch a hole into the firewall. In case you are unsure what STUN
66 server to use, simply use ``--stun stunserver.org''.
68 .SS -c[=alias], --client[=alias]
69 Starts curvetun in client mode and connects to the given connection alias that is
70 defined in the configuration file.
73 Generate private and public keypair. If not done yet, this must be done
77 Export our user and key combination to stdout as a one-liner.
80 Dump all known clients that may connect to the local curvetun server
84 Dump all known servers we as a client can connect to, and exit.
87 Do not fork off as a client or server on startup.
90 Starts curvetun in server mode. Additional parameters are needed, at least
91 the definition of the port clients can connect to.
94 Disable all curvetun logging of possible user information. This can
95 be used for having curvetun users connect more anonymously. This option
99 Use UDP as a carrier protocol instead of TCP. By default TCP is the
100 carrier protocol. This option is for servers only.
103 Defines IPv4 as the underlying network protocol to be used on the tunnel
104 device. IPv4 is default. This option is for servers only.
107 Defines IPv6 as the underlying network protocol to be used on the tunnel
108 device. This option is for servers only.
111 Show version information and exit.
114 Show user help and exit.
118 .SS curvetun --server -4 -u -N --port 6666 --stun stunserver.org
119 Starts curvetun in server mode with IPv4 as network protocol and UDP as a transport
120 carrier protocol. The curvetun server listens for incoming connections on port 6666
121 and performs an STUN lookup on startup to stunserver.org.
123 .SS curvetun --client=ethz
124 Starts curvetun in client mode and connects to the defined connection alias ``ethz''
125 that is defined in the curvetun ~/.curvetun/servers configuration.
127 .SS curvetun --keygen
128 Generates initial keypairs and stores them in ~/.curvetun/.
130 .SS curvetun --export
131 Exports your user data to stdout for configuration of a curvetun server.
134 Encrypted IP tunnels are often used to create virtual private networks (VPN),
135 where parts of the network can only be reached via an insecure or untrusted medium
136 such as the Internet. Only a few software utilities exists to create such tunnels,
137 or, VPNs. Two popular representatives of such software are OpenVPN and VTUN.
139 The latter also introduced the TUN/TAP interfaces into the Linux kernel. VTUN
140 only has a rather basic encryption module, that does not fit todays
141 cryptographic needs. By default, MD5 is used to create 128-Bit wide keys for
142 the symmetric BlowFish cipher in ECB mode [1].
144 Although OpenSSL is used in both VTUN and OpenVPN, OpenVPN is much more
145 feature rich regarding ciphers and user authentication. Nevertheless, letting
146 people choose ciphers or authentication methods is not necessarily a
147 good thing: administrators could either prefer speed over security and
148 therefore choose weak ciphers, so that the communication system will be as
149 good as without any cipher; they could choose weak passwords for symmetric
150 encryption or they could misconfigure the communication system by having too
151 much choice of ciphers and too little experience for picking the right one.
153 Next to the administration issues, there are also software development issues.
154 Cryptographic libraries like OpenSSL are a huge mess and too low-level and
155 complex to properly fully understand or correctly apply, so that they form a
156 further ground for vulnerabilities of such software.
158 In 2010, the cryptographers Tanja Lange and Daniel J. Bernstein have therefore
159 created and published a cryptography library for networking, which is called
160 NaCl (pronounced ''salt''). NaCl addresses such problems as mentioned in
161 OpenSSL and, in contrast to the rather generic use of OpenSSL, was created
162 with a strong focus on public-key authenticated encryption based on elliptic
163 curve cryptography, which is used in curvetun. Partially quoting Daniel J.
166 RSA is somewhat older than elliptic-curve cryptography: RSA was introduced
167 in 1977, while elliptic-curve cryptography was introduced in 1985. However,
168 RSA has shown many more weaknesses than elliptic-curve cryptography. RSA's
169 effective security level was dramatically reduced by the linear sieve in the
170 late 1970s, by the quadratic sieve and ECM in the 1980s, and by the
171 number-field sieve in the 1990s. For comparison, a few attacks have been
172 developed against some rare elliptic curves having special algebraic
173 structures, and the amount of computer power available to attackers has
174 predictably increased, but typical elliptic curves require just as much
175 computer power to break today as they required twenty years ago.
177 IEEE P1363 standardized elliptic-curve cryptography in the late 1990s,
178 including a stringent list of security criteria for elliptic curves. NIST
179 used the IEEE P1363 criteria to select fifteen specific elliptic curves at
180 five different security levels. In 2005, NSA issued a new ''Suite B''
181 standard, recommending the NIST elliptic curves (at two specific security
182 levels) for all public-key cryptography and withdrawing previous
183 recommendations of RSA.
185 curvetun uses a particular elliptic curve, Curve25519, introduced in the
186 following paper: Daniel J. Bernstein, ''Curve25519: new Diffie-Hellman speed
187 records,'' pages 207-228 in Proceedings of PKC 2006, edited by Moti Yung,
188 Yevgeniy Dodis, Aggelos Kiayias, and Tal Malkin, Lecture Notes in Computer
189 Science 3958, Springer, 2006, ISBN 3-540-33851-9.
191 This elliptic curve follows all of the standard IEEE P1363 security criteria.
192 It also follows new recommendations that achieve ''side-channel immunity''
193 and ''twist security'' while improving speed. What this means is that secure
194 implementations of Curve25519 are considerably simpler and faster than secure
195 implementations of, for example, NIST P-256; there are fewer opportunities for
196 implementors to make mistakes that compromise security, and mistakes are
197 more easily caught by reviewers.
199 An attacker who spends a billion dollars on special-purpose chips to attack
200 Curve25519, using the best attacks available today, has about 1 chance in
201 1000000000000000000000000000 of breaking Curve25519 after a year of computation.
202 One could achieve similar levels of security with 3000-bit RSA, but
203 encryption and authentication with 3000-bit RSA are not nearly fast enough
204 to handle tunnel traffic and would require much more space in network
208 Security analysis of VTun
210 \%http://www.off.net/~jme/vtun_secu.html
214 NaCl: Networking and Cryptography library
216 \%http://nacl.cr.yp.to/
220 If you've never run curvetun before, you need to do an initial setup once.
222 First, make sure that the servers and clients clocks are periodically
223 synced, for example, by running an ntp daemon. This is necessary to protect
224 against replay attacks. Also, make sure you have read and write access to
225 /dev/net/tun. You should not run curvetun as root! Then, after you have assured
226 this, the first step is to generate keys and config files. On both the client
231 You are asked for a user name. You can use an email address or whatever suits
232 you. Here, we assume you have entered 'mysrv1' on the server and 'myclient1'
235 Now, all necessary files have been created under ~/.curvetun. Files include
236 \[lq]priv.key\[rq], \[lq]pub.key\[rq], \[lq]username\[rq], \[lq]clients\[rq]
237 and \[lq]servers\[rq].
239 \[lq]clients\[rq] and \[lq]servers\[rq] are empty at the beginning and need
240 to be filled. The \[lq]clients\[rq] file is meant for the server, so that it
241 knows what clients are allowed to connect. The \[lq]servers\[rq] file is for
242 the client, where it can select curvetun servers to connect to. Both files are
243 kept very simple, so that a single configuration line per client or server
246 The client needs to export its public key data for the server
250 where it prints sth like:
252 myclient1;11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
253 \\_______/ \\_____________________________________________________________________________________________/
254 username 32 byte public key for 'myclient1'
256 This line is transferred to the server admin (yes, we assume a manual on-site
257 key exchange scenario where f.e. the admin sets up server and clients), where
258 the admin then adds this entry into his ``clients'' file like:
260 server$ echo "myclient1;11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:" \\
261 "11:11:11:11:11:11:11:11:11:11:11:11:11:11:11" >> ~/.curvetun/clients
263 The server admin can check, if the server has registered it properly by
267 which prints all parsed clients from ``~/.curvetun/clients''. This process could
268 easily be automated/scripted with f.e. Perl and LDAP.
270 Now, the client ``myclient1'' is known to the server; that's it for the server
271 configuration. The next step is to tell the client where he needs to connect to
274 We assume in this example that the tunnel server has an public IP i.e. 1.2.3.4,
275 runs on port 6666 and uses UDP as a carrier protocol. In case you are behind
276 a NAT, you can use curvetun's ``--stun'' option for starting the server, to
277 obtain your mapping. However, in this example we continue with 1.2.3.4 and 6666,
280 First, the server needs to export its key to the client, as
284 where it prints sth like:
286 mysrv1;22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22
287 \\____/ \\_____________________________________________________________________________________________/
288 username 32 byte public key for 'mysrv1'
289 ^-- you need this public key
291 Thus, you now have the server IP, server port, server transport protocol and the
292 server's public key at hand. Thus, on the client side it can be put all together
295 client$ echo "myfirstserver;1.2.3.4;6666;udp;22:22:22:22:22:22:22:22:22:22:" \\
296 "22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:" \\
297 "22:22" >> ~/.curvetun/servers
299 where the client can check its config via:
303 Okay, assuming we've made it, then we start the server with:
305 server$ curvetun -s -p 6666 -u
306 server# ifconfig curves0 up
307 server# ifconfig curves0 10.0.0.1/24
309 Then, we start the client with:
311 client$ curvetun -c=myfirstserver
312 client# ifconfig curvec0 up
313 client# ifconfig curvec0 10.0.0.2/24
315 Also, client-side information, errors or warnings will appear in syslog! By now
316 we should be able to ping the server:
318 client$ ping 10.0.0.1
320 That's it! Routing example:
322 Server side's public IP on eth0 is i.e. 1.2.3.4:
324 server$ ... start curvetun server ...
325 server# ifconfig curves0 up
326 server# ifconfig curves0 10.0.0.1/24
327 server# echo 1 > /proc/sys/net/ipv4/ip_forward
328 server# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
329 server# iptables -A FORWARD -i eth0 -o curves0 -m state --state RELATED,ESTABLISHED -j ACCEPT
330 server# iptables -A FORWARD -i curves0 -o eth0 -j ACCEPT
332 Client side's IP on eth0 is i.e. 5.6.7.8:
334 client$ ... start curvetun client ...
335 client# ... lookup your default gateway (e.g. via route, here: 5.6.7.9) ...
336 client# ifconfig curvec0 up
337 client# ifconfig curvec0 10.0.0.2/24
338 client# route add -net 1.2.3.0 netmask 255.255.255.0 gw 5.6.7.9 dev eth0
339 client# route add default gw 10.0.0.1
340 client# route del default gw 5.6.7.9
342 That should be it, happy browsing and emailing via curvetun tunnels!
345 This software is an experimental prototype intended for researchers. It will most
346 likely mature over time, but it is currently not advised to use this software
347 when life is put at risk.
350 Blackhole tunneling is currently not supported.
353 curvetun is licensed under the GNU GPL version 2.0.
357 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It is
358 currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
359 Borkmann <dborkma@tik.ee.ethz.ch>.
371 Manpage was written by Daniel Borkmann.