From 04307338380c20b5fae68bf81efde40f81f9f0ae Mon Sep 17 00:00:00 2001
From: Martin Sustrik <sustrik@anapaya.net>
Date: Fri, 11 Sep 2020 10:04:39 +0200
Subject: [PATCH] [doc] BFD/SCION protocol specification

---
 doc/protocols/bfd.rst          | 75 ++++++++++++++++++++++++++++++++++
 doc/protocols/index.rst        |  1 +
 doc/protocols/scion-header.rst | 11 ++++-
 3 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100644 doc/protocols/bfd.rst

diff --git a/doc/protocols/bfd.rst b/doc/protocols/bfd.rst
new file mode 100644
index 0000000000..d6b8e67626
--- /dev/null
+++ b/doc/protocols/bfd.rst
@@ -0,0 +1,75 @@
+*******************
+BFD on top of SCION
+*******************
+
+BFD (Bidirectional Forwarding Detection) is a network protocol that is used to
+detect faults between two forwarding engines connected by a link. (See `rfc5880
+<https://tools.ietf.org/html/rfc5880>`__ and `rfc5881
+<https://tools.ietf.org/html/rfc5881>`__.)
+
+BFD can be layered on top of different transport protocols. This document
+describes how BFD should be layered on top of SCION.
+
+The Protocol
+============
+
+BFD packets, as they are described in the relevant RFCs, should be placed
+directly into SCION payload, with no additional intermediate protocol::
+
+    +----------------------+
+    | SCION common header  |
+    +----------------------+
+    | SCION address header |
+    +----------------------+
+    |  SCION path header   |
+    +----------------------+
+    |         BFD          |
+    +----------------------+
+
+The `NextHdr` field in the SCION common header must be set to type `BFD` (17).
+
+BFD in SCION Router
+===================
+
+Discriminators
+--------------
+
+SCION router should choose its discriminators for BFD sessions at random.
+
+Bootstrapping
+-------------
+
+BFD bootstrapping process (that is, how incoming BFD packet with `Your Discriminator`
+field equal to zero is mapped to a BFD session) is to be defined by each
+particular application.
+
+SCION router, in particular, does bootstrapping in the following way.
+
+It creates one "external" BFD session for each SCION
+interface that it owns. Its BFD peer is the SCION router in the neighbouring
+AS. The associated BFD packets must use SCION `OneHopPath
+<https://scion.docs.anapaya.net/en/latest/protocols/scion-header.html#path-type-onehoppath>`__
+type.
+
+This kind of BFD session in unambiguously identified by the ID of the SCION interface the
+packet was received on.
+
+Furthermore, SCION router creates one "internal" BFD session for every
+other SCION router instance within the same AS. The associated BFD packets must use SCION
+`Empty
+<https://scion.docs.anapaya.net/en/latest/protocols/scion-header.html#path-type-empty>`__
+path type.
+
+These BFD sessions are uniquely identified by the source address, as it appears
+in the SCION address header.
+
+Any other BFD packets (e.g. packets with standard SCION path) are invalid and
+must be dropped by the SCION router.
+
+Caveats
+=======
+
+Note that there is no UDP header, and therefore no ports in BFD/SCION protocol.
+
+The consequence is that there can't be two SCION/BFD-enabled applications (e.g.
+two SCION router instances) sharing the same IP address.
diff --git a/doc/protocols/index.rst b/doc/protocols/index.rst
index dc6f6ecd60..135813639c 100644
--- a/doc/protocols/index.rst
+++ b/doc/protocols/index.rst
@@ -11,3 +11,4 @@ This page contains SCION control and data plane protocols and specifications.
    extension-header
    scmp
    sig
+   bfd
diff --git a/doc/protocols/scion-header.rst b/doc/protocols/scion-header.rst
index f908cfd928..f14c431602 100644
--- a/doc/protocols/scion-header.rst
+++ b/doc/protocols/scion-header.rst
@@ -55,8 +55,9 @@ PayloadLen
 PathType
     The PathType specifies the SCION path type with up to 256 different types.
     The format of each path type is independent of each other. The initially
-    proposed SCION path types are SCION (0), OneHopPath (1), EPIC (2) and
-    COLIBRI (3). Here, we only specify the SCION and OneHopPath path types.
+    proposed SCION path types are Empty (0), SCION (1), OneHopPath (2), EPIC (3)
+    and COLIBRI (4). Here, we only specify the Empty, SCION and OneHopPath path
+    types.
 DT/DL/ST/SL
     DT/ST and DL/SL encode host-address type and host-address length,
     respectively, for destination/ source. The possible host address length
@@ -404,6 +405,12 @@ In construction direction (down):
    #. Check that the MAC in the hop field matches :math:`{\sigma^P_i}'`.
    #. Do not update `SegID` as it already contains :math:`\beta_{i+1}`.
 
+Path Type: EmptyPath
+====================
+
+Empty path is used to send traffic within the AS. It has no additional fields,
+i.e., it consumes 0 bytes on the wire.
+
 Path Type: OneHopPath
 =====================