Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Capture Information Block (CIB) addition #51

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

Capture Information Block (CIB) addition #51

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ef54275
Initial Capture Information Block (CIB) concept.
ryankurte Jun 14, 2018
7608aa6
Copy edits
ryankurte Jun 17, 2018
e73d4bc
Added local_location, updated descriptions
ryankurte Jun 17, 2018
2e0bb98
Simplified proposal
ryankurte Aug 18, 2018
c91863c
Added example
ryankurte Aug 18, 2018
4e89195
Added note on CIB persistence
ryankurte Aug 18, 2018
dac8670
Fixed CIB block type, cib_options collision
ryankurte Jan 23, 2019
da11baa
Merge branch 'master' into proposed-wireless-fields
ryankurte Feb 12, 2019
7820a51
Fixing comments from review
ryankurte Feb 13, 2019
5df4b9d
add CIB option examples, fix CIB block number
ryankurte Feb 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 224 additions & 0 deletions draft-tuexen-opsawg-pcapng.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@
<t hangText='EPB:'>Enhanced Packet Block</t>
<t hangText='SPB:'>Simple Packet Block</t>
<t hangText='NRB:'>Name Resolution Block</t>
<t hangText='CIB:'>Capture Information Block</t>
<t hangText='CB:'>Custom Block</t>
</list>

Expand Down Expand Up @@ -267,6 +268,10 @@
capture has been made. If this appears in a file, an Interface
Description Block is also required, before this block.</t>

<t><xref target="section_cib">Capture Information Block</xref>: it
defines how to store some interface information such as location,
orientation, velocity, and associated errors.</t>

<t><xref target="section_custom_block">Custom Block</xref>: it
contains vendor-specific data in a portable fashion.</t>

Expand Down Expand Up @@ -2037,6 +2042,219 @@ Section Header

</section>

<section anchor="section_cib" title="Capture Information Block">

<t>The Capture Information Block (CIB) is used to support the addition
of time-varying metadata associated with capture interfaces, including
location, orientation, velocity, and related errors.
Each CIB is associated with a specific interface and applied to all packets
received on this interface following the CIB until superseded by a new CIB on
the same interface.
</t>

<t>For example, a capture from a static interface may contain a single CIB at
the start of the file to apply to all packets on this interface.
A capture from a moving interface with GNSS will add a CIB each time updated
positional information is available, and this information will apply to all
packets received on this interface until the next CIB.
</t>

<t>Note that issuing a new CIB will clear all existing CIB options on an interface,
for example, the CIBs for a non-moving but rotating interface with a known position
must all contain both location and orientation data.
</t>

<t>The format of the Capture Information Block is shown in <xref
target="format_cib"/>.</t>

<figure anchor="format_cib" title="Capture Information Block Format">
<artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
0 1 2 3
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
+---------------------------------------------------------------+
0 | Block Type = 0x0000000B |
+---------------------------------------------------------------+
4 | Block Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 | Interface ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 / /
/ Options (variable) /
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Block Total Length |
+---------------------------------------------------------------+
</artwork>
</figure>
<t>The fields have the following meaning:
<list style="symbols">

<t>Block Type: The block type of the Capture Information Block is
11.</t>

<t>Block Total Length: total size of this block, as described in
<xref target="section_block"/>.</t>

<t>Interface ID: specifies the interface for this CIB to be applied
to; the correct interface will be the one whose Interface
Description Block (within the current Section of the file) is
identified by the same number (see <xref target="section_idb"/>)
of this field. The interface ID MUST be valid, which means that an
matching interface description block MUST exist.</t>

<t>Options: optionally, a list of options (formatted according to
the rules defined in <xref target="section_opt"/>) can be present.</t>

</list>
</t>

<t>Location information can be represented with in global (lat/lng/alt in degrees)
or local (X/Y/Z in metres) form, only one of these forms may be used in a given PCAP file.
Combining pcap files with different location formats should result in the
removal of all position information.
</t>

<t>
Velocity and Orientation are to be interpreted from the zero frame for either form.
For the global form, X corresponds to latitude, Y to longitude, and Z to altitude.
Yaw is about the X/Y or Lat/Lng plane with zero facing along Y or North,
pitch is applied with this yaw offset, and roll is applied to the combination of both.
</t>

<t>
Error options provide an optional mechanism for attaching error information to measurements,
and are only valid where the corresponding measurement (location, velocity, or orientation)
option is specified. Should an error option be present without the corresponding measurement,
this option should be ignored.
</t>

<t>All the information fields are defined as options in order to support
systems that do not have a complete set of information. Therefore,
In addition to the options defined in <xref target="section_opt"/>,
the following options are valid within this block:</t>

<texttable anchor="options_cib" title="Capture Information Block Options">
<ttcol align="left">Name</ttcol>
<ttcol align="left">Code</ttcol>
<ttcol align="left">Length</ttcol>
<ttcol align="left">Multiple allowed?</ttcol>

<c>local_location</c>
<c>2</c>
<c>12</c>
<c>no</c>

<c>local_location_error</c>
<c>3</c>
<c>12</c>
<c>no</c>

<c>global_location</c>
<c>4</c>
<c>12</c>
<c>no</c>

<c>global_location_error</c>
<c>5</c>
<c>12</c>
<c>no</c>

<c>orientation</c>
<c>6</c>
<c>12</c>
<c>no</c>

<c>orientation_error</c>
<c>7</c>
<c>12</c>
<c>no</c>

<c>velocity</c>
<c>8</c>
<c>12</c>
<c>no</c>

<c>velocity_error</c>
<c>9</c>
<c>12</c>
<c>no</c>
</texttable>

<t>
<list hangIndent="8" style="hanging">

<t hangText="cib_local_location"><vspace blankLines="0"/>The
cib_local_location option specifies the local location of the packet
capture or interface in an abitrary plane; location is stored as three
32-bit floats representing X, Y (in plane), and Z (altitude) offsets in
metres.</t>

<t>Example: '41 24 cc cd 41 73 33 33 3f cc cc cd' decodes to
x: 10.3m, y: 15.2m, z: 1.6m</t>

<t hangText="cib_local_location_error"><vspace blankLines="0"/>The
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it should indicate that having a cib_local_location_error option without a cib_local_location makes no sense, and that having a cib_local_location option without a cib_local_location_error option means that the error is unknown.

If so, the same should be done for the other options as well.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added that an overarching comment at line 2125 rather than adding it per-option, though I can put it on each option if you would prefer?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A global comment suffices.

What's the correct interpretation of a measurement without a corresponding error? "It's unknown how accurate this measurement is"?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the absence of error information only indicates that there is no error information.
As to whether it is unknown, unknowable, elided because the capturer doesn't care, or for any other reason, would be outside the scope of the capture file?

cib_local_location_error option specifies the error in local location
capture; this is stored as three 32-bit floats in the same order and
representation as cib_local_location.</t>

<t>Example: '3f 80 00 00 3f 99 99 9a 3f cc cc cd' decodes to
x_error: 1.0m, y_error: 1.2m, z_error: 1.6m</t>

<t hangText="cib_global_location"><vspace blankLines="0"/>The
cib_global_location option specifies the global location of the
packet capture or interface; location is stored as three 32-bit floats
representing latitude and longitude in degrees, and altitude in
metres.</t>

<t>Example: 'c2 13 64 ce 43 2e c2 90 41 88 00 00' decodes to
lat: -36.8484437° lng: 174.7600023° alt: 17.0m</t>

<t hangText="cib_global_location_error"><vspace blankLines="0"/>The
cib_global_location_error option specifies the error in global location
capture; this is stored as three 32-bit floats in the same order and
representation as cib_global_location.</t>

<t>Example: '3f 80 00 00 3f 99 99 9a 3f cc cc cd' decodes to
lat_error: 0.1° lng_error: 0.2° alt_error: 1.6m</t>

<t hangText="cib_orientation"><vspace blankLines="0"/>The
cib_orientation option specifies the orientation of the packet
capturing antenna; orientation is stored as three 32-bit floats
representing yaw, pitch, and roll in radians.
This is relative to the zero frame for global or local location.</t>

<t>Example: '3f c9 0f db 3e 86 0a 92 00 00 00 00' decodes to
yaw: pi/2, pitch: -pi/12, roll: 0.0</t>

<t hangText="cib_orientation_error"><vspace blankLines="0"/>The
cib_orientation_error option specifies the error in orientation capture;
this is stored as three 32-bit floats in the same order and
representation as cib_orientation.</t>

<t>Example: '3c 23 d7 0a 3c a3 d7 0a 00 00 00 00' decodes to
yaw_error: 0.01, pitch_error: 0.02, roll_error: 0.0</t>

<t hangText="cib_velocity"><vspace blankLines="0"/>The
cib_velocity option specifies the velocity of the packet capture interface;
velocity is stored as three 32-bit floats representing the motion in the
X (lat), Y (lng), and Z (altitude) directions in metres per second.
This is relative to the zero frame for global or local location.</t>

<t>Example: '41 24 cc cd 41 73 33 33 00 00 00 00' decodes to
x: 10.3m/s, y: 15.2m/s, z: 0.0m/s</t>

<t hangText="cib_velocity_error"><vspace blankLines="0"/>The
cib_velocity_error option specifies the error in velocity capture;
this is stored as three 32-bit floats in the same order and
representation as cib_velocity.</t>

<t>Example: '3f 80 00 00 3f 99 99 9a 00 00 00 00' decodes to
x_error: 1.0m/s, y_error: 1.2m/s, z_error: 0.0m/s</t>

</list>
</t>

</section>

<section anchor="section_custom_block" title="Custom Block">

Expand Down Expand Up @@ -2576,6 +2794,12 @@ Section Header
<xref target="section_dsb">Decryption Secrets Block</xref>
</c>


<c>0x0000000B</c>
<c>
<xref target="section_cib">Capture Information Block</xref>
</c>

<c>0x00000101</c>
<c>
<eref target="https://github.com/HoneProject">Hone Project</eref>
Expand Down