diff options
Diffstat (limited to 'doc/source/devel/protocol.rst')
| -rw-r--r-- | doc/source/devel/protocol.rst | 73 |
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 +~~~~~~~~~~~~~~~ |