The Tcpdump Group git mirrors - libpcap/blob - cbpf-savefile.manfile.in

   1 .\" Copyright (c) 2022
   2 .\"     The TCPDUMP project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution.
  10 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  11 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  13 .\"
  14 .TH CBPF-SAVEFILE @MAN_FILE_FORMATS@ "9 February 2025"
  15 .SH NAME
  16 cbpf-savefile \- cBPF savefile format (work in progress, DRAFT revision 7)
  17 .SH DESCRIPTION
  18 This man page discusses a file format for cBPF, which is the "classic" (and
  19 for a long time the only) Berkeley Packet Filter.  It does
  20 .B NOT
  21 apply to the newer "extended" variety of BPF (eBPF).
  22 .LP
  23 The main purpose of this file format is to store BPF bytecode, most commonly
  24 compiled from a BPF filter expression (see
  25 .BR \%pcap-filter (7)
  26 for the filter syntax description) using libpcap.  Besides that, the format
  27 allows to encode some information about the context in which the compilation
  28 was done.  This meta-data can make it easier to reproduce the compilation
  29 later if required.  cBPF savefile design is based on the file format proposed
  30 by C.S. Peron in 2005.
  31 .LP
  32 Unless stated otherwise, in the following specification integer fields are
  33 big-endian unsigned, string fields do not use NUL character for termination
  34 or padding.
  35
  36 .SH FILE FORMAT
  37 A savefile consists of a fixed-size header and a variable-size body as
  38 follows:
  39 .LP
  40 .nf
  41  0                   1                   2                   3
  42  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  43 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  44 |      0xA1     |      0xB2     |     0xC3      |     0xCB      |
  45 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  46 |      'c'      |      'B'      |     'P'       |     'F'       |
  47 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  48 |   MajorVer=1  |    MinorVer   |             Flags             |
  49 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  50 |                            SnapLen                            |
  51 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  52 |         LinkTypeValue         |       InstructionCount=n      |
  53 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  54 |                                                               |
  55 |                         instruction 1                         |
  56 |                                                               |
  57 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  58 |                                                               |
  59 |                         instruction 2                         |
  60 |                                                               |
  61 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  62 |                                                               |
  63 ~                                                               ~
  64 |                                                               |
  65 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  66 |                                                               |
  67 |                         instruction n                         |
  68 |                                                               |
  69 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  70 |                                                               |
  71 |                   optional trailing TLV space                 |
  72 |                                                               |
  73 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  74 .fi
  75 .LP
  76 The first four octets contain a fixed signature, also known as
  77 a magic number, to make it easy to identify the file type automatically.
  78 The next four octets contain the ASCII string "cBPF" to provide a hint for
  79 manual identification.
  80
  81 .SS MajorVer and MinorVer
  82 Contain the major and the minor version numbers of this format respectively.
  83 The current major version is 1 and the current minor version is 0.  Format
  84 changes that do not impact compatibility (e.g., new TLV types or flags)
  85 increment the minor version only.  Other format changes increment the major
  86 version and reset the minor version to 0.  All format versions have the first
  87 part of the header up to and including MinorVer identical.
  88
  89 .SS Flags
  90 .nf
  91  b15 b14 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00
  92 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  93 |                       reserved            |RND|CPX|COP|XOR|MOD|
  94 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  95 .fi
  96
  97 MOD, XOR, COP, CPX and RND: if set to 1, in this BPF dialect
  98 .BR BPF_MOD ,
  99 .BR BPF_XOR ,
 100 .BR BPF_COP ,
 101 .B BPF_COPX
 102 and
 103 .B BPF_RND
 104 respectively are valid instructions.  For the current list of OSes that
 105 support
 106 .B BPF_MOD
 107 and
 108 .B BPF_XOR
 109 in the kernel see the
 110 .B %
 111 and
 112 .B ^
 113 binary operators in
 114 .BR \%pcap-filter (7).
 115 .B BPF_COP
 116 and
 117 .B BPF_COPX
 118 are implemented in NetBSD kernel.
 119 .B BPF_RND
 120 is implemented in OpenBSD kernel.
 121 .LP
 122 Note that the fact an instruction is valid in a BPF dialect does not always
 123 mean the compiled bytecode in the savefile contains the instruction.  In other
 124 words, the purpose of the flags above is not to provide a digest of the file
 125 contents, but to enable conclusive automatic verification of the bytecode if
 126 required by the use case.
 127
 128
 129 .SS SnapLen
 130 Contains the snapshot length used for the compilation, usually this is the
 131 .I snaplen
 132 input argument to
 133 .BR pcap_open_dead (3PCAP)
 134 or
 135 .BR pcap_set_snaplen (3PCAP).
 136
 137 .SS LinkTypeValue
 138 Contains the link-layer header type value used for the compilation, usually
 139 this is either the
 140 .I linktype
 141 input argument to
 142 .BR pcap_open_dead ()
 143 or the
 144 .I dlt
 145 input argument to
 146 .BR pcap_set_datalink (3PCAP)
 147 or the value(s) returned by
 148 .BR pcap_datalink (3PCAP)
 149 and
 150 .BR pcap_list_datalinks (3PCAP).
 151 Although these functions take and return link-layer header type values via the
 152 .B int
 153 C type, by convention only the low 16 bits are in use.
 154
 155 .SS InstructionCount
 156 This is the last field of the fixed header in major version 1, it contains the
 157 number of bytecode instructions following the header.  By convention, valid
 158 BPF bytecode always ends with a
 159 .B ret
 160 instruction, so in a valid savefile this field value is at least 1.
 161
 162 .PP
 163 The file format thus far minimizes the overhead for software that uses the BPF
 164 bytecode.  If there is any data after the last instruction, it is the trailing
 165 TLV space, which mostly contains meta-data for human interpretation.  It
 166 contains TLVs in the format specified below.
 167
 168 .SH INSTRUCTION FORMAT
 169 .LP
 170 .nf
 171  0                   1                   2                   3
 172  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 173 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 174 |             opcode            |       jt      |       jf      |
 175 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 176 |                               k                               |
 177 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 178 .fi
 179 .LP
 180 This is the traditional encoding of a BPF instruction (a 4-tuple of
 181 integers).  Note that usually the endianness depends on the machine, but in
 182 this format it is fixed.  Some opcodes interpret k as a signed integer.
 183
 184 .SH TLV FORMAT
 185 .LP
 186 .nf
 187  0                   1                   2                   3
 188  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 189 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 190 |              Type             |            Length=m           |
 191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 192 |                                                               |
 193 ~                        Value (m octets)                       ~
 194 |                                                               |
 195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 196 .fi
 197 .LP
 198 All TLVs are optional.  Every TLV may appear in the same savefile at most
 199 once.  Length value does not include Type and Length.  Code points for Type
 200 and the associated Length constraints are defined below.
 201
 202 .SS EOF TLV
 203 Allows to mark the end of TLV space (hence of the savefile) explicitly to make it
 204 clear that the file is not truncated.  If this TLV is present in the TLV
 205 space, it may appear the last only.
 206 .LP
 207 Type is 0, Length is 0, Value is empty.
 208
 209 .SS LinkTypeName TLV
 210 Allows to record the input argument to
 211 .BR pcap_datalink_name_to_val (3PCAP)
 212 if the latter was used to translate a DLT name into LinkTypeValue (the same
 213 name can sometimes produce different values in different contexts).
 214 .LP
 215 Type is 1, Length is variable, Value contains an ASCII string.
 216
 217 .SS Filter TLV
 218 Allows to record the filter expression that was compiled into the
 219 bytecode, usually this is the
 220 .I str
 221 input argument to
 222 .BR pcap_compile (3PCAP).
 223 .LP
 224 Type is 2, Length is variable, Value contains an ASCII string.
 225
 226 .SS OptReq TLV
 227 Allows to record whether optimization was requested for the compilation or
 228 not, usually this is the
 229 .I optimize
 230 input argument to
 231 .BR pcap_compile ().
 232 Note that some link-layer header types and filter keywords disable the
 233 optimization automatically in libpcap.
 234 .LP
 235 Type is 3, Length is 1, Value contains 1 or 0.
 236
 237 .SS Netmask TLV
 238 Allows to record the value of
 239 .I netmask
 240 input argument to
 241 .BR pcap_compile ().
 242 .LP
 243 Type is 4, Length is 4, Value contains a 32-bit IPv4 netmask.
 244
 245 .SS Comment TLV
 246 Allows to record a free-form text, for example, the name and version of the
 247 program that generated the file.
 248 .LP
 249 Type is 5, Length is variable, Value contains a UTF-8 string.
 250
 251 .SS Timestamp TLV
 252 Allows to record when the compilation was performed.
 253 .LP
 254 Type is 6, Length is 8, Value contains a 64-bit Unix timestamp.
 255
 256 .SH SOFTWARE SUPPORT
 257 BPF Exam at
 258 .I \%https://www.tcpdump.org/bpfexam/
 259 can produce a cBPF savefile from user input.
 260
 261 .SH SEE ALSO
 262 .BR \%pcap-savefile (@MAN_FILE_FORMATS@)