\input texinfo @c -*-texinfo-*-
-@c $Id: tinc.texi,v 1.8.4.16 2001/05/24 20:24:12 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.16 2001/05/24 20:24:12 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.16 2001/05/24 20:24:12 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
@example
mknod -m 600 /dev/tap0 c 36 16
chown 0.0 /dev/tap0
+mknod -m 600 /dev/tap1 c 36 17
+chown 0.0 /dev/tap0
+...
+mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16}
+chown 0.0 /dev/tap@emph{N}
@end example
-Any further ethertap devices have minor device number 16 through 31.
+There is a maximum of 16 ethertap devices.
If you use the universal TUN/TAP driver, you have to create the
-following device files (unless they already exist):
+following device file (unless it already exist):
@example
mknod -m 600 /dev/tun c 10 200
then the TUN/TAP device will probably be automatically generated as
@file{/dev/net/tun}.
+Unlike the ethertap device, you do not need multiple device files if
+you are planning to run multiple tinc daemons.
+
@c ==================================================================
@node Other files, , Device files, System files
out, remember to replace it with at least one space character.
In this section all valid variables are listed in alphabetical order.
-The default value is given between parentheses; required directives are
-given in @strong{bold}.
+The default value is given between parentheses,
+other comments are between square brackets and
+required directives are given in @strong{bold}.
@menu
* Main configuration variables::
make it even harder for crackers, even though it is thought to be nearly
impossible to crack a single key.
-@item ListenPort = <port> (655)
-@cindex ListenPort
-Listen on local port port. The computer connecting to this daemon should
-use this number as the argument for his ConnectPort.
-
@item @strong{Name = <name>}
@cindex Name
This is a symbolic name for this connection. It can be anything
-@item PingTimeout = <seconds> (5)
+@item PingTimeout = <seconds> (60)
@cindex PingTimeout
The number of seconds of inactivity that tinc will wait before sending a
probe to the other end. If that other end doesn't answer within that
same amount of seconds, the connection is terminated, and the others
will be notified of this.
-@item PrivateKey = <key> (obsolete)
+@item PrivateKey = <key> [obsolete]
@cindex PrivateKey
This is the RSA private key for tinc. However, for safety reasons it is
advised to store private keys of any kind in separate files. This prevents
accidental eavesdropping if you are editting the configuration file.
-@item @strong{PrivateKeyFile = <path>} (recommended)
+@item @strong{PrivateKeyFile = <path>} [recommended]
@cindex PrivateKeyFile
This is the full path name of the RSA private key file that was
generated by ``tincd --generate-keys''. It must be a full path, not a
relative directory.
-@item @strong{TapDevice = <device>} (/dev/tap0)
+@item @strong{TapDevice = <device>} (/dev/tap0 or /dev/net/tun)
@cindex TapDevice
The ethertap device to use. Note that you can only use one device per
daemon. The info pages of the tinc package contain more information
about configuring an ethertap device for Linux.
-@item TCPonly = <yes|no> (no, experimental)
-@cindex TCPonly
-If this variable is set to yes, then the packets are tunnelled over a TCP
-connection instead of a UDP connection. This is especially useful for those
-who want to run a tinc daemon from behind a masquerading firewall, or if
-UDP packet routing is disabled somehow. This is experimental code,
-try this at your own risk.
@end table
@subsection Host configuration variables
@table @asis
-@item @strong{Address = <IP address|hostname>}
+@item @strong{Address = <IP address|hostname>} [recommended]
@cindex Address
This variable is only required if you want to connect to this host. It
must resolve to the external IP address where the host can be reached,
not the one that is internal to the VPN.
-@item IndirectData = <yes|no> (no, experimental)
+@item IndirectData = <yes|no> (no) [experimental]
@cindex IndirectData
This option specifies whether other tinc daemons besides the one you
specified with ConnectTo can make a direct connection to you. This is
by a single zero) o hexadecimal (prefixed with 0x). port is the port
number for both the UDP and the TCP (meta) connections.
-@item PublicKey = <key> (obsolete)
+@item PublicKey = <key> [obsolete]
@cindex PublicKey
This is the RSA public key for this host.
-@item PublicKeyFile = <path> (obsolete)
+@item PublicKeyFile = <path> [obsolete]
@cindex PublicKeyFile
This is the full path name of the RSA public key file that was generated
by ``tincd --generate-keys''. It must be a full path, not a relative
/22. This conforms to standard CIDR notation as described in
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
-@item TCPonly = <yes|no> (no, experimental)
+@item TCPonly = <yes|no> (no) [experimental]
@cindex TCPonly
If this variable is set to yes, then the packets are tunnelled over a
TCP connection instead of a UDP connection. This is especially useful
for those who want to run a tinc daemon from behind a masquerading
firewall, or if UDP packet routing is disabled somehow. This is
experimental code, try this at your own risk. It may not work at all.
+Setting this options also implicitly sets IndirectData.
@end table
@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 / tinc / blobdiff