build: Add Makefile target for Coverity scanner
[netsniff-ng.git] / curvetun.8
blob1c06a9b9194f4125eaaae4628c50a5d4cf1a8f95
1 .\" netsniff-ng - the packet sniffing beast
2 .\" Copyright 2013 Daniel Borkmann.
3 .\" Subject to the GPL, version 2.
4 .PP
5 .TH CURVETUN 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
6 .SH NAME
7 curvetun \- a lightweight curve25519 ip4/6 tunnel
8 .PP
9 .SH SYNOPSIS
10 .PP
11 \fBcurvetun\fR [\fIoptions\fR]
12 .PP
13 .SH DESCRIPTION
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.
17 .PP
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.
22 .PP
23 For key management, public-key cryptography based on elliptic curves are
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.
27 .PP
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
30 pattern or default port numbers that gives certainty that the connection from
31 a particular flow is actually running curvetun.
32 .PP
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 avoid
37 revealing critical user connection data.
38 .PP
39 .IP " 1." 4
40 obfsproxy from the TOR project
41 .RS 4
42 \%https://www.torproject.org/projects/obfsproxy.html.en
43 .RE
44 .PP
45 .IP " 2." 4
46 Telex, anti-censorship in the network infrastructure
47 .RS 4
48 \%https://telex.cc/
49 .RE
50 .PP
51 .SH OPTIONS
52 .PP
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, curves{0,1,2,..} for a curvetun server,
56 and curvec{0,1,2,...} for a curvetun client are used.
57 .PP
58 .SS -p <num>, --port <num>
59 Defines the port the curvetun server should listen on. There is no default port
60 for curvetun, so setting this option for server bootstrap is mandatory. This
61 option is for servers only.
62 .PP
63 .SS -t <server>, --stun <server>
64 If needed, this options enables an STUN lookup in order to show public IP to 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''.
67 .PP
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.
71 .PP
72 .SS -k, --keygen
73 Generate private and public keypair. This must be done initially.
74 .PP
75 .SS -x, --export
76 Export user and key combination to stdout as a one-liner.
77 .PP
78 .SS -C, --dumpc
79 Dump all known clients that may connect to the local curvetun server and exit.
80 .PP
81 .SS -S, --dumps
82 Dump all known servers curvetun as a client can connect to, and exit.
83 .PP
84 .SS -D, --nofork
85 Do not fork off as a client or server on startup.
86 .PP
87 .SS -s, --server
88 Start curvetun in server mode. Additional parameters are needed, at least
89 the definition of the port that clients can connect to is required.
90 .PP
91 .SS -N, --no-logging
92 Disable all curvetun logging of user information. This option can be used to
93 enable curvetun users to connect more anonymously. This option is for servers
94 only.
95 .PP
96 .SS -u, --udp
97 Use UDP as a carrier protocol instead of TCP. By default, TCP is the
98 carrier protocol. This option is for servers only.
99 .PP
100 .SS -4, --ipv4
101 Defines IPv4 as the underlying network protocol to be used on the tunnel
102 device. IPv4 is the default. This option is for servers only.
104 .SS -6, --ipv6
105 Defines IPv6 as the underlying network protocol to be used on the tunnel
106 device. This option is for servers only.
108 .SS -v, --version
109 Show version information and exit.
111 .SS -h, --help
112 Show user help and exit.
114 .SH USAGE EXAMPLE
116 .SS curvetun --server -4 -u -N --port 6666 --stun stunserver.org
117 Starts curvetun in server mode with IPv4 as network protocol and UDP as a transport
118 carrier protocol. The curvetun server listens for incoming connections on port 6666
119 and performs an STUN lookup on startup to stunserver.org.
121 .SS curvetun --client=ethz
122 Starts curvetun in client mode and connects to the defined connection alias ''ethz''
123 that is defined in the curvetun ~/.curvetun/servers configuration file.
125 .SS curvetun --keygen
126 Generates initial keypairs and stores them in the ~/.curvetun/ directory.
128 .SS curvetun --export
129 Export user data to stdout for configuration of a curvetun server.
131 .SH CRYPTOGRAPHY
132 Encrypted IP tunnels are often used to create virtual private networks (VPN),
133 where parts of the network can only be reached via an insecure or untrusted medium
134 such as the Internet. Only a few software utilities exist to create such tunnels,
135 or, VPNs. Two popular representatives of such software are OpenVPN and VTUN.
137 The latter also introduced the TUN/TAP interfaces into the Linux kernel. VTUN
138 only has a rather basic encryption module, that does not fit todays
139 cryptographic needs. By default, MD5 is used to create 128-Bit wide keys for
140 the symmetric BlowFish cipher in ECB mode [1].
142 Although OpenSSL is used in both VTUN and OpenVPN, OpenVPN is much more
143 feature rich regarding ciphers and user authentication. Nevertheless, letting
144 people choose ciphers or authentication methods is not necessarily a
145 good thing: administrators could either prefer speed over security and
146 therefore choose weak ciphers, so that the communication system will be as
147 good as without any cipher; they could choose weak passwords for symmetric
148 encryption or they could misconfigure the communication system by having too
149 much choice of ciphers and too little experience for picking the right one.
151 Next to the administration issues, there are also software development issues.
152 Cryptographic libraries like OpenSSL are a huge mess and too low-level and
153 complex to fully understand or correctly apply, so that they form further
154 ground for vulnerabilities of such software.
156 In 2010, the cryptographers Tanja Lange and Daniel J. Bernstein have therefore
157 created and published a cryptographic library for networking, which is named
158 NaCl (pronounced ''salt''). NaCl addresses such problems as mentioned in
159 OpenSSL and, in contrast to the rather generic use of OpenSSL, was created
160 with a strong focus on public-key authenticated encryption based on elliptic
161 curve cryptography, which is used in curvetun. Partially quoting Daniel J.
162 Bernstein:
164 "RSA is somewhat older than elliptic-curve cryptography: RSA was introduced
165 in 1977, while elliptic-curve cryptography was introduced in 1985. However,
166 RSA has shown many more weaknesses than elliptic-curve cryptography. RSA's
167 effective security level was dramatically reduced by the linear sieve in the
168 late 1970s, by the quadratic sieve and ECM in the 1980s, and by the
169 number-field sieve in the 1990s. For comparison, a few attacks have been
170 developed against some rare elliptic curves having special algebraic
171 structures, and the amount of computer power available to attackers has
172 predictably increased, but typical elliptic curves require just as much
173 computer power to break today as they required twenty years ago.
175 IEEE P1363 standardized elliptic-curve cryptography in the late 1990s,
176 including a stringent list of security criteria for elliptic curves. NIST
177 used the IEEE P1363 criteria to select fifteen specific elliptic curves at
178 five different security levels. In 2005, NSA issued a new ''Suite B''
179 standard, recommending the NIST elliptic curves (at two specific security
180 levels) for all public-key cryptography and withdrawing previous
181 recommendations of RSA."
183 curvetun uses a particular elliptic curve, Curve25519, introduced in the
184 following paper: Daniel J. Bernstein, ''Curve25519: new Diffie-Hellman speed
185 records,'' pages 207-228 in Proceedings of PKC 2006, edited by Moti Yung,
186 Yevgeniy Dodis, Aggelos Kiayias, and Tal Malkin, Lecture Notes in Computer
187 Science 3958, Springer, 2006, ISBN 3-540-33851-9.
189 This elliptic curve follows all of the standard IEEE P1363 security criteria.
190 It also follows new recommendations that achieve ''side-channel immunity''
191 and ''twist security'' while improving speed. What this means is that secure
192 implementations of Curve25519 are considerably simpler and faster than secure
193 implementations of, for example, NIST P-256; there are fewer opportunities for
194 implementors to make mistakes that compromise security, and mistakes are
195 more easily caught by reviewers.
197 An attacker who spends a billion dollars on special-purpose chips to attack
198 Curve25519, using the best attacks available today, has about 1 chance in
199 1000000000000000000000000000 of breaking Curve25519 after a year of computation.
200 One could achieve similar levels of security with 3000-bit RSA, but
201 encryption and authentication with 3000-bit RSA are not nearly fast enough
202 to handle tunnel traffic and would require much more space in network
203 packets.
205 .IP " 1." 4
206 Security analysis of VTun
207 .RS 4
208 \%http://www.off.net/~jme/vtun_secu.html
211 .IP " 2." 4
212 NaCl: Networking and Cryptography library
213 .RS 4
214 \%http://nacl.cr.yp.to/
217 .SH SETUP HOWTO
218 If you have not run curvetun before, you need to do an initial setup once.
220 First, make sure that the servers and clients clocks are periodically
221 synced, for example, by running an NTP daemon. This is necessary to protect
222 against replay attacks. Also, make sure you have read and write access to
223 /dev/net/tun. You should not run curvetun as root! Then, after you have assured
224 this, the first step is to generate keys and config files. On both the client
225 and server do:
227 .B curvetun -k
229 You are asked for a user name. You can use an email address or whatever suits
230 you. Here, we assume you have entered 'mysrv1' on the server and 'myclient1'
231 on the client side.
233 Now, all necessary files have been created under ~/.curvetun. Files include
234 \[lq]priv.key\[rq], \[lq]pub.key\[rq], \[lq]username\[rq], \[lq]clients\[rq]
235 and \[lq]servers\[rq].
237 \[lq]clients\[rq] and \[lq]servers\[rq] are empty at the beginning and need
238 to be filled. The \[lq]clients\[rq] file is meant for the server, so that it
239 knows what clients are allowed to connect. The \[lq]servers\[rq] file is for
240 the client, where it can select curvetun servers to connect to. Both files are
241 kept very simple, so that a single configuration line per client or server
242 is sufficient.
244 The client needs to export its public key data for the server
246 .B curvetun -x
248 where it prints a string in the following format:
250   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
251   \\_______/ \\_____________________________________________________________________________________________/
252    username  32 byte public key for 'myclient1'
254 This line is transferred to the server admin (yes, we assume a manual on-site
255 key exchange scenario where, for example, the admin sets up server and clients), where
256 the admin then adds this entry into his ''clients'' file like:
258   server$ echo "myclient1;11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:" \\
259                "11:11:11:11:11:11:11:11:11:11:11:11:11:11:11" >> ~/.curvetun/clients
261 The server admin can check if the server has registered it properly as follows:
263   server$ curvetun \-C
265 which prints all parsed clients from ''~/.curvetun/clients''. This process could
266 easily be automated or scripted with, for example, Perl and LDAP.
268 Now, the client ''myclient1'' is known to the server; that completes the server
269 configuration. The next step is to tell the client where it needs to connect to
270 the server.
272 We assume in this example that the tunnel server has a public IP address, e.g. 1.2.3.4,
273 runs on port 6666 and uses UDP as a carrier protocol. In case you are behind
274 NAT, you can use curvetun's ''\-\-stun'' option for starting the server, to
275 obtain your mapping. However, in this example we continue with 1.2.3.4 and 6666,
276 UDP.
278 First, the server needs to export its key to the client, as follows:
280   server$ curvetun \-x
282 where it prints a string in the following format:
284   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
285   \\____/ \\_____________________________________________________________________________________________/
286  username  32 byte public key for 'mysrv1'
287            ^-- you need this public key
289 Thus, you now have the server IP address, server port, server transport protocol and the
290 server's public key at hand. On the client side it can be put all together
291 in the config as follows:
293   client$ echo "myfirstserver;1.2.3.4;6666;udp;22:22:22:22:22:22:22:22:22:22:" \\
294                "22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:"  \\
295                "22:22" >> ~/.curvetun/servers
297 The client can check its config using:
299   client$ curvetun \-S
301 Then we start the server with:
303   server$ curvetun \-s \-p 6666 \-u
304   server# ifconfig curves0 up
305   server# ifconfig curves0 10.0.0.1/24
307 Then, we start the client with:
309   client$ curvetun \-c=myfirstserver
310   client# ifconfig curvec0 up
311   client# ifconfig curvec0 10.0.0.2/24
313 Also, client-side information, errors, or warnings will appear in syslog! By now
314 we should be able to ping the server:
316   client$ ping 10.0.0.1
318 That's it! Routing example:
320 Server side's public IP on eth0 is, for example, 1.2.3.4:
322   server$ ... start curvetun server ...
323   server# ifconfig curves0 up
324   server# ifconfig curves0 10.0.0.1/24
325   server# echo 1 > /proc/sys/net/ipv4/ip_forward
326   server# iptables \-t nat \-A POSTROUTING \-o eth0 \-j MASQUERADE
327   server# iptables \-A FORWARD \-i eth0 \-o curves0 \-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT
328   server# iptables \-A FORWARD \-i curves0 \-o eth0 \-j ACCEPT
330 Client side's IP on eth0 is, for example, 5.6.7.8:
332   client$ ... start curvetun client ...
333   client# ... lookup your default gateway (e.g. via route, here: 5.6.7.9) ...
334   client# ifconfig curvec0 up
335   client# ifconfig curvec0 10.0.0.2/24
336   client# route add \-net 1.2.3.0 netmask 255.255.255.0 gw 5.6.7.9 dev eth0
337   client# route add default gw 10.0.0.1
338   client# route del default gw 5.6.7.9
340 That should be it, happy browsing and emailing via curvetun tunnels!
342 .SH NOTE
343 This software is an experimental prototype intended for researchers. It will most
344 likely mature over time, but it is currently not advised to use this software
345 when life is put at risk.
347 .SH BUGS
348 Blackhole tunneling is currently not supported.
350 .SH LEGAL
351 curvetun is licensed under the GNU GPL version 2.0.
353 .SH HISTORY
354 .B curvetun
355 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It is
356 currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
357 Borkmann <dborkma@tik.ee.ethz.ch>.
359 .SH SEE ALSO
360 .BR netsniff-ng (8),
361 .BR trafgen (8),
362 .BR mausezahn (8),
363 .BR bpfc (8),
364 .BR ifpps (8),
365 .BR flowtop (8),
366 .BR astraceroute (8)
368 .SH AUTHOR
369 Manpage was written by Daniel Borkmann.
371 .SH COLOPHON
372 This page is part of the Linux netsniff-ng toolkit project. A description of the project,
373 and information about reporting bugs, can be found at http://netsniff-ng.org/.