docs: todo: shorten todo entry, thanks to Jon

[netsniff-ng.git] / Documentation / Curvetun

What is curvetun?
/////////////////

curvetun is a lightweight, high-speed ECDH multiuser IP tunnel for Linux
that is based on epoll(2). curvetun uses the Linux TUN/TAP interface and
supports {IPv4,IPv6} over {IPv4,IPv6} with UDP or TCP as carrier protocols.
It has an integrated packet forwarding trie, thus multiple users with
different IPs can be handled via a single tunnel device on the server side
and flows are scheduled for processing in a CPU-local manner. As an appropriate
key management, public-key cryptography based on elliptic curves are being
used and packets are encrypted end-to-end by a symmetric stream cipher (Salsa20)
and authenticated by a MAC (Poly1305), where keys have previously been computed
with the ECDH key agreement protocol (Curve25519). Cryptography is based on
Daniel J. Bernsteins Networking and Cryptography library (NaCl). By design,
curvetun does not provide any particular pattern or default port numbers
that gives certainty that the software from a particular packet stream is
actually curvetun. However, if you have further needs to bypass censorship,
you can try using curvetun in combination with Tor's obfsproxy [1] [2].
Furthermore, curvetun also protects you against replay attacks and DH man
in the mittle. Optionally, server event logging can be disabled.

[1] https://www.torproject.org/projects/obfsproxy.html.en
[2] git clone git://git.torproject.org/obfsproxy.git

Motivation
//////////

IP tunnels are usually used to create virtual private networks (VPN), where
parts of the network can only be reached via an unsecure or untrusted underlay
network like the Internet. Only few software exists to create such tunnels,
or, VPNs. Two popular representatives of such software are OpenVPN and VTUN.
The latter also introduced the TUN/TAP interfaces into the Linux kernel.
VTUN only has a rather basic encryption module, that doesn't fit into todays
cryptographic needs. By default MD5 is used to create 128-Bit wide keys for
the symmetric BlowFish cipher in ECB mode [1]. Although OpenSSL is used in both,
VTUN and OpenVPN, OpenVPN is much more feature rich regarding ciphers and user
authentication. Nevertheless, letting people choose ciphers or authentication
methods does not necessarily mean a good thing: administrators could either
prefer speed over security and therefore choose weak ciphers, so that the
communication system will be as good as without any cipher, they could choose
weak passwords for symmetric encryption or they could misconfigure the
communication system by having too much choices of ciphers and too little
experience for picking the right one. Next to the administration issues,
there are also software development issues. Cryptographic libraries like
OpenSSL are too low-level and too complex to fully understand or correctly
apply, so that they form a further ground for vulnerabilities of such software.
In 2010, the famous cryptographers Tanja Lange and Daniel J. Bernstein have
therefore created and published a cryptography library for networking, which
is called NaCl (pronounced 'salt'). NaCl challenges such addressed problems
as in OpenSSL and, in contrast to the rather generic use of OpenSSL, was
created with a strong focus on public-key authenticated encryption based on
elliptic curve cryptography, which is used in curvetun.

[1] http://www.off.net/~jme/vtun_secu.html

Elliptic-curve cryptography and Curve25519
//////////////////////////////////////////

From http://dnscurve.org/crypto.html:

RSA is somewhat older than elliptic-curve cryptography: RSA was introduced
in 1977, while elliptic-curve cryptography was introduced in 1985. However,
RSA has shown many more weaknesses than elliptic-curve cryptography. RSA's
effective security level was dramatically reduced by the linear sieve in the
late 1970s, by the quadratic sieve and ECM in the 1980s, and by the
number-field sieve in the 1990s. For comparison, a few attacks have been
developed against some rare elliptic curves having special algebraic
structures, and the amount of computer power available to attackers has
predictably increased, but typical elliptic curves require just as much
computer power to break today as they required twenty years ago.

IEEE P1363 standardized elliptic-curve cryptography in the late 1990s,
including a stringent list of security criteria for elliptic curves. NIST
used the IEEE P1363 criteria to select fifteen specific elliptic curves at
five different security levels. In 2005, NSA issued a new "Suite B"
standard, recommending the NIST elliptic curves (at two specific security
levels) for all public-key cryptography and withdrawing previous
recommendations of RSA.

[curvetun] uses a particular elliptic curve, Curve25519, introduced in the
following paper: Daniel J. Bernstein, "Curve25519: new Diffie–Hellman speed
records," pages 207–228 in Proceedings of PKC 2006, edited by Moti Yung,
Yevgeniy Dodis, Aggelos Kiayias, and Tal Malkin, Lecture Notes in Computer
Science 3958, Springer, 2006, ISBN 3-540-33851-9.

This elliptic curve follows all of the standard IEEE P1363 security criteria.
It also follows new recommendations that achieve "side-channel immunity"
and "twist security" while improving speed. What this means is that secure
implementations of Curve25519 are considerably simpler and faster than secure
implementations of (e.g.) NIST P-256; there are fewer opportunities for
implementors to make mistakes that compromise security, and mistakes are
more easily caught by reviewers.

An attacker who spends a billion dollars on special-purpose chips to attack
Curve25519, using the best attacks available today, has about 1 chance in
1000000000000000000000000000 of breaking Curve25519 after a year of computation.
One could achieve similar levels of security with 3000-bit RSA, but
encryption and authentication with 3000-bit RSA are not nearly fast enough
to handle [tunnel traffic] and would require much more space in [network]
packets.

More can be found here: http://cr.yp.to/highspeed/naclcrypto-20090310.pdf

Using the curvetun tunnel for browsing the web (example howto):
///////////////////////////////////////////////////////////////

curvetun inital setup example:

If you've never run curvetun before, you need to do an initial setup once.

At first, make sure that the servers and clients clocks are periodically
synced, i.e. with ntpdate ntp.ubuntu.com pool.ntp.org as a cronjob or simply
install the ntp daemon. This is necessary to protect against replay attacks.

Also, make sure if you have read/write access to /dev/net/tun. You should not
run curvetun as root!

Then, the first step is to create keys and config files. On both, the client
and server do:

$ curvetun -k

You are asked for a username. You can use an email address or whatever. Here,
we assume, you've entered 'mysrv1' on the server and 'myclient1' on the client
side.

Now on the necessary file have been created:
        ~/.curvetun/priv.key   - Your private key
        ~/.curvetun/pub.key    - Your public key
        ~/.curvetun/username   - Your username (here: mysrv1 or myclient1)
        ~/.curvetun/clients    - Participants the server accepts
        ~/.curvetun/servers    - Possible servers the client can connect to

'clients' and 'servers' are empty at the beginning and need to be filled now.
The 'clients' file is meant for the server, so that it knows what clients
may connect. The 'servers' file is for the client, where it can select
curvetun servers to connect to.

Now the client exports it's public key for the server:

client$ curvetun -x

... where it prints sth like:

  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
  \_______/ \_____________________________________________________________________________________________/
   username  32 byte public key for 'myclient1'

This line is transferred to the server admin, where the admin add this entry
into his 'clients' file like:

server$ echo "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" >> ~/.curvetun/clients

The server admin can check, if the server has registered it properly by ...

server$ curvetun -C

... which prints all parsed clients from ~/.curvetun/clients.

[Note: in src/ there is also a Perl script curvetun_ldap.pl that can generate
 a client file from LDAP entries!]

Now, the client 'myclient1' is known to the server; that's it for the server
config. The next step is to tell the client what he needs to connect to the
server.

We hereby assume, the tunnel server has an public IP i.e. 1.2.3.4, runs on
port 6666 and uses UDP as a carrier protocol. In case you are behind a NAT,
you can use curvetun's --stun option for starting the server, to obtain your
mapping. However, in this example we continue with 1.2.3.4 and 6666, UDP.

First, the server needs to export its key to the client, as:

server$ curvetun -x

... where it prints sth like:

  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
  \____/ \_____________________________________________________________________________________________/
 username  32 byte public key for 'mysrv1'
           ^-- you need this public key

Now, you give the client your connection information:
   * IP 1.2.3.4
   * Port 6666
   * Proto UDP
   * Pubkey 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

... and the client puts it all together in its config like:

client$ echo "myfirstserver;1.2.3.4;6666;udp;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" >> ~/.curvetun/servers

... again, where he can check his config with:

client$ curvetun -S

Okay, assuming we've made it, then we start the server with:

server$ curvetun -s -p 6666 -u
server# ifconfig curves0 up
server# ifconfig curves0 10.0.0.1/24

Server-side information, errors or warnings will appear in syslog!

Then, we start the client with ...

client$ curvetun -c=myfirstserver
client# ifconfig curvec0 up
client# ifconfig curvec0 10.0.0.2/24

Also, client-side information, errors or warnings will appear in syslog!
... and we're now able to ping the server:

client$ ping 10.0.0.1

That's it!

IPv4 routing example:

Server side: your public IP on eth0 is i.e. 1.2.3.4

server$ ... start curvetun server ...
server# ifconfig curves0 up
server# ifconfig curves0 10.0.0.1/24
server# echo 1 > /proc/sys/net/ipv4/ip_forward
server# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
server# iptables -A FORWARD -i eth0 -o curves0 -m state --state RELATED,ESTABLISHED -j ACCEPT
server# iptables -A FORWARD -i curves0 -o eth0 -j ACCEPT

Client side: your IP on eth0 is i.e. 5.6.7.8

client$ ... start curvetun client ...
client# ... lookup your default gateway ...
         -> either stated in route, or
         -> traceroute google.ch and take the first IP entry
         -> default gw here i.e. 5.6.7.9
client# ifconfig curvec0 up
client# ifconfig curvec0 10.0.0.2/24
client# route add -net 1.2.3.0 netmask 255.255.255.0 gw 5.6.7.9 dev eth0
client# route add default gw 10.0.0.1
client# route del default gw 5.6.7.9

... and there you go, now open your browser on the client side and surf the
web or do whatever you want. For instance, with curvetun we were able to watch
Youtube videos in FullHD without problems. All your traffic will then be
tunneled encrypted to your server.