1CURVETUN(8)                   netsniff-ng toolkit                  CURVETUN(8)
2
3
4

NAME

6       curvetun - a lightweight curve25519 ip4/6 tunnel
7

SYNOPSIS

9       curvetun [options]
10

DESCRIPTION

12       curvetun  is  a  lightweight,  high-speed  ECDH multiuser IP tunnel for
13       Linux that is based on  epoll(2).   curvetun  uses  the  Linux  TUN/TAP
14       interface  and  supports {IPv4, IPv6} over {IPv4, IPv6} with UDP or TCP
15       as carrier protocols.
16
17       It has an integrated packet forwarding tree, thus multiple  users  with
18       different  IPs  can be handled via a single tunnel device on the server
19       side, and flows are scheduled for processing in a CPU efficient way, at
20       least in the case of TCP as the carrier protocol.
21
22       For  key  management,  public-key cryptography based on elliptic curves
23       are used and packets are encrypted end-to-end by the  symmetric  stream
24       cipher  Salsa20  and authenticated by the MAC Poly1305, where keys have
25       previously  been  computed  with  the  ECDH  key   agreement   protocol
26       Curve25519.
27
28       Cryptography  is based on Daniel J. Bernstein's networking and cryptog‐
29       raphy library “NaCl”. By design, curvetun does not provide any particu‐
30       lar  pattern or default port numbers that gives certainty that the con‐
31       nection from a particular flow is actually running curvetun.
32
33       However, if you have a further need to bypass censorship, you  can  try
34       using  curvetun  in combination with Tor's obfsproxy or Telex. Further‐
35       more, curvetun also protects you against replay attacks and DH  man-in-
36       the-middle attacks.  Additionally, server-side syslog event logging can
37       also be disabled to avoid revealing critical user connection data.
38
39        1. obfsproxy from the TOR project
40           https://www.torproject.org/projects/obfsproxy.html.en
41
42        2. Telex, anti-censorship in the network infrastructure
43           https://telex.cc/
44

OPTIONS

46       -d <tundev>, --dev <tundev>
47              Defines the name of the tunnel device that is being created.  If
48              this option is not set, then the default names, curves{0,1,2,..}
49              for a curvetun server,  and  curvec{0,1,2,...}  for  a  curvetun
50              client are used.
51
52       -p <num>, --port <num>
53              Defines  the port the curvetun server should listen on. There is
54              no default port for curvetun, so setting this option for  server
55              bootstrap is mandatory. This option is for servers only.
56
57       -t <server>, --stun <server>
58              If  needed, this options enables an STUN lookup in order to show
59              public IP to port mapping and to punch a hole into the firewall.
60              In  case  you  are  unsure  what  STUN server to use, simply use
61              ''--stun stunserver.org''.
62
63       -c[=alias], --client[=alias]
64              Starts curvetun in client mode and connects to the given connec‐
65              tion alias that is defined in the configuration file.
66
67       -k, --keygen
68              Generate  private  and  public  keypair.  This must be done ini‐
69              tially.
70
71       -x, --export
72              Export user and key combination to stdout as a one-liner.
73
74       -C, --dumpc
75              Dump all known clients that may connect to  the  local  curvetun
76              server and exit.
77
78       -S, --dumps
79              Dump  all known servers curvetun as a client can connect to, and
80              exit.
81
82       -D, --nofork
83              Do not fork off as a client or server on startup.
84
85       -s, --server
86              Start curvetun in server mode. Additional parameters are needed,
87              at  least the definition of the port that clients can connect to
88              is required.
89
90       -N, --no-logging
91              Disable all curvetun logging of user  information.  This  option
92              can  be  used  to  enable  curvetun users to connect more anony‐
93              mously. This option is for servers only.
94
95       -u, --udp
96              Use UDP as a carrier protocol instead of TCP. By default, TCP is
97              the carrier protocol. This option is for servers only.
98
99       -4, --ipv4
100              Defines  IPv4  as  the underlying network protocol to be used on
101              the tunnel device. IPv4 is  the  default.  This  option  is  for
102              servers only.
103
104       -6, --ipv6
105              Defines  IPv6  as  the underlying network protocol to be used on
106              the tunnel device. This option is for servers only.
107
108       -v, --version
109              Show version information and exit.
110
111       -h, --help
112              Show user help and exit.
113

USAGE EXAMPLE

115       curvetun --server -4 -u -N --port 6666 --stun stunserver.org
116              Starts curvetun in server mode with IPv4 as network protocol and
117              UDP as a transport carrier protocol. The curvetun server listens
118              for incoming connections on  port  6666  and  performs  an  STUN
119              lookup on startup to stunserver.org.
120
121       curvetun --client=ethz
122              Starts  curvetun in client mode and connects to the defined con‐
123              nection alias ''ethz'' that is defined in the curvetun ~/.curve‐
124              tun/servers configuration file.
125
126       curvetun --keygen
127              Generates  initial  keypairs and stores them in the ~/.curvetun/
128              directory.
129
130       curvetun --export
131              Export user data to  stdout  for  configuration  of  a  curvetun
132              server.
133

CRYPTOGRAPHY

135       Encrypted  IP tunnels are often used to create virtual private networks
136       (VPN), where parts of the network can only be reached via  an  insecure
137       or untrusted medium such as the Internet. Only a few software utilities
138       exist to create such tunnels, or, VPNs. Two popular representatives  of
139       such software are OpenVPN and VTUN.
140
141       The  latter  also introduced the TUN/TAP interfaces into the Linux ker‐
142       nel. VTUN only has a rather basic encryption module, that does not  fit
143       today's  cryptographic needs. By default, MD5 is used to create 128-Bit
144       wide keys for the symmetric BlowFish cipher in ECB mode [1].
145
146       Although OpenSSL is used in both VTUN and OpenVPN, OpenVPN is much more
147       feature  rich  regarding ciphers and user authentication. Nevertheless,
148       letting people choose ciphers or authentication methods is  not  neces‐
149       sarily  a  good  thing:  administrators  could either prefer speed over
150       security and therefore choose weak ciphers, so that  the  communication
151       system  will  be  as good as without any cipher; they could choose weak
152       passwords for symmetric encryption or they could misconfigure the  com‐
153       munication  system  by having too much choice of ciphers and too little
154       experience for picking the right one.
155
156       Next to the administration issues, there are also software  development
157       issues.   Cryptographic  libraries like OpenSSL are a huge mess and too
158       low-level and complex to fully understand or correctly apply,  so  that
159       they form further ground for vulnerabilities of such software.
160
161       In  2010,  the  cryptographers Tanja Lange and Daniel J. Bernstein have
162       therefore created and published a cryptographic library for networking,
163       which is named NaCl (pronounced ''salt''). NaCl addresses such problems
164       as mentioned in OpenSSL and, in contrast to the rather generic  use  of
165       OpenSSL,  was  created  with a strong focus on public-key authenticated
166       encryption based on elliptic  curve  cryptography,  which  is  used  in
167       curvetun. Partially quoting Daniel J.  Bernstein:
168
169       "RSA is somewhat older than elliptic-curve cryptography: RSA was intro‐
170       duced in 1977, while  elliptic-curve  cryptography  was  introduced  in
171       1985.  However,  RSA has shown many more weaknesses than elliptic-curve
172       cryptography. RSA's effective security level was  dramatically  reduced
173       by  the  linear sieve in the late 1970s, by the quadratic sieve and ECM
174       in the 1980s, and by the number-field sieve in the 1990s. For  compari‐
175       son,  a  few  attacks  have  been  developed against some rare elliptic
176       curves having special algebraic structures, and the amount of  computer
177       power  available  to  attackers  has predictably increased, but typical
178       elliptic curves require just as much computer power to break  today  as
179       they required twenty years ago.
180
181       IEEE  P1363 standardized elliptic-curve cryptography in the late 1990s,
182       including a stringent list of security criteria  for  elliptic  curves.
183       NIST  used  the IEEE P1363 criteria to select fifteen specific elliptic
184       curves at five different security levels. In 2005,  NSA  issued  a  new
185       ''Suite  B''  standard,  recommending  the NIST elliptic curves (at two
186       specific security levels) for all public-key cryptography and withdraw‐
187       ing previous recommendations of RSA."
188
189       curvetun  uses  a  particular elliptic curve, Curve25519, introduced in
190       the following paper: Daniel J.  Bernstein,  ''Curve25519:  new  Diffie-
191       Hellman  speed  records,''  pages  207-228  in Proceedings of PKC 2006,
192       edited by Moti Yung, Yevgeniy Dodis, Aggelos Kiayias, and  Tal  Malkin,
193       Lecture   Notes   in   Computer  Science  3958,  Springer,  2006,  ISBN
194       3-540-33851-9.
195
196       This elliptic curve follows all of the  standard  IEEE  P1363  security
197       criteria.   It  also  follows  new recommendations that achieve ''side-
198       channel immunity'' and ''twist security'' while improving  speed.  What
199       this  means  is that secure implementations of Curve25519 are consider‐
200       ably simpler and faster than secure implementations  of,  for  example,
201       NIST P-256; there are fewer opportunities for implementors to make mis‐
202       takes that compromise security, and mistakes are more easily caught  by
203       reviewers.
204
205       An  attacker  who  spends a billion dollars on special-purpose chips to
206       attack Curve25519, using the best attacks available today, has about  1
207       chance  in  1000000000000000000000000000 of breaking Curve25519 after a
208       year of computation.  One could achieve similar levels of security with
209       3000-bit  RSA,  but encryption and authentication with 3000-bit RSA are
210       not nearly fast enough to handle tunnel traffic and would require  much
211       more space in network packets.
212
213        1. Security analysis of VTun
214           http://www.off.net/~jme/vtun_secu.html
215
216        2. NaCl: Networking and Cryptography library
217           http://nacl.cr.yp.to/
218

SETUP HOWTO

220       If  you  have  not run curvetun before, you need to do an initial setup
221       once.
222
223       First, make sure that the servers and clients clocks  are  periodically
224       synced,  for  example,  by  running an NTP daemon. This is necessary to
225       protect against replay attacks. Also, make sure you have read and write
226       access  to  /dev/net/tun.  You  should  not run curvetun as root! Then,
227       after you have assured this, the first step is  to  generate  keys  and
228       config files. On both the client and server do:
229
230       curvetun -k
231
232       You are asked for a user name. You can use an email address or whatever
233       suits you. Here, we assume you have entered 'mysrv1' on the server  and
234       'myclient1' on the client side.
235
236       Now,  all  necessary  files  have been created under ~/.curvetun. Files
237       include “priv.key”, “pub.key”, “username”, “clients” and “servers”.
238
239       “clients” and “servers” are empty at  the  beginning  and  need  to  be
240       filled.  The  “clients”  file is meant for the server, so that it knows
241       what clients are allowed to connect. The  “servers”  file  is  for  the
242       client,  where it can select curvetun servers to connect to. Both files
243       are kept very simple, so that a single configuration line per client or
244       server is sufficient.
245
246       The client needs to export its public key data for the server
247
248       curvetun -x
249
250       where it prints a string in the following format:
251
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       \_____________________________________________________________________________________________/
255          username  32 byte public key for 'myclient1'
256
257       This line is transferred to the server admin (yes, we assume  a  manual
258       on-site  key  exchange  scenario  where, for example, the admin sets up
259       server and clients), where the admin then  adds  this  entry  into  his
260       ''clients'' file like:
261
262         server$                                                          echo
263       "myclient1;11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:" \
264                      "11:11:11:11:11:11:11:11:11:11:11:11:11:11:11"        >>
265       ~/.curvetun/clients
266
267       The  server admin can check if the server has registered it properly as
268       follows:
269
270         server$ curvetun -C
271
272       which prints all  parsed  clients  from  ''~/.curvetun/clients''.  This
273       process  could  easily be automated or scripted with, for example, Perl
274       and LDAP.
275
276       Now, the client ''myclient1'' is known to the  server;  that  completes
277       the  server configuration. The next step is to tell the client where it
278       needs to connect to the server.
279
280       We assume in this example that  the  tunnel  server  has  a  public  IP
281       address, e.g. 1.2.3.4, runs on port 6666 and uses UDP as a carrier pro‐
282       tocol. In case you are behind NAT, you can  use  curvetun's  ''--stun''
283       option  for  starting  the  server, to obtain your mapping. However, in
284       this example we continue with 1.2.3.4 and 6666, UDP.
285
286       First, the server needs to export its key to the client, as follows:
287
288         server$ curvetun -x
289
290       where it prints a string in the following format:
291
292         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
293         \____/
294       \_____________________________________________________________________________________________/
295        username  32 byte public key for 'mysrv1'
296                  ^-- you need this public key
297
298       Thus, you now have the server IP address, server port, server transport
299       protocol and the server's public key at hand. On the client side it can
300       be put all together in the config as follows:
301
302         client$                         echo                        "myfirst‐
303       server;1.2.3.4;6666;udp;22:22:22:22:22:22:22:22:22:22:" \
304                      "22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:"
305       \
306                      "22:22" >> ~/.curvetun/servers
307
308       The client can check its config using:
309
310         client$ curvetun -S
311
312       Then we start the server with:
313
314         server$ curvetun -s -p 6666 -u
315         server# ifconfig curves0 up
316         server# ifconfig curves0 10.0.0.1/24
317
318       Then, we start the client with:
319
320         client$ curvetun -c=myfirstserver
321         client# ifconfig curvec0 up
322         client# ifconfig curvec0 10.0.0.2/24
323
324       Also,  client-side information, errors, or warnings will appear in sys‐
325       log! By now we should be able to ping the server:
326
327         client$ ping 10.0.0.1
328
329       That's it! Routing example:
330
331       Server side's public IP on eth0 is, for example, 1.2.3.4:
332
333         server$ ... start curvetun server ...
334         server# ifconfig curves0 up
335         server# ifconfig curves0 10.0.0.1/24
336         server# echo 1 > /proc/sys/net/ipv4/ip_forward
337         server# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
338         server# iptables -A FORWARD -i  eth0  -o  curves0  -m  state  --state
339       RELATED,ESTABLISHED -j ACCEPT
340         server# iptables -A FORWARD -i curves0 -o eth0 -j ACCEPT
341
342       Client side's IP on eth0 is, for example, 5.6.7.8:
343
344         client$ ... start curvetun client ...
345         client#  ...  lookup  your  default  gateway  (e.g.  via route, here:
346       5.6.7.9) ...
347         client# ifconfig curvec0 up
348         client# ifconfig curvec0 10.0.0.2/24
349         client# route add -net 1.2.3.0 netmask 255.255.255.0 gw  5.6.7.9  dev
350       eth0
351         client# route add default gw 10.0.0.1
352         client# route del default gw 5.6.7.9
353
354       That should be it, happy browsing and emailing via curvetun tunnels!
355

NOTE

357       This software is an experimental prototype intended for researchers. It
358       will most likely mature over time, but it is currently not  advised  to
359       use this software when life is put at risk.
360

BUGS

362       Blackhole tunneling is currently not supported.
363
365       curvetun is licensed under the GNU GPL version 2.0.
366

HISTORY

368       curvetun  was  originally written for the netsniff-ng toolkit by Daniel
369       Borkmann. It is currently maintained by Tobias  Klauser  <tklauser@dis‐
370       tanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.
371

SEE ALSO

373       netsniff-ng(8),  trafgen(8),  mausezahn(8),  bpfc(8),  ifpps(8),  flow‐
374       top(8), astraceroute(8)
375

AUTHOR

377       Manpage was written by Daniel Borkmann.
378

COLOPHON

380       This page is part of the Linux netsniff-ng toolkit project. A  descrip‐
381       tion of the project, and information about reporting bugs, can be found
382       at http://netsniff-ng.org/.
383
384
385
386Linux                            03 March 2013                     CURVETUN(8)
Impressum