bfdd/bfddp_packet.h

   1 /*
   2  * BFD Data Plane protocol messages header.
   3  *
   4  * Copyright (C) 2020 Network Device Education Foundation, Inc. ("NetDEF")
   5  *                    Rafael F. Zalamena
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the “Software”), to
   9  * deal in the Software without restriction, including without limitation the
  10  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  11  * sell copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  22  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  23  * IN THE SOFTWARE.
  24  */
  25
  26 /**
  27  * \file bfddp_packet.h
  28  */
  29 #ifndef BFD_DP_PACKET_H
  30 #define BFD_DP_PACKET_H
  31
  32 #include <netinet/in.h>
  33
  34 #include <stdint.h>
  35
  36 /*
  37  * Protocol definitions.
  38  */
  39
  40 /**
  41  * BFD protocol version as defined in RFC5880 Section 4.1 Generic BFD Control
  42  * Packet Format.
  43  */
  44 #define BFD_PROTOCOL_VERSION 1
  45
  46 /** Default data plane port. */
  47 #define BFD_DATA_PLANE_DEFAULT_PORT 50700
  48
  49 /** BFD single hop UDP port, as defined in RFC 5881 Section 4. Encapsulation. */
  50 #define BFD_SINGLE_HOP_PORT 3784
  51
  52 /** BFD multi hop UDP port, as defined in RFC 5883 Section 5. Encapsulation. */
  53 #define BFD_MULTI_HOP_PORT 4784
  54
  55 /** Default slow start multiplier. */
  56 #define SLOWSTART_DMULT 3
  57 /** Default slow start transmission speed. */
  58 #define SLOWSTART_TX 1000000u
  59 /** Default slow start receive speed. */
  60 #define SLOWSTART_RX 1000000u
  61 /** Default slow start echo receive speed. */
  62 #define SLOWSTART_ERX 0u
  63
  64 /*
  65  * BFD single hop source UDP ports. As defined in RFC 5881 Section 4.
  66  * Encapsulation.
  67  */
  68 #define BFD_SOURCE_PORT_BEGIN 49152
  69 #define BFD_SOURCE_PORT_END 65535
  70
  71 /** BFD data plane protocol version. */
  72 #define BFD_DP_VERSION 1
  73
  74 /** BFD data plane message types. */
  75 enum bfddp_message_type {
  76         /** Ask for BFD daemon or data plane for echo packet. */
  77         ECHO_REQUEST = 0,
  78         /** Answer a ECHO_REQUEST packet. */
  79         ECHO_REPLY = 1,
  80         /** Add or update BFD peer session. */
  81         DP_ADD_SESSION = 2,
  82         /** Delete BFD peer session. */
  83         DP_DELETE_SESSION = 3,
  84         /** Tell BFD daemon state changed: timer expired or session down. */
  85         BFD_STATE_CHANGE = 4,
  86
  87         /** Ask for BFD session counters. */
  88         DP_REQUEST_SESSION_COUNTERS = 5,
  89         /** Tell BFD daemon about counters values. */
  90         BFD_SESSION_COUNTERS = 6,
  91 };
  92
  93 /**
  94  * `ECHO_REQUEST`/`ECHO_REPLY` data payload.
  95  *
  96  * Data plane might use whatever precision it wants for `dp_time`
  97  * field, however if you want to be able to tell the delay between
  98  * data plane packet send and BFD daemon packet processing you should
  99  * use `gettimeofday()` and have the data plane clock synchronized with
 100  * BFD daemon (not a problem if data plane runs in the same system).
 101  *
 102  * Normally data plane will only check the time stamp it sent to determine
 103  * the whole packet trip time.
 104  */
 105 struct bfddp_echo {
 106         /** Filled by data plane. */
 107         uint64_t dp_time;
 108         /** Filled by BFD daemon. */
 109         uint64_t bfdd_time;
 110 };
 111
 112
 113 /** BFD session flags. */
 114 enum bfddp_session_flag {
 115         /** Set when using multi hop. */
 116         SESSION_MULTIHOP = (1 << 0),
 117         /** Set when using demand mode. */
 118         SESSION_DEMAND = (1 << 1),
 119         /** Set when using cbit (Control Plane Independent). */
 120         SESSION_CBIT = (1 << 2),
 121         /** Set when using echo mode. */
 122         SESSION_ECHO = (1 << 3),
 123         /** Set when using IPv6. */
 124         SESSION_IPV6 = (1 << 4),
 125         /** Set when using passive mode. */
 126         SESSION_PASSIVE = (1 << 5),
 127         /** Set when session is administrative down. */
 128         SESSION_SHUTDOWN = (1 << 6),
 129 };
 130
 131 /**
 132  * `DP_ADD_SESSION`/`DP_DELETE_SESSION` data payload.
 133  *
 134  * `lid` is unique in BFD daemon so it might be used as key for data
 135  * structures lookup.
 136  */
 137 struct bfddp_session {
 138         /** Important session flags. \see bfddp_session_flag. */
 139         uint32_t flags;
 140         /**
 141          * Session source address.
 142          *
 143          * Check `flags` field for `SESSION_IPV6` before using as IPv6.
 144          */
 145         struct in6_addr src;
 146         /**
 147          * Session destination address.
 148          *
 149          * Check `flags` field for `SESSION_IPV6` before using as IPv6.
 150          */
 151         struct in6_addr dst;
 152
 153         /** Local discriminator. */
 154         uint32_t lid;
 155         /**
 156          * Minimum desired transmission interval (in microseconds) without
 157          * jitter.
 158          */
 159         uint32_t min_tx;
 160         /**
 161          * Required minimum receive interval rate (in microseconds) without
 162          * jitter.
 163          */
 164         uint32_t min_rx;
 165         /**
 166          * Required minimum echo receive interval rate (in microseconds)
 167          * without jitter.
 168          */
 169         uint32_t min_echo_rx;
 170         /** Amount of milliseconds to wait before starting the session */
 171         uint32_t hold_time;
 172
 173         /** Minimum TTL. */
 174         uint8_t ttl;
 175         /** Detection multiplier. */
 176         uint8_t detect_mult;
 177         /** Reserved / zeroed. */
 178         uint16_t zero;
 179
 180         /** Interface index (set to `0` when unavailable). */
 181         uint32_t ifindex;
 182         /** Interface name (empty when unavailable). */
 183         char ifname[64];
 184
 185         /* TODO: missing authentication. */
 186 };
 187
 188 /** BFD packet state values as defined in RFC 5880, Section 4.1. */
 189 enum bfd_state_value {
 190         /** Session is administratively down. */
 191         STATE_ADMINDOWN = 0,
 192         /** Session is down or went down. */
 193         STATE_DOWN = 1,
 194         /** Session is initializing. */
 195         STATE_INIT = 2,
 196         /** Session is up. */
 197         STATE_UP = 3,
 198 };
 199
 200 /** BFD diagnostic field values as defined in RFC 5880, Section 4.1. */
 201 enum bfd_diagnostic_value {
 202         /** Nothing was diagnosed. */
 203         DIAG_NOTHING = 0,
 204         /** Control detection time expired. */
 205         DIAG_CONTROL_EXPIRED = 1,
 206         /** Echo function failed. */
 207         DIAG_ECHO_FAILED = 2,
 208         /** Neighbor signaled down. */
 209         DIAG_DOWN = 3,
 210         /** Forwarding plane reset. */
 211         DIAG_FP_RESET = 4,
 212         /** Path down. */
 213         DIAG_PATH_DOWN = 5,
 214         /** Concatenated path down. */
 215         DIAG_CONCAT_PATH_DOWN = 6,
 216         /** Administratively down. */
 217         DIAG_ADMIN_DOWN = 7,
 218         /** Reverse concatenated path down. */
 219         DIAG_REV_CONCAT_PATH_DOWN = 8,
 220 };
 221
 222 /** BFD remote state flags. */
 223 enum bfd_remote_flags {
 224         /** Control Plane Independent bit. */
 225         RBIT_CPI = (1 << 0),
 226         /** Demand mode bit. */
 227         RBIT_DEMAND = (1 << 1),
 228         /** Multipoint bit. */
 229         RBIT_MP = (1 << 2),
 230 };
 231
 232 /**
 233  * `BFD_STATE_CHANGE` data payload.
 234  */
 235 struct bfddp_state_change {
 236         /** Local discriminator. */
 237         uint32_t lid;
 238         /** Remote discriminator. */
 239         uint32_t rid;
 240         /** Remote configurations/bits set. \see bfd_remote_flags. */
 241         uint32_t remote_flags;
 242         /** Remote minimum desired transmission interval. */
 243         uint32_t desired_tx;
 244         /** Remote minimum receive interval. */
 245         uint32_t required_rx;
 246         /** Remote minimum echo receive interval. */
 247         uint32_t required_echo_rx;
 248         /** Remote state. \see bfd_state_values.*/
 249         uint8_t state;
 250         /** Remote diagnostics (if any) */
 251         uint8_t diagnostics;
 252         /** Remote detection multiplier. */
 253         uint8_t detection_multiplier;
 254 };
 255
 256 /**
 257  * BFD control packet state bits definition.
 258  */
 259 enum bfddp_control_state_bits {
 260         /** Used to request connection establishment signal. */
 261         STATE_POLL_BIT = (1 << 5),
 262         /** Finalizes the connection establishment signal. */
 263         STATE_FINAL_BIT = (1 << 4),
 264         /** Signalizes that forward plane doesn't depend on control plane. */
 265         STATE_CPI_BIT = (1 << 3),
 266         /** Signalizes the use of authentication. */
 267         STATE_AUTH_BIT = (1 << 2),
 268         /** Signalizes that peer is using demand mode. */
 269         STATE_DEMAND_BIT = (1 << 1),
 270         /** Used in RFC 8562 implementation. */
 271         STATE_MULTI_BIT = (1 << 0),
 272 };
 273
 274 /**
 275  * BFD control packet.
 276  *
 277  * As defined in 'RFC 5880 Section 4.1 Generic BFD Control Packet Format'.
 278  */
 279 struct bfddp_control_packet {
 280         /** (3 bits version << 5) | (5 bits diag). */
 281         uint8_t version_diag;
 282         /**
 283          * (2 bits state << 6) | (6 bits flags)
 284          *
 285          * \see bfd_state_value, bfddp_control_state_bits.
 286          */
 287         uint8_t state_bits;
 288         /** Detection multiplier. */
 289         uint8_t detection_multiplier;
 290         /** Packet length in bytes. */
 291         uint8_t length;
 292         /** Our discriminator. */
 293         uint32_t local_id;
 294         /** Remote system discriminator. */
 295         uint32_t remote_id;
 296         /** Desired minimum send interval in microseconds. */
 297         uint32_t desired_tx;
 298         /** Desired minimum receive interval in microseconds. */
 299         uint32_t required_rx;
 300         /** Desired minimum echo receive interval in microseconds. */
 301         uint32_t required_echo_rx;
 302 };
 303
 304 /**
 305  * The protocol wire message header structure.
 306  */
 307 struct bfddp_message_header {
 308         /** Protocol version format. \see BFD_DP_VERSION. */
 309         uint8_t version;
 310         /** Reserved / zero field. */
 311         uint8_t zero;
 312         /** Message contents type. \see bfddp_message_type. */
 313         uint16_t type;
 314         /**
 315          * Message identification (to pair request/response).
 316          *
 317          * The ID `0` is reserved for asynchronous messages (e.g. unrequested
 318          * messages).
 319          */
 320         uint16_t id;
 321         /** Message length. */
 322         uint16_t length;
 323 };
 324
 325 /**
 326  * Data plane session counters request.
 327  *
 328  * Message type: `DP_REQUEST_SESSION_COUNTERS`.
 329  */
 330 struct bfddp_request_counters {
 331         /** Session local discriminator. */
 332         uint32_t lid;
 333 };
 334
 335 /**
 336  * BFD session counters reply.
 337  *
 338  * Message type: `BFD_SESSION_COUNTERS`.
 339  */
 340 struct bfddp_session_counters {
 341         /** Session local discriminator. */
 342         uint32_t lid;
 343
 344         /** Control packet bytes input. */
 345         uint64_t control_input_bytes;
 346         /** Control packets input. */
 347         uint64_t control_input_packets;
 348         /** Control packet bytes output. */
 349         uint64_t control_output_bytes;
 350         /** Control packets output. */
 351         uint64_t control_output_packets;
 352
 353         /** Echo packet bytes input. */
 354         uint64_t echo_input_bytes;
 355         /** Echo packets input. */
 356         uint64_t echo_input_packets;
 357         /** Echo packet bytes output. */
 358         uint64_t echo_output_bytes;
 359         /** Echo packets output. */
 360         uint64_t echo_output_packets;
 361 };
 362
 363 /**
 364  * The protocol wire messages structure.
 365  */
 366 struct bfddp_message {
 367         /** Message header. \see bfddp_message_header. */
 368         struct bfddp_message_header header;
 369
 370         /** Message payload. \see bfddp_message_type. */
 371         union {
 372                 struct bfddp_echo echo;
 373                 struct bfddp_session session;
 374                 struct bfddp_state_change state;
 375                 struct bfddp_control_packet control;
 376                 struct bfddp_request_counters counters_req;
 377                 struct bfddp_session_counters session_counters;
 378         } data;
 379 };
 380
 381 #endif /* BFD_DP_PACKET_H */