How to call my dissector on USB payload (leftover capture data)

Question

Hello,

in the question How can I decrypt SSL session with Lua dissector, a custom Lua dissector is added to the dissector table "usb.bulk". My usecase is similar: I need to dissect a proprietary protocol on top of the USB protocol. But the following instruction (as seen in that question) doesn't seem to do the trick:

function myprotocol.init()
    DissectorTable.get("usb.bulk"):add(0xFF, myprotocol)
end

Normally I would replace the dissector with my own, keeping a reference to the original one and call that explicitly if needed (like described here) - but I do not know which dissector(s) from that DissectorTable I need to replace. So I am stuck with the following questions:

What is the behavior of a DissectorTable when I add another dissector? What do I have to do so that my dissector gets called?
Which dissectors are contained in the usb.bulk DissectorTable? I could not find out on github (btw. I am not a C programmer)
Does the 'pattern' argument of the add function (the value 0xFF in this case) have any relevance for USB dissector tables?
Should I create my own DissectorTable for this usecase? Why would I need one?

Any help is much appreciated. Thank you in advance.

Accepted Answer

Handling of USB captures is a bit complex in terms that the possibility to choose a dissector for the payload automatically often depends on whether the enumeration phase has been captured or not, because the "integer" dissector tables refer to values of fields of USB descriptors which are only transferred over the bus during the enumeration phase.

So in the particular case of that other Question, the 0xff (or 255) value inserted into the usb.bulk integer dissector table probably matches the value of bInterfaceClass from the interface descriptor. That table is, as its name suggests, only consulted for USB bulk transfers.

For payloads which follow some characteristic patterns, the choice of dissector is slightly easier, because it is possible to use heuristic to choose the proper dissector even if the enumeration phase is missing in the capture. A heuristic dissector also needs to be registered for a transport protocol, and all heuristic dissectors registered for a given transport are tried on all payload PDUs of that transport until one of them succeeds, with the following exception: if a heuristic dissector for protocol X succeeds on a PDU, it may declare that PDU to be part of a "conversation" of protocol X; doing so makes the transport protocol's dissector invoke the dissector for protocol X on further PDUs with identical address attributes (in our case, the USB address B.D.E - Bus.Device.Endpoint) directly rather than attempt all registered heuristic dissectors again. So for USB bulk transfers, you would register your protocol's heuristic dissector as one for transport usb.bulk. I'm simplifying here a bit because I don't know whether you actually need the details.

So the first things to do for you is to check what type of USB transfer your proprietary protocol is using, whether the pattern is unambiguous enough that it would be safe to base a heuristic on it. If you cannot rely on heuristic and the transfer used is bulk, find out what bInterfaceClass value your USB device is sending in its GET DESCRIPTOR Response CONFIGURATION answer during enumeration phase. For other transfer types, another field of another message may have been chosen as selector.