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. Lua Support in Wireshark

11.1. Introduction
11.2. Example: Creating a Menu with Lua
11.3. Example: Dissector written in Lua
11.4. Example: Listener written in Lua
11.5. Example: Lua scripts with shared modules

12. Wireshark’s Lua API Reference Manual

12.1. Utility Functions

12.1.1. Global Functions

12.2. GUI Support

12.2.1. ProgDlg
12.2.2. TextWindow
12.2.3. Global Functions

12.3. Functions For New Protocols And Dissectors

12.3.1. Dissector
12.3.2. DissectorTable
12.3.3. Pref
12.3.4. Prefs
12.3.5. Proto
12.3.6. ProtoExpert
12.3.7. ProtoField
12.3.8. Global Functions

12.4. Obtaining Dissection Data

12.4.1. Field
12.4.2. FieldInfo
12.4.3. Global Functions

12.5. Obtaining Packet Information

12.5.1. Address
12.5.2. Column
12.5.3. Columns
12.5.4. Conversation
12.5.5. NSTime
12.5.6. Pinfo
12.5.7. PrivateTable

12.6. Functions For Handling Packet Data

12.6.1. ByteArray
12.6.2. Tvb
12.6.3. TvbRange

12.7. Adding Information To The Dissection Tree

12.7.1. TreeItem

12.8. Post-Dissection Packet Analysis

12.8.1. Listener

12.9. Saving Capture Files

12.9.1. Dumper
12.9.2. PseudoHeader

12.10. Wtap Functions For Handling Capture File Types

12.10.1. Global Functions

12.11. Custom File Format Reading And Writing

12.11.1. CaptureInfo
12.11.2. CaptureInfoConst
12.11.3. File
12.11.4. FileHandler
12.11.5. FrameInfo
12.11.6. FrameInfoConst
12.11.7. Global Functions

12.12. Directory Handling Functions

12.12.1. Dir
12.12.2. Example
12.12.3. Example

12.13. Handling 64-bit Integers

12.13.1. Int64
12.13.2. UInt64

12.14. Binary encode/decode support

12.14.1. Struct

12.15. Gcrypt symmetric cipher functions

12.15.1. GcryptCipher
12.15.2. Global Functions

12.16. PCRE2 Regular Expressions

12.17. Bitwise Operations

13. User Interface

13.1. Introduction

13.2. The Qt Application Framework

13.2.1. User Experience Considerations
13.2.2. Qt Creator
13.2.3. Source Code Overview
13.2.4. Coding Practices and Naming Conventions
13.2.5. Other Issues and Information

13.3. Human Interface Reference Documents

14. Wireshark Tests

14.1. Quick Start

14.2. Test suite structure

14.2.1. Test Coverage And Availability
14.2.2. Suites, Cases, and Tests
14.2.3. pytest fixtures

14.3. Listing And Running Tests

14.4. Adding Or Modifying Tests

14.5. External Tests

14.5.1. Custom Fixtures

15. Creating ASN.1 Dissectors

15.1. About ASN.1

15.2. ASN.1 Dissector Requirements

15.2.1. Building An ASN.1-Based Plugin

15.3. Understanding Error Messages

15.4. Hand-Massaging The ASN.1 File

15.5. Command Line Syntax

15.6. Generated Files

15.7. Step By Step Instructions

15.8. Hints For Using Asn2wrs

15.8.1. ANY And Parameterized Types
15.8.2. Tagged Assignments
15.8.3. Untagged CHOICEs
15.8.4. Imported Module Name Conflicts

15.9. Simple ASN.1-Based Dissector

15.10. Conformance (.cnf) Files

15.10.1. Example .cnf File
15.10.2. Example packet-protocol-template.h File
15.10.3. Example packet-protocol-template.c File

15.11. Conformance File Directive Reference

15.11.1. #.END
15.11.2. #.EXPORTS
15.11.3. #.FN_BODY
15.11.4. #.MODULE_IMPORT, #.INCLUDE and #.IMPORT
15.11.5. #.MODULE_IMPORT
15.11.6. #.INCLUDE and #.IMPORT
15.11.7. #.NO_EMIT And #.USER_DEFINED
15.11.8. #.PDU and #.PDU_NEW
15.11.9. #.REGISTER and #.REGISTER_NEW

16. This Document’s License (GPL)

List of Figures

3.1. GitLab Workflow
7.1. Wireshark function blocks
12.1. A progress bar in action
12.2. A text window in action
12.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
12.1. Default background colors
12.2. Default background colors

		Next
		Preface