epan/dissectors/packet-bpv7.h

   1 /* packet-bpv7.h
   2  * Definitions for Bundle Protocol Version 7 dissection.
   3  * References:
   4  *     RFC 9171: https://www.rfc-editor.org/rfc/rfc9171.html
   5  *
   6  * Copyright 2019-2021, Brian Sipos <brian.sipos@gmail.com>
   7  *
   8  * Wireshark - Network traffic analyzer
   9  * By Gerald Combs <gerald@wireshark.org>
  10  * Copyright 1998 Gerald Combs
  11  *
  12  * SPDX-License-Identifier: LGPL-2.1-or-later
  13  */
  14 #ifndef PACKET_BPV7_H
  15 #define PACKET_BPV7_H
  16
  17 #include <ws_symbol_export.h>
  18 #include <epan/tvbuff.h>
  19 #include <epan/proto.h>
  20 #include <epan/expert.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /* This dissector defines two layers of protocol:
  27  * - The BPv7 bundle format and its block types.
  28  * - The BPv7 Administrative Record which is a bundle payload as indicated by
  29  *   a primary block flag.
  30  *
  31  * BPv7 block-type-specific data (BTSD) dissectors are registered with the
  32  * dissector table "bpv7.block_type" and Administrative Record dissectors
  33  * with the table "bpv7.admin_record_type". Both use uint64_t* table keys.
  34  * Both use bp_dissector_data_t* as dissector user data.
  35  *
  36  * There is a BTSD heuristic dissector table "bpv7.btsd" which uses
  37  * bp_dissector_data_t* as dissector user data.
  38  *
  39  * Payload block (block type 1) dissection is additionally handled based on
  40  * bundle flags and destination EID as:
  41  * - If the bundle flags mark it as administrative, it is dissected as such.
  42  * - If the destination is a well-known SSP, the dissector table
  43  *   "bpv7.payload.dtn_wkssp" is used with the scheme-specific part.
  44  * - If the destination is "dtn" scheme, the dissector table
  45  *   "bpv7.payload.dtn_serv" is used with the service demux (text string).
  46  *   There is also Decode As behavior for dtn service demux.
  47  * - If the destination is "ipn" scheme, the dissector table
  48  *   "bpv7.payload.ipn_serv" is used with the service number (uint value).
  49  *   There is also Decode As behavior for ipn service number.
  50  * - Finally, fall through to BTSD heuristic dissection.
  51  * All payload dissection uses bp_dissector_data_t* as dissector user data.
  52  */
  53
  54 /** Bundle CRC types.
  55  * RFC 9171 Section 4.2.1.
  56  */
  57 typedef enum {
  58     /// no CRC is present.
  59     BP_CRC_NONE = 0,
  60     /// a standard X-25 CRC-16 is present.
  61     BP_CRC_16 = 1,
  62     /// a standard CRC32C (Castagnoli) CRC-32 is present.
  63     BP_CRC_32 = 2,
  64 } BundleCrcType;
  65
  66 /** Bundle processing control flags.
  67  * RFC 9171 Section 4.2.3.
  68  */
  69 typedef enum {
  70     /// bundle deletion status reports are requested.
  71     BP_BUNDLE_REQ_DELETION_REPORT = 0x040000,
  72     /// bundle delivery status reports are requested.
  73     BP_BUNDLE_REQ_DELIVERY_REPORT = 0x020000,
  74     /// bundle forwarding status reports are requested.
  75     BP_BUNDLE_REQ_FORWARDING_REPORT = 0x010000,
  76     /// bundle reception status reports are requested.
  77     BP_BUNDLE_REQ_RECEPTION_REPORT = 0x004000,
  78     /// status time is requested in all status reports.
  79     BP_BUNDLE_REQ_STATUS_TIME = 0x000040,
  80     /// user application acknowledgement is requested.
  81     BP_BUNDLE_USER_APP_ACK = 0x000020,
  82     /// bundle must not be fragmented.
  83     BP_BUNDLE_NO_FRAGMENT = 0x000004,
  84     /// payload is an administrative record.
  85     BP_BUNDLE_PAYLOAD_ADMIN = 0x000002,
  86     /// bundle is a fragment.
  87     BP_BUNDLE_IS_FRAGMENT = 0x000001,
  88 } BundleProcessingFlag;
  89
  90 /** Block processing control flags.
  91  * RFC 9171 Section 4.2.4.
  92  */
  93 typedef enum {
  94     /// block must be removed from bundle if it can't be processed.
  95     BP_BLOCK_REMOVE_IF_NO_PROCESS = 0x10,
  96     /// bundle must be deleted if block can't be processed.
  97     BP_BLOCK_DELETE_IF_NO_PROCESS = 0x04,
  98     /// transmission of a status report is requested if block can't be processed.
  99     BP_BLOCK_STATUS_IF_NO_PROCESS = 0x02,
 100     /// block must be replicated in every fragment.
 101     BP_BLOCK_REPLICATE_IN_FRAGMENT = 0x01,
 102 } BlockProcessingFlag;
 103
 104 /** Standard block type codes.
 105  * RFC 9171 Section 4.3.2 and Section 4.4.
 106  */
 107 typedef enum {
 108     BP_BLOCKTYPE_INVALID = 0,
 109     /// Payload (data)
 110     BP_BLOCKTYPE_PAYLOAD = 1,
 111     /// Previous Node
 112     BP_BLOCKTYPE_PREV_NODE = 6,
 113     /// Bundle Age
 114     BP_BLOCKTYPE_BUNDLE_AGE = 7,
 115     /// Hop Count
 116     BP_BLOCKTYPE_HOP_COUNT = 10,
 117     /// Block Integrity Block
 118     BP_BLOCKTYPE_BIB = 11,
 119     /// Block Confidentiality Block
 120     BP_BLOCKTYPE_BCB = 12,
 121 } BlockTypeCode;
 122
 123 /** Administrative record type codes.
 124  * RFC 9171 Section 6.1.
 125  */
 126 typedef enum {
 127     /// Bundle status report
 128     BP_ADMINTYPE_BUNDLE_STATUS = 1,
 129 } AdminRecordTypeCode;
 130
 131 /// DTN time with derived UTC time
 132 typedef struct {
 133     /// DTN time
 134     uint64_t dtntime;
 135     /// Converted to UTC
 136     nstime_t utctime;
 137 } bp_dtn_time_t;
 138
 139 /// Creation Timestamp used to correlate bundles
 140 typedef struct {
 141     /// Absolute time
 142     bp_dtn_time_t abstime;
 143     /// Sequence number
 144     uint64_t seqno;
 145 } bp_creation_ts_t;
 146
 147 /** Function to match the GCompareDataFunc signature.
 148  */
 149 WS_DLL_PUBLIC
 150 int bp_creation_ts_compare(const void *a, const void *b, void *user_data);
 151
 152 /** Endpoint ID scheme encodings.
 153  */
 154 typedef enum {
 155     EID_SCHEME_DTN = 1,
 156     EID_SCHEME_IPN = 2,
 157 } EidScheme;
 158
 159 /// Metadata from a Endpoint ID
 160 typedef struct {
 161     /// Scheme ID number
 162     int64_t scheme;
 163     /// Derived URI text as address
 164     address uri;
 165
 166     /// Optional DTN-scheme well-known SSP
 167     const char *dtn_wkssp;
 168     /// Optional DTN-scheme service name
 169     const char *dtn_serv;
 170     /// Optional IPN-scheme service name
 171     uint64_t *ipn_serv;
 172 } bp_eid_t;
 173
 174 /** Construct a new timestamp.
 175  */
 176 WS_DLL_PUBLIC
 177 bp_eid_t * bp_eid_new(wmem_allocator_t *alloc);
 178
 179 /** Function to match the GDestroyNotify signature.
 180  */
 181 WS_DLL_PUBLIC
 182 void bp_eid_free(wmem_allocator_t *alloc, bp_eid_t *obj);
 183
 184 /** Function to match the GCompareFunc signature.
 185  */
 186 WS_DLL_PUBLIC
 187 bool bp_eid_equal(const void *a, const void *b);
 188
 189 /// Security marking metadata
 190 typedef struct {
 191     /// Block numbers marking the data as security integrity protected
 192     wmem_map_t *data_i;
 193     /// Block numbers marking the data as security-modified and not decodable
 194     wmem_map_t *data_c;
 195 } security_mark_t;
 196
 197 /// Metadata extracted from the primary block
 198 typedef struct {
 199     /// Display item for the whole block
 200     proto_item *item_block;
 201
 202     /// Bundle flags (assumed zero).
 203     /// Values are BundleProcessingFlag.
 204     uint64_t flags;
 205     /// Destination EID
 206     bp_eid_t *dst_eid;
 207     /// Source NID
 208     bp_eid_t *src_nodeid;
 209     /// Report-to NID
 210     bp_eid_t *rep_nodeid;
 211     /// Creation Timestamp
 212     bp_creation_ts_t ts;
 213     /// Optional fragment start offset
 214     uint64_t *frag_offset;
 215     /// Optional bundle total length
 216     uint64_t *total_len;
 217     /// CRC type code (assumed zero)
 218     uint64_t crc_type;
 219     /// Raw bytes of CRC field
 220     tvbuff_t *crc_field;
 221
 222     security_mark_t sec;
 223 } bp_block_primary_t;
 224
 225 /** Construct a new object on the file allocator.
 226  */
 227 WS_DLL_PUBLIC
 228 bp_block_primary_t * bp_block_primary_new(wmem_allocator_t *alloc);
 229
 230 /** Function to match the GDestroyNotify signature.
 231  */
 232 WS_DLL_PUBLIC
 233 void bp_block_primary_free(wmem_allocator_t *alloc, bp_block_primary_t *obj);
 234
 235 typedef struct {
 236     /// The index of the block within the bundle.
 237     /// This is for internal bookkeeping, *not* the block number.
 238     uint64_t blk_ix;
 239     /// Display item for the whole block
 240     proto_item *item_block;
 241
 242     /// Type of this block
 243     uint64_t *type_code;
 244     /// Unique identifier for this block
 245     uint64_t *block_number;
 246     /// All flags on this block
 247     uint64_t flags;
 248     /// CRC type code (assumed zero)
 249     uint64_t crc_type;
 250     /// Raw bytes of CRC field
 251     tvbuff_t *crc_field;
 252
 253     /// Type-specific data, unencoded
 254     tvbuff_t *data;
 255     /// Type-specific data tree
 256     proto_tree *tree_data;
 257
 258     security_mark_t sec;
 259 } bp_block_canonical_t;
 260
 261 /** Construct a new object on the file allocator.
 262  * @param blk_ix The index of the block within the bundle.
 263  * The canonical index is always greater than zero.
 264  */
 265 WS_DLL_PUBLIC
 266 bp_block_canonical_t * bp_block_canonical_new(wmem_allocator_t *alloc, uint64_t blk_ix);
 267
 268 WS_DLL_PUBLIC
 269 void bp_block_canonical_delete(wmem_allocator_t *alloc, bp_block_canonical_t *obj);
 270
 271 /// Identification of an individual bundle
 272 typedef struct {
 273     /// Normalized EID URI for the Source Node ID
 274     address src;
 275     /// Creation Timestamp
 276     bp_creation_ts_t ts;
 277     /// Pointer to external optional fragment start offset
 278     const uint64_t *frag_offset;
 279     /// Pointer to external optional bundle total length
 280     const uint64_t *total_len;
 281 } bp_bundle_ident_t;
 282
 283 /** Construct a new object on the file allocator.
 284  * @param alloc The allocator to use.
 285  * @param src The non-null pointer to source EID.
 286  * @param ts The non-null pointer to Timestamp.
 287  * @param off Optional fragment offset value.
 288  * @param len Optional fragment length value.
 289  */
 290 WS_DLL_PUBLIC
 291 bp_bundle_ident_t * bp_bundle_ident_new(wmem_allocator_t *alloc, const bp_eid_t *src, const bp_creation_ts_t *ts, const uint64_t *off, const uint64_t *len);
 292
 293 WS_DLL_PUBLIC
 294 void bp_bundle_ident_free(wmem_allocator_t *alloc, bp_bundle_ident_t *obj);
 295
 296 /** Function to match the GEqualFunc signature.
 297  */
 298 WS_DLL_PUBLIC
 299 gboolean bp_bundle_ident_equal(const void *a, const void *b);
 300
 301 /** Function to match the GHashFunc signature.
 302  */
 303 WS_DLL_PUBLIC
 304 unsigned bp_bundle_ident_hash(const void *key);
 305
 306 /// Metadata extracted per-bundle
 307 typedef struct {
 308     /// Index of the frame
 309     uint32_t frame_num;
 310     /// Layer within the frame
 311     uint8_t layer_num;
 312     /// Timestamp on the frame (end time if reassembled)
 313     nstime_t frame_time;
 314     /// Bundle identity derived from #primary data
 315     bp_bundle_ident_t *ident;
 316     /// Required primary block
 317     bp_block_primary_t *primary;
 318     /// Additional blocks in order (type bp_block_canonical_t)
 319     wmem_list_t *blocks;
 320     /// Map from block number (uint64_t) to pointer to block of that number
 321     /// (bp_block_canonical_t owned by #blocks)
 322     wmem_map_t *block_nums;
 323     /// Map from block type code (uint64_t) to sequence (wmem_list_t) of
 324     /// pointers to block of that type (bp_block_canonical_t owned by #blocks)
 325     wmem_map_t *block_types;
 326
 327     /// Payload BTSD start offset in bundle TVB
 328     unsigned *pyld_start;
 329     /// Payload BTSD length
 330     unsigned *pyld_len;
 331 } bp_bundle_t;
 332
 333 /** Construct a new object on the file allocator.
 334  */
 335 WS_DLL_PUBLIC
 336 bp_bundle_t * bp_bundle_new(wmem_allocator_t *alloc);
 337
 338 /** Function to match the GDestroyNotify signature.
 339  */
 340 WS_DLL_PUBLIC
 341 void bp_bundle_free(wmem_allocator_t *alloc, bp_bundle_t *obj);
 342
 343 /** Extract an Endpoint ID.
 344  * All EID fields are allocated with wmem_file_scope().
 345  *
 346  * @param tree The tree to write items under.
 347  * @param hfindex The root item field.
 348  * @param hfindex_uri The reassembled URI item field.
 349  * @param pinfo Packet info to update.
 350  * @param tvb Buffer to read from.
 351  * @param[in,out] offset Starting offset within @c tvb.
 352  * @param[out] eid If non-null, the EID to write to.
 353  * @return The new tree item.
 354  */
 355 WS_DLL_PUBLIC
 356 proto_item * proto_tree_add_cbor_eid(proto_tree *tree, int hfindex, int hfindex_uri, packet_info *pinfo, tvbuff_t *tvb, int *offset, bp_eid_t *eid);
 357
 358 /// Metadata for an entire file
 359 typedef struct {
 360     /// Map from a bundle ID (bp_bundle_ident_t) to wmem_list_t of bundle (bp_bundle_t)
 361     wmem_map_t *bundles;
 362     /// Map from subject bundle ID (bp_bundle_ident_t) to
 363     /// map from references (bp_bundle_ident_t) of status bundles to NULL
 364     /// i.e. a set
 365     wmem_map_t *admin_status;
 366 } bp_history_t;
 367
 368 /** Data supplied to each block sub-dissector.
 369  */
 370 typedef struct {
 371     /// The overall bundle being decoded (so far)
 372     bp_bundle_t *bundle;
 373     /// This block being decoded
 374     bp_block_canonical_t *block;
 375 } bp_dissector_data_t;
 376
 377 #ifdef __cplusplus
 378 }
 379 #endif
 380
 381 #endif /* PACKET_BPV7_H */