Wireshark插件开发指南.doc

Wireshark Plug-in development guide本文背景：在网络程序的编写过程中，你有可能需要定义某种数据协议；而在测试过程中，需要分析收到或发送的数据，这时候，你需要一个工具去捕获数据，解析数据。这就是Wireshark,但是，你需要编写插件完成这个工作。本文目的：插件开发的环境设置及开发过程。本文内容：1. Summary2. Develop Environment Setup2.1 Cygwin Installation2.2 Wireshark Source Code Build. 3. Plug-in Implementation3.1 Wireshark Architecture3.2 Main Process of Plug-in Development3.3 An Example - TSC Output Protocol Analyzer4. Plug-in Deployment & Use4.1 Deployment4.2 Use Plug-in5. Appendix. 85.1 Compile Error Information & Solution1. SummaryWireshark is a tool for capturing data from network card interface and interpreting it through protocol dissectors. If you want to investigate the network data packaged in some protocol, which is sent by your applications, Wireshark can handle it very well. Currently there are hundreds of build-in dissectors, like TCP, UDP, SMTP, etc. However, if the protocol used in your application is not supported by Wireshark, a new plug-in must be implemented.This document provides details on Wireshark plug-in development, including three sections: Environment Setup, Plug-in Development and Plug-in Deployment & Use.2. Develop Environment Setup2.1 Cygwin InstallationCygwin is a Linux-like environment for Windows. If you want to build Wireshark in Windows, you need to install Cygwin as it will use some tools in Cygwin.Download Link/setup.exeRun the setup.exe, and you can choose to download the installer package or install on-line directly. During the installation, a dialog will show you all the available tools for installation. There are some tools required for building Wireshark source code successfully.Tools Needed to SelectArchive/unzipDevel/bisonDevel/flexInterpreters/perlUtils/patchWeb/wgetCheck after InstallationA shortcut on desktop will be created if installation successful.2.2 Wireshark Source Code BuildWithout Wireshark source code, you can not compile your source code of plug-in successfully. So the first thing you need to do is getting Wireshark source code on hand.Download LinkYou can download any version of Wireshark source code from the link:/download/src/all-versions/The version I ever used to build successfully is Wireshark 0.99.5.Modify ConfigurationExtract the source code package to a directory, where there is a config.namke file. Modify the files as below (search the files with key words). Recommend to backup config.nmake file before any change.Key WordsValueActionsWIRESHARK_LIBSThe location of your Wireshark libraryMSVC_VARIANTYour version of Microsoft Visual Studio C+GTK1_DIR$(WIRESHARK_LIBS)gtk+use # to comment this line out as if you plan to use the latest version GTK 2GTK2_DIR$(WIRESHARK_LIBS)gtk2Default CYGWIN_PATHThe path of Cygwin bin directoryPYTHONThe path of pythonyou can install standalone version of python, or use the default python in CygwinbinMAKENSISThe path of MakeNsisuse # to comment this line out if you havent installed MakeNsisHHC_DIR$(PROGRAM_FILES)/HTML Help Workshop/use # to comment this line out if you havent installed Html Help WorkshopINSTALL1_DIRwireshark-gtk1use # to comment this line out if you dont want to generate GTK 1 versions Wireshark Table 1. Configuration ChangeVerify Whether All Tools Is AvailableOpen a command window, switch to the bin directory of your Visual Studio C+ (If use Visual S 2003, it will be C:Program FilesMicrosoft Visual Studio .NET 2003Vc7bin).Run vcvars32.bat in the command window. DONT CLOSE THIS COMMAND WINDOW AND ALL OTHER COMMANDS SHOULD BE EXECUTED IN THE SAME WINDOW!Then in the same command window, switch to the directory of Wireshark source code, and execute this command to verify tools.nmake f makefile.nmake verify_toolsNormally the result is as below.Figure 1. Result of Verify ToolsHttp Proxy SettingBefore downloading Wireshark library, you need to set HTTP proxy if you cant access the Wireshark library server directly.Create a new System Variable with the name HTTP_PROXY and the value as proxy profile (like /proxy.pac).Download the Wireshark LibraryExecute this command to download library with wget.nmake f makefile.nmake setupNormally it takes about 30 minutes to download all libraries. When it finishes, it will tell you its ready to build Wireshark now.Build WiresharkBefore building, execute this command to clean the temporary files of previous build.nmake f makefile.nmake distcleanExecute this command to build Wireshark.nmake f makefile.nmake allNormally it takes about 20 minutes to build successfully. If error happens, refer to Appendix 6.1.3. Plug-in Implementation3.1 Wireshark Architecture Wireshark can be divided into four main modules: Capture Core, WireTap, Protocol Interpreter and Dissector. Capture Core uses the common library WinPcap to capture data from different network (Ethernet, Ring, etc.); when got the data, WireTap is used to save it as a binary file; because the data is in binary, without Protocol Interpreter and Dissector, user can not understand the data. Here, Dissector can be build-in Dissector and plug-in Dissector. The following covers plug-in dissector development.Figure 2. Wireshark Architecture3.2 Main Process of Plug-in DevelopmentDefine Data Fields for Your ProtocolDefine a hf_register_info structure to contain all fields in Protocol, including field name, field name for filtering, field data type, field display style, etc.If some fields in your protocol need to be displayed as sub tree of another field, its required to define a gint array to save sub tree in protocol data panel.Registry ProtocolYou can use proto_register_protocol to registry your protocol name, after which it will allocate a protocol id for it.Bind Protocol with WiresharkConsider when a packet has been captured by Wireshark, how it knows what protocol analyzer to use. You can use plugin_reg_handoff to bind protocol with Wireshark. Firstly set the protocol name based on which your protocol works, for example, UDP, TCP, etc. Secondly, identify your protocol by setting some condition, for example, the first byte of your protocol packet is special value. If a protocol analyzer is matched with the captured packet, it will be used to interpret all the fields values in the packet.Protocol Analysis ProcessAs Wireshark already knows the protocol field structure, its easy to display all field values. The main logic in this step is displaying data in a GUI style.3.3 An Example - TSC Output Protocol AnalyzerIn this section, firstly we introduce a TSC output protocol, with which TSC outputs Market data and News to TSfCP and Thomson. Then, write the skeleton of plug-in for this protocol. TSC Output Protocol IntroductionTSC will output data packets containing all the following fields.Field NameField Size (Bits)CommentType8 Each packet will contain this TSC Packet Header.Sequence16Timestamp48Seconds32Million Seconds16Control Flag & Message Count8Line ID8This is one TSC Marketfeed message.One packet can contain several Marketfeed messages.Line Sequence16Line Message Count8Line Message Number8Message Length16Message DataMessage Length * 8Table 2. TSC ProtocolPlug-in ImplementationCreate a new tsc.c and implement it following these steps.Firstly, define data structure for above fields as below, static hf_register_info hf = /Field 1 &hf_tsc_type, Tsc Type, tsc.type, FT_UINT8, BASE_HEX, VALS(tsc_type_vals), 0x0, NULL, HFILL , /Field 2 &hf_tsc_sequence, Tsc Sequence, tsc.requence, FT_UINT16, BASE_HEX_DEC, NULL, 0x0, , HFILL , /Field nThen, registry TSC protocol,int proto_tsc = proto_register_protocol ( TSC Protocol, /* Display Name as Root of Tree */ TSC, /* Short name for Info Column*/ tsc /* Name for filter */ );Bind this protocol with Wireshark:/TSC protocol works based on UDP protocol.heur_dissector_add(udp,dissect_tsc_heur,proto_tsc);static gboolean dissect_tsc_heur(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree) guint8 packet_type = 0; packet_type = tvb_get_guint8(tvb, 0); if( packet_type != 0x01 & packet_type != 0x02 ) /* abort if it is not a TSC Data packet. */ return FALSE; else /* Interpret it */ dissect_tsc(tvb,pinfo,tree); return TRUE; Lastly, implement the protocol analyzer,static void dissect_tsc(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree) /Read the first field packet_type = tvb_get_guint8(tvb, 0); /Add the first field on the tree proto_tree_add_item(tsc_tree, hf_tsc_type, tvb, offset, 1, FALSE); /Move to next field offset += 1 ; proto_tree_add_item(tsc_tree, hf_tsc_sequence, tvb, offset, 2, TRUE); /Move to next field offset += 2 ; /other fields parserBuild Plug-inUnder directory plugins of Wireshark source code, create a new folder TSC and put tsc.c into it.; create a new text file named makefile.nmake with the content as below. (This file is for compile the tsc.c and its copied from other existed plug-in and change the plug-in name).include .config.nmakeCFLAGS=/DHAVE_CONFIG_H /I./. /I././wiretap $(GLIB_CFLAGS) /I$(PCAP_DIR)include -D_U_= $(LOCAL_CFLAGS)LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS)!IFDEF ENABLE_LIBWIRESHARKLINK_PLUGIN_WITH=.epanlibwireshark.libCFLAGS=/DHAVE_WIN32_LIBWIRESHARK_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS)OBJECTS=packet-tsc.obj tsc.dll tsc.exp tsc.lib : $(OBJECTS) $(LINK_PLUGIN_WITH) link -dll /out:tsc.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) $(GLIB_LIBS)!ENDIFclean: rm -f $(OBJECTS) tsc.dll tsc.exp tsc.lib *.pdbdistclean: cleanmaintainer-clean: distclean Under directory plugins of Wireshark source code, there is antohter file makefile.nmake needed to be changed for invoking the above file to build TSC plug-in.Now, you can build the whole Wireshark source code again. After about 20 minutes, you can find the tsc.dll under PluginsTSC.4. Plug-in Deployment & U