\input texinfo @c -*-texinfo-*-
-@c $Id: tinc.texi,v 1.8.4.17 2001/05/25 10:06:13 guus Exp $
+@c $Id: tinc.texi,v 1.8.4.18 2001/05/25 12:45:37 guus Exp $
@c %**start of header
@setfilename tinc.info
@settitle tinc Manual
<itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
Wessel Dankers <wsl@@nl.linux.org>.
-$Id: tinc.texi,v 1.8.4.17 2001/05/25 10:06:13 guus Exp $
+$Id: tinc.texi,v 1.8.4.18 2001/05/25 12:45:37 guus Exp $
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
<itimmermans@@bigfoot.com>, Guus Sliepen <guus@@sliepen.warande.net> and
Wessel Dankers <wsl@@nl.linux.org>.
-$Id: tinc.texi,v 1.8.4.17 2001/05/25 10:06:13 guus Exp $
+$Id: tinc.texi,v 1.8.4.18 2001/05/25 12:45:37 guus Exp $
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
@menu
-* The Connection::
+* The connection::
+* The meta-protocol::
* Security::
@end menu
@c ==================================================================
-@node The Connection, Security, Technical information, Technical information
-@section The basic philosophy of the way tinc works
-@cindex connection
+@node The connection, The meta-protocol, Technical information, Technical information
+@section The connection
+@cindex connection
tinc is a daemon that takes VPN data and transmit that to another host
computer over the existing Internet infrastructure.
@menu
-* Protocol Preview::
-* The Meta-connection::
+* The UDP tunnel::
+* The meta-connection::
@end menu
@c ==================================================================
-@node Protocol Preview, The Meta-connection, The Connection, The Connection
-@subsection A preview of the way the tinc works
+@node The UDP tunnel, The meta-connection, The connection, The connection
+@subsection The UDP tunnel
@cindex ethertap
@cindex frame type
@c ==================================================================
-@node The Meta-connection, , Protocol Preview, The Connection
+@node The meta-connection, , The UDP tunnel, The connection
@subsection The meta-connection
Having only an UDP connection available is not enough. Though suitable
a timeout, both TCP streams would sense the timeout, and both would
start re-sending packets.
+
+@c ==================================================================
+@node The meta-protocol, Security, The connection, Technical information
+@section The meta-protocol
+
+The meta protocol is used to tie all tinc daemons together, and
+exchange information about which tinc daemon serves which virtual
+subnet.
+
+The meta protocol consists of requests that can be sent to the other
+side. Each request has a unique number and several parameters. All
+requests are represented in the standard ASCII character set. It is
+possible to use tools such as telnet or netcat to connect to a tinc
+daemon and to read and write requests by hand, provided that one
+understands the numeric codes sent.
+
+The authentication scheme is described in @ref{Authentication protocol}. After a
+succesful authentication, the server and the client will exchange all the
+information about other tinc daemons and subnets they know of, so that both
+sides (and all the other tinc daemons behind them) have their information
+synchronised.
+
+@cindex ADD_HOST
+@cindex ADD_SUBNET
+@example
+daemon message
+--------------------------------------------------------------------------
+origin ADD_HOST daemon a329e18c:655 0
+ | | +--> options
+ | +---------> real address:port
+ +-------------------> name of new tinc daemon
+origin ADD_SUBNET daemon 1,0a010100/ffffff00
+ | | | +--> netmask
+ | | +----------> vpn IPv4 network address
+ | +----------------> subnet type (1=IPv4)
+ +--------------------> owner of this subnet
+--------------------------------------------------------------------------
+@end example
+
+@cindex DEL_HOST
+@cindex DEL_SUBNET
+In case daemons leave the VPN, DEL_HOST and DEL_SUBNET messages with exactly
+the same syntax are sent to inform the other daemons of the departure.
+
+The keys used to encrypt VPN packets are not sent out directly. This is
+because it would generate a lot of traffic on VPNs with many daemons, and
+chances are that not every tinc daemon will ever send a packet to every
+other daemon. Instead, if a daemon needs a key it sends a request for it
+via the meta connection of the nearest hop in the direction of the
+destination. If any hop on the way has already learned the key, it will
+act as a proxy and forward it's copy back to the requestor.
+
+@cindex REQ_KEY
+@cindex ANS_KEY
+@cindex KEY_CHANGED
+@example
+daemon message
+--------------------------------------------------------------------------
+daemon REQ_KEY origin destination
+ | +--> name of the tinc daemon it wants the key from
+ +----------> name of the daemon that wants the key
+daemon ANS_KEY origin destination e4ae0b0a82d6e0078179b5290c62c7d0
+ | | \______________________________/
+ | | +--> 128 bits key
+ | +--> name of the daemon that wants the key
+ +----------> name of the daemon that uses this key
+daemon KEY_CHANGED origin
+ +--> daemon that has changed it's packet key
+--------------------------------------------------------------------------
+@end example
+
+There is also a mechanism to check if hosts are still alive. Since network
+failures or a crash can cause a daemon to be killed without properly
+shutting down the TCP connection, this is necessary to keep an up to date
+connection list. PINGs are sent at regular intervals, except when there
+is also some other traffic. A little bit of salt (random data) is added
+with each PING and PONG message, to make sure that long sequences of PING/PONG
+messages without any other traffic won't result in known plaintext.
+
+@cindex PING
+@cindex PONG
+@example
+daemon message
+--------------------------------------------------------------------------
+origin PING 9e76
+ \__/
+ +--> 2 bytes of salt (random data)
+dest. PONG 3b8d
+ \__/
+ +--> 2 bytes of salt (random data)
+--------------------------------------------------------------------------
+@end example
+
+This basically covers what is sent over the meta connection by
+tinc.
+
+
@c ==================================================================
-@node Security, , The Connection, Technical information
+@node Security, , The meta-protocol, Technical information
@section About tinc's encryption and other security-related issues.
@cindex TINC
at the beginning of each packet to make sure eavesdroppers cannot get
any information at all from the packets they can intercept.
+@menu
+* Authentication protocol::
+* Encryption of network packets::
+@end menu
+
+
+@c ==================================================================
+@node Authentication protocol, Encryption of network packets, Security, Security
+@subsection Authentication protocol
+
@cindex authentication
-Another important part is the authentication done prior to allowing other
-tinc daemons to connect. This is done by a challenge/response handshake
-involving RSA encryption.
-The details of the authentication can be found in a file called @file{doc/SECURITY2}
-in the source of tinc.
+A new scheme for authentication in tinc has been devised, which offers some
+improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is
+below.
+
+@example
+daemon message
+--------------------------------------------------------------------------
+client <attempts connection>
+
+server <accepts connection>
+
+client ID client 10 0
+ | | +-> options
+ | +---> version
+ +--------> name of tinc daemon
+
+server ID server 10 0
+ | | +-> options
+ | +---> version
+ +--------> name of tinc daemon
+
+client META_KEY 5f0823a93e35b69e...7086ec7866ce582b
+ \_________________________________/
+ +-> RSAKEYLEN bits totally random string S1,
+ encrypted with server's public RSA key
+
+server META_KEY 6ab9c1640388f8f0...45d1a07f8a672630
+ \_________________________________/
+ +-> RSAKEYLEN bits totally random string S2,
+ encrypted with client's public RSA key
+
+From now on:
+ - the client will encrypt outgoing traffic using S1
+ - the server will encrypt outgoing traffic using S2
+
+client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0
+ \_________________________________/
+ +-> CHALLEN bits totally random string H1
+
+server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f
+ \_________________________________/
+ +-> CHALLEN bits totally random string H2
+
+client CHAL_REPLY 816a86
+ +-> 160 bits SHA1 of H2
+
+server CHAL_REPLY 928ffe
+ +-> 160 bits SHA1 of H1
+--------------------------------------------------------------------------
+@end example
+
+This new scheme has several improvements, both in efficiency and security.
+
+First of all, the server sends exactly the same kind of messages over the wire
+as the client. The previous versions of tinc first authenticated the client,
+and then the server. This scheme even allows both sides to send their messages
+simultaneously, there is no need to wait for the other to send something first.
+This means that any calculations that need to be done upon sending or receiving
+a message can also be done in parallel. This is especially important when doing
+RSA encryption/decryption. Given that these calculations are the main part of
+the CPU time spent for the authentication, speed is improved by a factor 2.
+
+Second, only one RSA encrypted message is sent instead of two. This reduces the
+amount of information attackers can see (and thus use for a cryptographic
+attack). It also improves speed by a factor two, making the total speedup a
+factor 4.
+
+Third, and most important:
+The symmetric cipher keys are exchanged first, the challenge is done
+afterwards. In the previous authentication scheme, because a man-in-the-middle
+could pass the challenge/chal_reply phase (by just copying the messages between
+the two real tinc daemons), but no information was exchanged that was really
+needed to read the rest of the messages, the challenge/chal_reply phase was of
+no real use. The man-in-the-middle was only stopped by the fact that only after
+the ACK messages were encrypted with the symmetric cipher. Potentially, it
+could even send it's own symmetric key to the server (if it knew the server's
+public key) and read some of the metadata the server would send it (it was
+impossible for the mitm to read actual network packets though). The new scheme
+however prevents this.
+
+This new scheme makes sure that first of all, symmetric keys are exchanged. The
+rest of the messages are then encrypted with the symmetric cipher. Then, each
+side can only read received messages if they have their private key. The
+challenge is there to let the other side know that the private key is really
+known, because a challenge reply can only be sent back if the challenge is
+decrypted correctly, and that can only be done with knowledge of the private
+key.
+
+Fourth: the first thing that is send via the symmetric cipher encrypted
+connection is a totally random string, so that there is no known plaintext (for
+an attacker) in the beginning of the encrypted stream.
+
+
+@c ==================================================================
+@node Encryption of network packets, , Authentication protocol, Security
+@subsection Encryption of network packet
+@cindex encryption
+
+A data packet can only be sent if the encryption key is known to both
+parties, and the connection is activated. If the encryption key is not
+known, a request is sent to the destination using the meta connection
+to retreive it. The packet is stored in a queue while waiting for the
+key to arrive.
+
+@cindex UDP
+The UDP packet containing the network packet from the VPN has the following layout:
+
+@example
+... | IP header | UDP header | salt | VPN packet | UDP trailer
+ \___________________/
+ |
+ V
+ Encrypted with symmetric cipher
+@end example
+
+So, the entire UDP payload is encrypted using a symmetric cipher (blowfish in CBC mode).
+2 bytes of salt (random data) are added in front of the actual VPN packet,
+so that two VPN packets with (almost) the same content do not seem to be
+the same for eavesdroppers.
+2 bytes of salt may not seem much, but you can encrypt 65536 identical packets
+now without an attacker being able to see that they were identical.
+Given a MTU of 1500 this means 96 Megabyte of data.
+
+There is no @emph{extra} provision against replay attacks or alteration of packets.
+However, the VPN packets, normally UDP or TCP packets themselves, contain
+checksums and sequence numbers.
+Since those checksums and sequence numbers are encrypted,
+they automatically become @emph{cryptographically secure}.
+The kernel will handle any checksum errors and duplicate packets.
@c ==================================================================
projects / oweals / tinc.git / commitdiff