Merged PROTOCOL, NETWORK and SECURITY2 with the texinfo manual.

doc/tinc.texi

@@ -1,5 +1,5 @@
 \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
@@ -17,7 +17,7 @@ Copyright @copyright{} 1998-2001 Ivo Timmermans
 <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
@@ -42,7 +42,7 @@ Copyright @copyright{} 1998-2001 Ivo Timmermans
 <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
@@ -1336,28 +1336,29 @@ files are bound to be in a different directory.
 
 
 @menu
-* The Connection::
+* The connection::
+* The meta-protocol::
 * Security::
 @end menu
 
 
 @c ==================================================================
-@node    The Connection, Security, Technical information, Technical information
+@node    The connection, The meta-protocol, Technical information, Technical information
-@section The basic philosophy of the way tinc works
+@section The connection
-@cindex 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 UDP tunnel::
-* The Meta-connection::
+* The meta-connection::
 @end menu
 
 
 @c ==================================================================
-@node    Protocol Preview, The Meta-connection, The Connection, The Connection
+@node    The UDP tunnel, The meta-connection, The connection, The connection
-@subsection A preview of the way the tinc works
+@subsection The UDP tunnel
 
 @cindex ethertap
 @cindex frame type
@@ -1401,7 +1402,7 @@ set the MAC address of your tap interface to that address.
 
 
 @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
@@ -1433,8 +1434,105 @@ three ACKs sent instead of just one.  Furthermore, if there would be
 a timeout, both TCP streams would sense the timeout, and both would
 start re-sending packets.
 
+
 @c ==================================================================
-@node    Security,  , The Connection, Technical information
+@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 meta-protocol, Technical information
 @section About tinc's encryption and other security-related issues.
 
 @cindex TINC
@@ -1452,12 +1550,146 @@ tinc uses blowfish encryption in CBC mode and a small amount of salt
 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
+A new scheme for authentication in tinc has been devised, which offers some
-tinc daemons to connect. This is done by a challenge/response handshake
+improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is
-involving RSA encryption.
+below.
-The details of the authentication can be found in a file called @file{doc/SECURITY2}
+
-in the source of tinc.
+@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 ==================================================================