addUpperLayerDecoder

Add custom upper-layer protocol decoder to PCAP file reader

Since R2021b

collapse all in page

    Syntax

    addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder)
    addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder,protocolFields)

    Description

    You can use the addUpperLayerDecoder object function to plug in a custom upper-layer protocol decoder to the pcapReader object for decoding the payload of an existing protocol decoder. For example, you can add an upper-layer protocol decoder, such as internet protocol (IP), to decode the payload in the output of an existing protocol decoder, Ethernet.

    addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder) adds a custom upper-layer protocol decoder function handle, upperLayerDecoder, to the packet capture (PCAP) file reader, pcap, for decoding the payload in the output of an existing protocol decoder, protocolName. The fieldName input specifies the field in the output structure of the existing protocol decoder, and the fieldValue input specifies the value of this field name. The upperLayerProtocolName input specifies a name for the upper-layer protocol decoder.

    example

    addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder,protocolFields) additionally specifies protocol fields to filter packets based on the specified fields of the protocol decoder output.

    Examples

    collapse all

    Open Live Script

    Create a protocol decoder function handle for decoding IP packets.

    ipDecoderHandle = @helperIPDecode;

    Create a PCAP file reader object, specifying the name of a PCAP file.

    pcapReaderObj = pcapReader("ethernetSamplePackets.pcap");

    Add IP packet decoder to the PCAP file reader for decoding the payload in the output of an existing protocol decoder, Ethernet.

    addUpperLayerDecoder(pcapReaderObj,"eth","Type",2048,"ip",ipDecoderHandle)

    Read all of the IP packets from the PCAP file to the MATLAB® workspace.

    packets = pcapReaderObj.readAll()
    packets=1×35 struct array with fields:
    SNo
    Timestamp
    LinkType
    Protocol
    PacketLength
    Packet
    RawBytes

    Input Arguments

    collapse all

    PCAP file reader, specified as a pcapReader object.

    Name of the existing protocol decoder, specified as a character vector or a string scalar. The existing protocol decoder can be an Ethernet decoder, an eCPRI decoder, or any other newly added protocol decoder.

    Data Types: char | string

    Field name in the output structure of the existing protocol decoder, specified as a character vector or a string scalar. For more information about the field names of Ethernet and eCPRI protocol decoders, see the protocolPackets output of the read or readAll object functions.

    Data Types: char | string

    Value of the field name, specified as a nonnegative integer, character vector, or string scalar. If the fieldName input has this value, then this object function passes the payload to the upper-layer protocol decoder handle.

    Data Types: double | char | string

    Name of the upper-layer protocol decoder, specified as a character vector or a string scalar. To store the decoded packet of the upper-layer protocol decoder, the read or readAll object functions use this value to create a new field in the Packet field of the output decoded protocol packet structure.

    Data Types: char | string

    Upper-layer protocol decoder that decodes the payload of the existing protocol decoder and returns the decoded packet with the processed length, specified as a function handle. This code shows the syntax of this argument.

    [outputPacket,processedLength] = upperLayerDecoderFunction(existingProtocolPayload);
upperLayerDecoder = @upperLayerDeocderFunction
    The upperLayerDecoderFunction is the function that decodes the payload of the existing protocol decoder. The outputPacket output contains the decoded packet as a structure or a cell array of structures. The processedLength output is the number of decoded bytes. A negative value of the processed length indicates failed packet decoding. If packet decoding fails, the output decoded packet structure is empty.

    Data Types: function_handle

    Protocol fields and data types, specified as a two-column cell array that indicates the protocol fields and their respective data types. Specify these fields and data types as character vectors or string scalars. The first column of the cell array specifies the field name. The second column of the cell array specifies the data type of the corresponding field name. The valid values for the data type are numeric, string, and hexadecimal. This value specifies the fields (of the protocol decoder output structure) on which the read or readAll object functions can specify the packetFilter input. When you specify the packetFilter input of read or readAll object functions, this object function uses the protocolFields value for:

    • Tab completion of packetFilter string

    • Validating packetFilter string

    For more information about how to use this value to filter packets, see the packetFilter input of the read or readAll object functions.

    Data Types: cell

    References

    [1] Group, The Tcpdump. “Tcpdump/Libpcap Public Repository.” Accessed May 20, 2020. https://www.tcpdump.org.

    Version History

    Introduced in R2021b

    See Also

    Objects

    Functions