summaryrefslogtreecommitdiffstats
path: root/doc/source/devel
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2014-10-26 16:56:43 +0100
committerMatthias Schiffer <mschiffer@universe-factory.net>2014-10-26 16:56:43 +0100
commit7e5ffc0cde38c27ce59ec8432c3cc8936050c4a9 (patch)
tree297d5176427e02384a9cef251af1a354fa1d655e /doc/source/devel
parent6359772b9cf6e8b9ffee1ca98413675a4357616f (diff)
downloadfastd-7e5ffc0cde38c27ce59ec8432c3cc8936050c4a9.tar
fastd-7e5ffc0cde38c27ce59ec8432c3cc8936050c4a9.zip
docs: handshake documentation
Diffstat (limited to 'doc/source/devel')
-rw-r--r--doc/source/devel/protocol.rst60
1 files changed, 59 insertions, 1 deletions
diff --git a/doc/source/devel/protocol.rst b/doc/source/devel/protocol.rst
index fdc5aa6..b3b40f3 100644
--- a/doc/source/devel/protocol.rst
+++ b/doc/source/devel/protocol.rst
@@ -55,19 +55,77 @@ Handshake protocol
The following specification describes the current handshake as it is performed by fastd versions
since v11 when secure handshakes are enabled.
-The handshake protocol consists of three packets. See also: FHMQV-C
+The handshake protocol consists of three packets. See also: :doc:`/crypto/ec25519`, :doc:`/crypto/fhmqvc`
+
+The following fields are sent in all three packets as different fastd versions expect them in
+different parts of the handshake:
+
+* Mode (TUN/TAP)
+* MTU
+* fastd version (e.g. ``v15``)
+* Protocol name (``ec25519-fhmqvc``)
Handshake request
.................
+The first packet of a handshake contains the following additional fields:
+
+* Handshake type (0x01)
+* FHMQV-C values:
+ - Sender key :math:`\hat{A}`
+ - Recipient key :math:`\hat{B}`
+ - Sender handshake key :math:`X`
+
+The recipient key may be omitted if the recipient identity is unknown because the handshake was triggered by an unexpected data packet.
Handshake reply
...............
+The second packet of a handshake contains the following additional fields:
+
+* Handshake type (0x02)
+* Reply code (0x00)
+* Method list (list of all supported methods)
+* FHMQV-C values:
+ - Sender key :math:`\hat{B}`
+ - Recipient key :math:`\hat{A}`
+ - Sender handshake key :math:`Y`
+ - Recipient handshake key :math:`X`
+ - TLV authentication tag :math:`\text{MAC}_B`
Handshake finish
................
+The second packet of a handshake contains the following additional fields:
+
+* Handshake type (0x03)
+* Reply code (0x00)
+* Method (the chosen encryption/authentication scheme)
+* FHMQV-C values:
+ - Sender key :math:`\hat{A}`
+ - Recipient key :math:`\hat{B}`
+ - Sender handshake key :math:`X`
+ - Recipient handshake key :math:`Y`
+ - TLV authentication tag :math:`\text{MAC}_A`
+
+Handshake error
+...............
+When an unacceptable handshake is received, fastd will respond with an error packet. The error packet contains the following fields:
+
+* Handshake type (the type of the packet that is answered plus 1)
+* Reply code (0x01 when a record is missing from the handshake,
+ 0x02 when a value is unacceptable)
+* Error detail (the record type ID which caused the error)
Payload packets
~~~~~~~~~~~~~~~
+The payload packet structure is defined by the methods; at the moment most methods use the same format, starting with a 24 byte header, followed by the actual payload:
+
+* Byte 1: Packet type (0x02)
+* Byte 2: Flags (method-specific; unused, always 0x00)
+* Bytes 3-8: Packet sequence number/nonce (big endian; incremented by 2 for each packet; one side of a connection uses the even sequence numbers and the other side the odd ones)
+* Bytes 9-24: Authentication tag (method-specific)
+
+The ``null`` method uses only a 1 byte header: The packet type is directly followed by the payload data.
+
+In the legacy ``xsalsa20-poly1305`` method, the flag and nonce fields are reversed and the nonce is in little endian for compatiblity reasons.