summaryrefslogtreecommitdiffstats
path: root/doc/source/devel/protocol.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/source/devel/protocol.rst')
-rw-r--r--doc/source/devel/protocol.rst73
1 files changed, 73 insertions, 0 deletions
diff --git a/doc/source/devel/protocol.rst b/doc/source/devel/protocol.rst
new file mode 100644
index 0000000..fdc5aa6
--- /dev/null
+++ b/doc/source/devel/protocol.rst
@@ -0,0 +1,73 @@
+Protocol specification
+======================
+
+Basic protocol design
+~~~~~~~~~~~~~~~~~~~~~
+fastd uses UDP as the transport protocol for its packets. UDP has been chosen
+instead of raw IP packets (as they are used by IPIP and 6in4 tunnels or IPsec)
+to simplify the deployment of multiple fastd instances on the same host using different
+UDP ports and allow passing through common NAT routers without explicit configuration.
+
+The first byte of the UDP payload is used to discern the different packet types
+used by fastd. For now only two values for the first byte have been defined:
+``0x01`` indicates a handshake packet, and ``0x02`` a data packet. All other
+values are reserved for future use and must be ignored by current implementations.
+
+Handshake format
+~~~~~~~~~~~~~~~~
+For historical reasons, all multi-byte values mentioned in the handshake specification are transmitted in Little Endian byte order
+unless specified otherwise.
+
+The initial ``0x01`` byte together with the next three bytes form the 4-byte handshake header; the rest of
+the packet after the header consists of a list of TLV records. The second header byte is reserved and must
+always be ``0x00``; the following two header bytes contain the length of the following TLV records in bytes
+encoded as Big Endian.
+
+The following TLV records start with a 2-byte type field, followed by a 2-byte length field and the
+arbitrary-length value. There is no special alignment defined for the TLV records.
+
+
+TLV record types
+----------------
+========== ============================= ========================== ===================================================================
+Record ID Value description Format Values
+========== ============================= ========================== ===================================================================
+``0x0000`` Handshake type 1-byte unsigned integer {1, 2, 3}
+``0x0001`` Reply code 1-byte unsigned integer {0 (success), 1 (mandatory record missing), 2 (unacceptable value)}
+``0x0002`` Error detail 1/2-byte unsigned integer Record type which caused an error
+``0x0003`` Flags (currently unused) variable-length bit field So far, no values are defined
+``0x0004`` Mode 1-byte unsigned integer {0 (TAP mode), 1 (TUN mode)}
+``0x0005`` Protocol name variable-length string "ec25519-fhmqvc"
+``0x0006`` Sender key 32-byte public key
+``0x0007`` Recipient key 32-byte public key
+``0x0008`` Sender handshake key 32-byte public key
+``0x0009`` Recipient handshake key 32-byte public key
+``0x000a`` Authentication tag (obsolete) 32-byte opaque value Not used if secure handshakes are enabled
+``0x000b`` MTU 2-byte unsigned integer
+``0x000c`` Method name variable-length string
+``0x000d`` Version name variable-length string
+``0x000e`` Method list zero-separated string list
+``0x000f`` TLV authentication tag 32-byte opaque value
+========== ============================= ========================== ===================================================================
+
+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
+
+Handshake request
+.................
+
+
+Handshake reply
+...............
+
+
+Handshake finish
+................
+
+
+Payload packets
+~~~~~~~~~~~~~~~