.. _protocol_setup_wireshark_udpdump:

=================
Wireshark udpdump
=================

`udpdump(1)`_ is Wireshark's remote UDP capture interface. ``vey-proxy`` can
export decrypted traffic to this interface by using Wireshark's
``exported_pdu`` format.

See `udpdump(1)`_ for the full Wireshark-side reference.

.. _udpdump(1): https://www.wireshark.org/docs/man-pages/udpdump.html

Protocol
--------

The exported records use the following Wireshark definitions:

- Data structure: `exported_pdu_tlvs`_
- Dissector implementation: `exported_pdu`_

.. _exported_pdu_tlvs: https://github.com/wireshark/wireshark/blob/master/wsutil/exported_pdu_tlvs.h
.. _exported_pdu: https://github.com/wireshark/wireshark/blob/master/epan/dissectors/packet-exported_pdu.c


Wireshark GUI
-------------

To capture packets in the Wireshark GUI:

- Select the *UDP Listener remote capture* entry in the main Wireshark window.
- Click the *settings* button at the beginning of that row.
- Set payload type to **exported_pdu**.
- Set the listening port to the value you want, then click *Save*.
- Double-click the *UDP Listener remote capture* entry to start the capture.

Tshark CLI
----------

See `extcap-preference`_ for the corresponding tshark options.

.. _extcap-preference: https://tshark.dev/capture/sources/extcap_interfaces/#extcap-preferences

Example:

.. code-block:: shell

  tshark -i udpdump -o extcap.udpdump.payload:exported_pdu -o extcap.udpdump.port:5555 <...>

Packet Layout
--------------

For each captured packet, the saved capture file will contain three
``exported_pdu`` frames.

The first frame is added by ``udpdump`` itself. It contains:

- The UDP socket address of ``vey-proxy``.

  The source IP is stored in ``EXP_PDU_TAG_IPV4_SRC`` or
  ``EXP_PDU_TAG_IPV6_SRC``.
  The source port is stored in ``EXP_PDU_TAG_SRC_PORT``.

- The UDP socket address of ``udpdump``.

  The destination IP is stored in ``EXP_PDU_TAG_IPV4_DST`` or
  ``EXP_PDU_TAG_IPV6_DST``.
  The destination port is stored in ``EXP_PDU_TAG_DST_PORT``.

The second frame is generated by ``vey-proxy``. It contains:

- The socket addresses for the client-side connection:

  - The client socket address for the client connection
  - The server socket address for the client connection

  The source IP is stored in ``EXP_PDU_TAG_IPV4_SRC`` or
  ``EXP_PDU_TAG_IPV6_SRC``.
  The source port is stored in ``EXP_PDU_TAG_SRC_PORT``.
  The destination IP is stored in ``EXP_PDU_TAG_IPV4_DST`` or
  ``EXP_PDU_TAG_IPV6_DST``.
  The destination port is stored in ``EXP_PDU_TAG_DST_PORT``.

The third frame is also generated by ``vey-proxy``. It contains:

- The socket addresses for the remote-side connection:

  - The client socket address for the remote connection
  - The server socket address for the remote connection

  The source IP is stored in ``EXP_PDU_TAG_IPV4_SRC`` or
  ``EXP_PDU_TAG_IPV6_SRC``.
  The source port is stored in ``EXP_PDU_TAG_SRC_PORT``.
  The destination IP is stored in ``EXP_PDU_TAG_IPV4_DST`` or
  ``EXP_PDU_TAG_IPV6_DST``.
  The destination port is stored in ``EXP_PDU_TAG_DST_PORT``.

- The port type.

  It is stored in ``EXP_PDU_TAG_PORT_TYPE``. For stream-based connections, the
  value is ``EXP_PDU_PT_TCP``.

To uniquely identify a stream, use all of the following values together:

- Source IP and source port from the first frame
- Source IP, source port, destination IP, destination port, and port type from
  the second frame