summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/source/crypto/ec25519.rst2
-rw-r--r--doc/source/crypto/fhmqvc.rst4
-rw-r--r--doc/source/devel/protocol.rst60
-rw-r--r--doc/source/index.rst3
4 files changed, 68 insertions, 1 deletions
diff --git a/doc/source/crypto/ec25519.rst b/doc/source/crypto/ec25519.rst
new file mode 100644
index 0000000..5998777
--- /dev/null
+++ b/doc/source/crypto/ec25519.rst
@@ -0,0 +1,2 @@
+ec25519
+=======
diff --git a/doc/source/crypto/fhmqvc.rst b/doc/source/crypto/fhmqvc.rst
new file mode 100644
index 0000000..b82c817
--- /dev/null
+++ b/doc/source/crypto/fhmqvc.rst
@@ -0,0 +1,4 @@
+FHMQV-C
+=======
+
+
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.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3593481..a53c0ed 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,6 +19,9 @@ Cryptographic algorithms
.. toctree::
:maxdepth: 2
+ crypto/ec25519
+ crypto/fhmqvc
+
Developer documentation
-----------------------