【wireshark】插件开发（五）：C插件

1. Wireshark对C插件的支持

每个解析器解码自己的协议部分, 然后把封装协议的解码传递给后续协议。

因此它可能总是从一个Frame解析器开始, Frame解析器解析捕获文件自己的数据包细节(如:时间戳), 将数据交给一个解码Ethernet头部的Ethernet frame解析器, 然后将载荷交给下一个解析器(如:IP), 如此等等. 在每一步, 数据包的细节会被解码并显示.

可以用两种可能的方式实现协议解析. 一是写一个解析器模块, 编译到主程序中, 这意味着它将永远是可用的. 另一种方式是实现一个插件(共享库/DLL), 它注册自身用于处理解析。

插件形式和内置形式的解析器之间的差别很小. 在Windows平台, 通过列于libwireshark.def中的函数, 我们可以访问有限的函数, 但它们几乎已经够用了.

比较大的好处是插件解析器的构建周期要远小于内置. 因此以插件开始会使最初的开发工作变得简单, 而最终代码的布署会和内置解析器一样。

另见 README.developer  文件doc/README.developer包含更多有关实现解析器(而且在某些情况下, 比本文档要新一些)的信息.

2. 编译构建C解析器

首先需要决定解析器是要以built-in方式，还是以plugin方式实现。plugin方式实现比较容易上手。

解析器初始化：

#include "config.h"
#include <epan/packet.h>

#define FOO_PORT 9877

static int proto_foo = -;

void
proto_register_foo(void)
{
    proto_foo = proto_register_protocol (
        "FOO Protocol", /* name       */
        "FOO",      /* short name */
        "foo"       /* abbrev     */
        );
}

首先include一些必需的头文件。proto_foo用来记录我们的协议，当将此解析器注册到主程序时，它的值将会更新。把所有非外部使用的变量和函数声明为static是一个好的编程实践，可以避免名字空间污染。一般情况下这不是问题，除非我们的解析器非常大，分成了多个文件。

我们#define了协议的UDP端口FOO_PORT。

现在我们已经有了与主程序交互所需的基本东西了。接下来实现2个解析器构建函数（dissector setup functions）。

首先调用proto_register_protocol()函数来注册协议。可以给它3个名字用来将来在不同的地方显示。比如full和short name用于“Preferences”和“Enabled protocols”对话框。abbrev name用于显示过滤器。

接下来我们需要handoff例程。

void
proto_reg_handoff_foo(void)
{
    static dissector_handle_t foo_handle;

    foo_handle = create_dissector_handle(dissect_foo, proto_foo);
    dissector_add_uint("udp.port", FOO_PORT, foo_handle);
}

首先创建一个dissector handle，它和foo协议及执行实际解析工作的函数关联。接下来将此handle与UDP端口号关联，以便主程序在看到此端口上的UDP数据时调用我们的解析器。

标准wireshark解析器习惯是把proto_register_foo()和proto_reg_handoff_foo()做为解析器代码的最后2个函数。

最后我们来编写一些解析器代码。目前将它做为基本的占位符。

static void
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
{
    col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
    /* Clear out stuff in the info column */
    col_clear(pinfo->cinfo,COL_INFO);
}

此函数用于解析交给它的packets。packet数据放在名为tvb的特殊缓存中。对此随着我们对协议细节了解的深入将会变得非常熟悉。packet_info结构包含有关协议的一般数据，我们应该在此更新信息。tree参数是细节解析发生的地方。

现在我们进行最小化的实现。第1行我们设置我们协议的文本，以示用户可以看到协议被识别了。另外唯一做的事情是清除INFO列中的所有数据，如果它正在被显示的话。

此时，我们已经准备好基本的解析器，可以进行编译和安装了。它什么也不做，除了识别协议并标识它。

为了编译此解析器并创建插件，除了packet-foo.c中的源代码，还有一堆必需的支持文件，它们是：

• Makefile.am - This is the UNIX/Linux makefile template
• CMakeLists.txt - 使用cmake编译时所需的脚本
• Makefile.common - This contains the file names of this plugin
• Makefile.nmake - This contains the Wireshark plugin makefile for Windows
• moduleinfo.h - This contains plugin version info
• moduleinfo.nmake - This contains DLL version info for Windows
• packet-foo.h, packet-foo.c - This is your dissector source
• plugin.rc.in - This contains the DLL resource template for Windows

这些文件的例子可以在plugins/gryphon中找到，把所有与gryphon相关的东西都改成foo即可。plugin.rc.in不需要改动，windows编译不需要的文件也不需要改动。

把以上文件准备好、修改好之后，cmd进入plugins/foo目录，运行

nmake -f Makefile.nmake xxx

来进行编译，就像编译wireshark源码一样。编译好之后生成foo.dll，将它拷贝到编译好的wireshark的plugins目录（可能会有中间目录，视情况）。

还可以修改plugins目录下面的Makefile.nmake文件，在PLUGIN_LIST中加入新插件的目录名，这样下次编译wireshark时会一起编译你的插件。

如果是在Mac OSX系统中编译插件(CMake方式)，需要修改主目录下的CMakeLists.txt，搜索plugin字符串，找到set(PLUGIN_SRC_DIRS下面的行，在路径中加入plugins/foo（plugins目录的Makefile.am文件可能不需要修改，其中SUBDIRS项中列出了各插件的源码目录） ；然后如同之前文章所述，进入build目录，执行make –j 6 plugins，即可编译插件们。

然后启动wireshark，打开Dissector Tables窗口，可以查到以下信息，说明wireshark已经正确加载我们的插件。

打开foo.pcap，效果如下图所示，此时没有协议解析树，只在报文列表中添加了协议名：

3. 完善C解析器

接下来可以做一些复杂一点的解析工作。最简单的事情是对载荷进行标记。

首先创建一个subtree用来放解析结果。这有助于在detailed display中更佳显示。对解析器的调用有2种情况。一种情况用于获取packet的摘要，另一种情况用于解析packet的细节。这两种情况由tree指针的不同来区别。如果tree指针为NULL，用于获取简略信息。如果是非NULL，则需要解析协议的各个细部。记住这些后，让我们来增强我们的解析器。

static void
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
{

    col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
    /* Clear out stuff in the info column */
    col_clear(pinfo->cinfo,COL_INFO);

    if (tree) { /* we are being asked for details */
        proto_item *ti = NULL;
        ti = proto_tree_add_item(tree, proto_foo, tvb, , -, ENC_NA);
    }
}

这里所做的是把一个subtree加入到解析中。此subtree会保存此协议的所有细节，且不会在不需要时弄乱显示。

我们还可以标记被此协议所消费的数据区域。在目前的情况下，这统治是传递过来的所有数据，因为我们假定此协议不再封装其他协议。因此，我们用proto_tree_add_item()往tree里添加新的节点，标识它的协议名，用tvb缓冲区做为数据，并消费此数据的0到最后1个字节（-1表示结束）。ENC_NA（not applicable）是编码参数。

在这些改变之后，在detailed display中就会有此协议的标识，且选中它将会高亮此packet的剩余内容。如下图所示：

现在，让我们进行下一步，添加一些协议解析。这一步我们需要创建2个表来帮助解析。这需要在proto_register_foo()函数中添加一些代码。

在proto_register_foo()的前面添加了2个static数组。这些数组在proto_register_protocol()调用之后被注册。

void
proto_register_foo(void)
{
    static hf_register_info hf[] = {
        { &hf_foo_pdu_type,
            { "FOO PDU Type", "foo.type",
            FT_UINT8, BASE_DEC,
            NULL, 0x0,
            NULL, HFILL }
        }
    };

    /* Setup protocol subtree array */
    static gint *ett[] = {
        &ett_foo
    };

    proto_foo = proto_register_protocol (
        "FOO Protocol", /* name       */
        "FOO",      /* short name */
        "foo"       /* abbrev     */
        );

    proto_register_field_array(proto_foo, hf, array_length(hf));
    proto_register_subtree_array(ett, array_length(ett));
}

变量hf_foo_pdu_type和ett_foo也需要在此文件的前面声明。

static int hf_foo_pdu_type = -;

static gint ett_foo = -;

现在我们可以用一些细节来增加协议的显示。

if (tree) { /* we are being asked for details */
  proto_item *ti = NULL;
  proto_tree *foo_tree = NULL;

  ti = proto_tree_add_item(tree, proto_foo, tvb, , -, ENC_NA);
  foo_tree = proto_item_add_subtree(ti, ett_foo);
  proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, , , ENC_BIG_ENDIAN);
}

现在解析开始看起来更加有趣了。我们开始破解此协议的第1个比特。packet起始处的一个字节数据定义了foo协议的packet type。

proto_item_add_subtree()调用往协议树中增加了一个子节点。此节点的展开是由ett_foo变量控制的。它会记住节点是否应该展开，在你在packet中移动的时候。所有后续的解析会添加到此树中，就像在接下来的调用中看到的那样。proto_tree_add_item向foo_tree添加了新项，并用hf_foo_pdu_type来控制此项的格式。pdu type是1个字节的数据，从0开始。我们假定它是网络字节序(也叫big endian），因此用ENC_BIG_ENDIAN。对于1个字节的数来说，没用字节序之说，但这是好的编程实践。

我们来看static数组中的定义细节：

• hf_foo_pdu_type - 此节点的索引
• FOO PDU Type - 此项的标识
• foo.type - 过滤用的字符串。它使我们可以在过滤器框中输入foo.type=1的语句
• FT_UINT8 - 指出此项是一个8bit的无符号整数。
• BASE_DEC - 对于整型来说，它令其打印为一个10进制数。还可以是16进制（BASE_HEX）或8进制（BASE_OCT）。

我们目前忽略结构中的其余成员。

如果此时编译并安装此插件，我们会看到它开始显示一些看起来有用的东西。

现在我们来完成这个简单协议的解析。我们需要添加更多的变量在hf数组中，以及更多的函数调用。

static int hf_foo_flags = -;
static int hf_foo_sequenceno = -;
static int hf_foo_initialip = -;
...

static void
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
{
    gint offset = ;

    ...

    if (tree) { /* we are being asked for details */
        proto_item *ti = NULL;
        proto_tree *foo_tree = NULL;

        ti = proto_tree_add_item(tree, proto_foo, tvb, , -, ENC_NA);
        foo_tree = proto_item_add_subtree(ti, ett_foo);
        proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_flags, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_sequenceno, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_initialip, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
    }
    ...
}

void
proto_register_foo(void) {
    ...
        ...
        { &hf_foo_flags,
            { "FOO PDU Flags", "foo.flags",
            FT_UINT8, BASE_HEX,
            NULL, 0x0,
            NULL, HFILL }
        },
        { &hf_foo_sequenceno,
            { "FOO PDU Sequence Number", "foo.seqn",
            FT_UINT16, BASE_DEC,
            NULL, 0x0,
            NULL, HFILL }
        },
        { &hf_foo_initialip,
            { "FOO PDU Initial IP", "foo.initialip",
            FT_IPv4, BASE_NONE,
            NULL, 0x0,
            NULL, HFILL }
        },
        ...
    ...
}
...

再修改一些细节，比如flag的位显示方式、foo协议树子节点字符串，packet列表中Info列的显示等等，最后效果如下：

4. 完整代码

/* packet-foo.c
 * Routines for Foo protocol packet disassembly
 * By zzq
 */

#include "config.h"

#include <epan/packet.h>
#include <epan/prefs.h>
//#include <epan/dissectors/packet-tcp.h>
#include "packet-foo.h"

#define FOO_PORT        9877
#define FOO_NAME        "Foo Protocol"
#define FOO_SHORT_NAME  "Foo"
#define FOO_ABBREV      "foo"

static int proto_foo = -;

static int hf_foo_pdu_type = -;
static int hf_foo_flags = -;
static int hf_foo_seqno = -;
static int hf_foo_ip = -;
static gint ett_foo = -;

static const value_string pkt_type_names[] =
{
    {, "Initilize"},
    {, "Terminate"},
    {, "Data"},
    {, NULL}
};

#define FOO_START_FLAG  0x01
#define FOO_END_FLAG    0x02
#define FOO_PRIOR_FLAG  0x04

static int hf_foo_start_flag    = -;
static int hf_foo_end_flag      = -;
static int hf_foo_prior_flag    = -;

void proto_register_foo(void);
void proto_reg_handoff_foo(void);
static int dissect_foo(tvbuff_t*, packet_info*, proto_tree*, void*);

void
proto_register_foo(void)
{
    static hf_register_info hf[] =
    {
        {
            &hf_foo_pdu_type,
            {
                "Type", "foo.type",
                FT_UINT8, BASE_DEC,
                VALS(pkt_type_names), 0x0,
                NULL, HFILL
            }
        },
        {
            &hf_foo_flags,
            {
                "Flags", "foo.flags",
                FT_UINT8, BASE_HEX, NULL, 0x0, NULL, HFILL
            }
        },
        {
            &hf_foo_start_flag,
            {
                "Start Flag", "foo.flags.start",
                FT_BOOLEAN, ,
                NULL, FOO_START_FLAG, NULL, HFILL
            }
        },
        {
            &hf_foo_end_flag,
            {
                "End Flag", "foo.flags.end",
                FT_BOOLEAN, ,
                NULL, FOO_END_FLAG, NULL, HFILL
            }
        },
        {
            &hf_foo_prior_flag,
            {
                "Priority Flag", "foo.flags.prior",
                FT_BOOLEAN, ,
                NULL, FOO_PRIOR_FLAG, NULL, HFILL
            }
        },
        {
            &hf_foo_seqno,
            {
                "Sequence Number", "foo.seq",
                FT_UINT16, BASE_DEC,
                NULL, 0x0, NULL, HFILL
            }
        },
        {
            &hf_foo_ip,
            {
                "IP Address", "foo.ip",
                FT_IPv4, BASE_NONE,
                NULL, 0x0, NULL, HFILL
            }
        }
    };

    static gint *ett[] = { &ett_foo };

    proto_foo = proto_register_protocol (
            FOO_NAME,
            FOO_SHORT_NAME,
            FOO_ABBREV);

    proto_register_field_array(proto_foo, hf, array_length(hf));
    proto_register_subtree_array(ett, array_length(ett));
}

static int
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void* data)
{
    guint8 packet_type = tvb_get_guint8(tvb, );

    col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
    /* Clear out stuff in the info column */
    col_clear(pinfo->cinfo,COL_INFO);
    col_add_fstr(pinfo->cinfo, COL_INFO, "Type %s",
        val_to_str(packet_type, pkt_type_names, "Unknown (0x%02x)"));

    /* proto details display */
    if(tree)
    {
        proto_item* ti = NULL;
        proto_tree* foo_tree = NULL;
        gint offset = ;

        ti = proto_tree_add_item(tree, proto_foo, tvb, , -, ENC_NA);
        proto_item_append_text(ti, ", Type %s",
            val_to_str(packet_type, pkt_type_names, "Unknown (0x%02x)"));
        foo_tree = proto_item_add_subtree(ti, ett_foo);
        proto_tree_add_item(foo_tree, hf_foo_pdu_type, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_flags, tvb, offset, , ENC_BIG_ENDIAN);
        proto_tree_add_item(foo_tree, hf_foo_start_flag, tvb, offset, , ENC_BIG_ENDIAN);
        proto_tree_add_item(foo_tree, hf_foo_end_flag, tvb, offset, , ENC_BIG_ENDIAN);
        proto_tree_add_item(foo_tree, hf_foo_prior_flag, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_seqno, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
        proto_tree_add_item(foo_tree, hf_foo_ip, tvb, offset, , ENC_BIG_ENDIAN);
        offset += ;
    }

    return tvb_reported_length(tvb);
}

void
proto_reg_handoff_foo(void)
{
    static dissector_handle_t foo_handle;

    foo_handle = new_create_dissector_handle(dissect_foo, proto_foo);
    dissector_add_uint("udp.port", FOO_PORT, foo_handle);
}

5. 参考

Wireshark开发指南第9章“Add a basic dissector”