Wireshark Developer’s Guide
		Next

Wireshark Developer’s Guide

Version 4.7.0

Ulf Lamping, Graham Bloice

Table of Contents

Preface

1. Foreword

2. Who should read this document?

3. Acknowledgements

4. About this document

5. Where to get the latest copy of this document?

6. Providing feedback about this document

7. Typographic Conventions

7.1. Admonitions
7.2. Shell Prompt and Source Code Examples

I. Wireshark Build Environment

1. Introduction

1.1. Introduction

1.2. What Is Wireshark?

1.3. Supported Platforms

1.3.1. Unix And Unix-like Platforms
1.3.2. Microsoft Windows

1.4. Development And Maintenance Of Wireshark

1.4.1. Programming Languages Used
1.4.2. Open Source Software

1.5. Releases And Distributions

1.5.1. Binary Distributions
1.5.2. The Source Code Distribution

1.6. Automated Builds (GitLab CI)

1.6.1. What Do The Automated Builds Do?

1.7. Reporting problems and getting help

1.7.1. Website
1.7.2. Wiki
1.7.3. FAQ
1.7.4. Other sources
1.7.5. Q&A Site
1.7.6. Mailing Lists
1.7.7. Bug Database (GitLab Issues)
1.7.8. Reporting Problems
1.7.9. Reporting Crashes on UNIX-like platforms
1.7.10. Reporting Crashes on Windows platforms

2. Setup and Build Instructions

2.1. UN*X

2.1.1. Build environment setup
2.1.2. Building
2.1.3. Optional: Install
2.1.4. Optional: Create User’s and Developer’s Guide
2.1.5. Optional: Create an installable or source code package
2.1.6. Troubleshooting during the build and install on Unix

2.2. Windows

2.2.1. Using Microsoft Visual Studio
2.2.2. Using MinGW-w64 with MSYS2
2.2.3. Using WSL2 on a Windows Host (Beginner Friendly)
2.2.4. Cross-compilation using Linux

3. Work with the Wireshark sources

3.1. Introduction

3.2. The Wireshark Git repository

3.2.1. Git Naming Conventions

3.3. Browsing And Searching The Source Code

3.4. Obtaining The Wireshark Sources

3.4.1. Git Over SSH Or HTTPS
3.4.2. Development Snapshots
3.4.3. Official Source Releases

3.5. Update Your Wireshark Sources

3.5.1. Update Using Git

3.6. Build Wireshark

3.6.1. Building on Unix
3.6.2. Windows Native
3.6.3. Build Type

3.7. Run Your Version Of Wireshark

3.7.1. Unix-Like Platforms
3.7.2. Windows Native

3.8. Debug Your Version Of Wireshark

3.8.1. Wireshark Logging
3.8.2. Traps Set By Logging
3.8.3. Logging APIs
3.8.4. Unix-Like Platforms
3.8.5. Windows Native

3.9. Make Changes To The Wireshark Sources

3.10. Contribute Your Changes

3.10.1. Workflow for Contributions
3.10.2. Forking the Source Tree
3.10.3. Pulling from Upstream
3.10.4. Creating Merge Requests
3.10.5. Updating Merge Requests
3.10.6. Some Tips For A Good Patch
3.10.7. Writing a Good Commit Message
3.10.8. Code Requirements
3.10.9. Backporting A Change

3.11. Binary Packaging

3.11.1. Packaging Guidelines
3.11.2. Debian: .deb Packages
3.11.3. Red Hat: .rpm Packages
3.11.4. macOS: .dmg Packages
3.11.5. Windows: NSIS .exe Installer
3.11.6. Windows: PortableApps .paf.exe Package

3.12. Mime Types

3.12.1. Display Filter
3.12.2. Coloring Rules
3.12.3. Filter List
3.12.4. Column List

4. Tool Reference

4.1. Introduction

4.2. Chocolatey

4.3. CMake

4.4. GNU Compiler Toolchain (UNIX And UNIX-like Platforms)

4.4.1. gcc (GNU Compiler Collection)
4.4.2. gdb (GNU Project Debugger)
4.4.3. make (GNU Make)
4.4.4. Ninja

4.5. Microsoft compiler toolchain (Windows native)

4.5.1. Official Toolchain Packages And Alternatives
4.5.2. Visual C++ 2022 Community Edition
4.5.3. cl.exe (C Compiler)
4.5.4. link.exe (Linker)
4.5.5. Visual C++ Runtime “Redistributable” Files
4.5.6. Windows Platform SDK

4.6. Documentation Toolchain

4.6.1. Asciidoctor
4.6.2. DocBook XML and XSL
4.6.3. xsltproc

4.7. Debugger

4.7.1. Visual Studio Integrated Debugger
4.7.2. Debugging Tools For Windows

4.12. Git Powershell Extensions (Optional)

4.13. Git GUI Client (Optional)

4.14. Perl (Optional)

4.14.1. Windows

4.15. Windows: NSIS (Optional)

4.16. Windows: WiX Toolset (Optional)

4.17. Windows: PortableApps (Optional)

5. Library Reference

5.1. Introduction
5.2. Windows Automated Library Download
5.3. Qt
5.4. GLib And Supporting Libraries
5.5. c-ares
5.6. SMI (Optional)
5.7. zlib (Optional)
5.8. libpcap or Npcap (Optional, But Strongly Recommended)
5.9. GnuTLS (Optional)
5.10. Libgcrypt
5.11. Kerberos (Optional)
5.12. Lua (Optional)
5.13. MaxMindDB (Optional)
5.14. WinSparkle (Optional)

II. Wireshark Development

6. Introduction

6.1. Source overview
6.2. Coding Style
6.3. The GLib library

7. How Wireshark Works

7.1. Introduction
7.2. Overview
7.3. Capturing packets
7.4. Capture Files
7.5. Dissect packets

8. Packet Capture

8.1. Adding A New Capture Type To Libpcap

8.2. Adding Capture Interfaces And Log Sources Using Extcap

8.2.1. Extcap Command Line Interface
8.2.2. Extcap Arguments
8.2.3. Toolbar Controls

9. Packet Dissection

9.1. How packet dissection works

9.2. Adding a basic dissector

9.2.1. Setting up the dissector
9.2.2. Dissecting the protocol’s details
9.2.3. Improving the dissection information

9.3. How to add an expert item

9.4. How to handle transformed data

9.5. How to reassemble split packets

9.5.1. How to reassemble split UDP packets
9.5.2. How to reassemble split TCP Packets

9.6. How to tap protocols

9.6.1. How to produce protocol statistics (stats)
9.6.2. How to follow protocol streams

9.7. How to use conversations

9.8. idl2wrs: Creating dissectors from CORBA IDL files

9.8.1. What is it?
9.8.2. Why do this?
9.8.3. How to use idl2wrs
9.8.4. TODO
9.8.5. Limitations
9.8.6. Notes

10. Wiretap

10.1. Background
10.2. Creating a new wiretap module
10.3. Additional notes on adding support for reading new capture formats
10.4. Adding support for writing capture formats
10.5. Adding support for a new encapsulation type

11. Plugins

11.1. Dissector plugins

11.2. The directory for the plugin, and its files

11.2.1. CMakeLists.txt
11.2.2. plugin.rc.in

11.3. Changes to existing Wireshark files

11.3.1. Custom extension
11.3.2. Permanent addition

11.4. Development and plugins on Unix

11.5. How to plugin related interface options

11.5.1. Implement a plugin GUI menu
11.5.2. Implement interactions with the main interface
11.5.3. Implement a plugin specific toolbar

12. Lua Support in Wireshark

12.1. Introduction
12.2. Example: Creating a Menu with Lua
12.3. Example: Dissector written in Lua
12.4. Example: Listener written in Lua
12.5. Example: Lua scripts with shared modules

13. Wireshark’s Lua API Reference Manual

13.1. Utility Functions

13.1.1. Global Functions

13.2. GUI Support

13.2.1. ProgDlg
13.2.2. TextWindow
13.2.3. Global Functions

13.3. Functions For New Protocols And Dissectors

13.3.1. Dissector
13.3.2. DissectorTable
13.3.3. Pref
13.3.4. Prefs
13.3.5. Proto
13.3.6. ProtoExpert
13.3.7. ProtoField
13.3.8. Global Functions

13.4. Obtaining Dissection Data

13.4.1. Field
13.4.2. FieldInfo
13.4.3. Global Functions

13.5. Obtaining Packet Information

13.5.1. Address
13.5.2. Column
13.5.3. Columns
13.5.4. Conversation
13.5.5. NSTime
13.5.6. Pinfo
13.5.7. PrivateTable

13.6. Functions For Handling Packet Data

13.6.1. ByteArray
13.6.2. Tvb
13.6.3. TvbRange

13.7. Adding Information To The Dissection Tree

13.7.1. TreeItem

13.8. Post-Dissection Packet Analysis

13.8.1. Listener

13.9. Saving Capture Files

13.9.1. Dumper
13.9.2. PseudoHeader

13.10. Wtap Functions For Handling Capture File Types

13.10.1. Global Functions

13.11. Custom File Format Reading And Writing

13.11.1. CaptureInfo
13.11.2. CaptureInfoConst
13.11.3. File
13.11.4. FileHandler
13.11.5. FrameInfo
13.11.6. FrameInfoConst
13.11.7. Global Functions

13.12. Directory Handling Functions

13.12.1. Dir
13.12.2. Example
13.12.3. Example

13.13. Handling 64-bit Integers

13.13.1. Int64
13.13.2. UInt64

13.14. Binary encode/decode support

13.14.1. Struct

13.15. Gcrypt symmetric cipher functions

13.15.1. GcryptCipher
13.15.2. Global Functions

13.16. PCRE2 Regular Expressions

13.17. Bitwise Operations

14. User Interface

14.1. Introduction

14.2. The Qt Application Framework

14.2.1. User Experience Considerations
14.2.2. Qt Creator
14.2.3. Source Code Overview
14.2.4. Coding Practices and Naming Conventions
14.2.5. Other Issues and Information

14.3. Human Interface Reference Documents

15. Wireshark Tests

15.1. Quick Start

15.2. Test suite structure

15.2.1. Test Coverage And Availability
15.2.2. Suites, Cases, and Tests
15.2.3. pytest fixtures

15.3. Listing And Running Tests

15.4. Adding Or Modifying Tests

15.5. External Tests

15.5.1. Custom Fixtures

16. Creating ASN.1 Dissectors

16.1. About ASN.1

16.2. ASN.1 Dissector Requirements

16.2.1. Building An ASN.1-Based Plugin

16.3. Understanding Error Messages

16.4. Hand-Massaging The ASN.1 File

16.5. Command Line Syntax

16.6. Generated Files

16.7. Step By Step Instructions

16.8. Hints For Using Asn2wrs

16.8.1. ANY And Parameterized Types
16.8.2. Tagged Assignments
16.8.3. Untagged CHOICEs
16.8.4. Imported Module Name Conflicts

16.9. Simple ASN.1-Based Dissector

16.10. Conformance (.cnf) Files

16.10.1. Example .cnf File
16.10.2. Example packet-protocol-template.h File
16.10.3. Example packet-protocol-template.c File

16.11. Conformance File Directive Reference

16.11.1. #.END
16.11.2. #.EXPORTS
16.11.3. #.FN_BODY
16.11.4. #.MODULE_IMPORT, #.INCLUDE and #.IMPORT
16.11.5. #.MODULE_IMPORT
16.11.6. #.INCLUDE and #.IMPORT
16.11.7. #.NO_EMIT And #.USER_DEFINED
16.11.8. #.PDU and #.PDU_NEW
16.11.9. #.REGISTER and #.REGISTER_NEW

17. This Document’s License (GPL)

List of Figures

3.1. GitLab Workflow
7.1. Wireshark function blocks
13.1. A progress bar in action
13.2. A text window in action
13.3. An input dialog in action

List of Tables

1. Typographic Conventions
3.1. Build Types
8.1. Control packet:
8.2. Commands and application for controls
9.1. Standard callbacks for following streams
13.1. Default background colors
13.2. Default background colors

		Next
		Preface