Movatterモバイル変換

Npcap Reference Guide
Developing software with Npcap

Developing software with Npcap

Abstract

Writing software that captures or injects network traffic is easy with Npcap. This guide describes the Npcap SDK, WinPcap compatibility, and the Npcap API.

Using the Npcap SDK

To build software that uses Npcap, use the latest version of the Npcap Software Development Kit (SDK). The latest SDK can be downloaded onNpcap.org. Updates to the SDK are much less frequent than updates to the Npcap binaries.

Examples

Examples of applications using Npcap are availablein the Examples directory in the source distribution. Several of these examples are explored in more depth in thethe section called “Npcap Development Tutorial”.

Npcap developer Yang Luo has also provided an example:UserBridge, which is a tool to redirect all packets from one interface to another.

Updating WinPcap software to Npcap

For the most part, Npcap is completely compatible with software written for WinPcap. Minor changes need to be made tothe section called “DLL loading” and in some casesthe section called “Service name”. However, there have been many improvements to the libpcap API between the last release of WinPcap and the current release of Npcap. Reviewing the changes may help improve performance, reliability, and maintainability of software that uses Npcap.

Apart from the libpcap API, WinPcap exported a few functions used byWinDump that were related to porting a Unix-style tool to Windows but unrelated to packet capture. Those functions were not documented in the WinPcap documentation, have never been included in libpcap, and are therefore not in the Npcap API:getservent,endservent, andeproto_db.

One other function exported by WinPcap,wsockinit, is available via the Npcap API aspcap_wsockinit. It callsWSAStartup for Windows Sockets version 1.1 and ensures thatWSACleanup is called when the process ends.

How to detect what version Npcap/WinPcap you are using?

Sometimes, our user software needs to detect the existence of Npcap/WinPcap at install-time or run-time. Although Npcap's GUI installer has the ability to handle this, you may want to handle it by yourself in some conditions, like you run Npcap installer in silent-mode. The run-time detection is even more useful. Your software probably has some functions that rely on Npcap's particular features (like loopback capture). You need to know if you are running on top of Npcap or the legacy WinPcap to control whether to switch your functions on. Fortunately, Npcap provides you some methods to detect Npcap/WinPcap at install-time and run-time.

Npcap version

Npcap has a version number that is independent of WinPcap. The last release of WinPcap was version 4.1.3, but Npcap started over counting versions from 0.00. In order to make it clear to the installers and other software that Npcap is newer and more advanced, the executable“file version” was advanced to“5.0.0.000” at that point. The major version will always be“5” to distinguish Npcap from WinPcap. The minor version is Npcap's major version; the revision is Npcap's minor version; and the build number is an encoding of the build date. So a file version of“5.0.92.612” is Npcap 0.92, built on June 12th.

Install-time detection

You can check the existence ofC:\Program Files\Npcap\NPFInstall.exe to detect Npcap's existence. If Npcap exists, you can check the file version ofC:\Program Files\Npcap\NPFInstall.exe to detect Npcap e-version. The e-version also gives you the version. The NSIS code is shown below.$inst_ver is an e-version string like“5.0.7.424”

GetDllVersion "C:\Program Files\Npcap\NPFInstall.exe" $R0 $R1IntOp $R2 $R0 / 0x00010000IntOp $R3 $R0 & 0x0000FFFFIntOp $R4 $R1 / 0x00010000IntOp $R5 $R1 & 0x0000FFFFStrCpy $inst_ver "$R2.$R3.$R4.$R5"

You can check the installation options of an already installed Npcap by reading the registry key:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npcap\Parameters. The entries likeAdminOnly,LoopbackSupport,DltNull,Dot11Support,WinPcapCompatible, etc. areREG_DWORD type. A 0x00000001 value indicates the installation option isCHECKED.

Note: Prior to Npcap 0.93, these values were stored in theServices\npcap key directly.

Run-time detection

Npcap and WinPcap can be installed together on a system. Which capture library is used by the user software relies on the DLL loading path. If Npcap'swpcap.dll is loaded first, then you are using Npcap, vice versa. However, it's difficult and fragile to check the DLL loading path by yourself. Fortunately, you can usepcap_lib_version to get the Npcap/WinPcap version string.

char *pcap_version = pcap_lib_version();printf("%s", pcap_version);// Npcap output: "Npcap version 0.92, based on libpcap version 1.8.1"// WinPcap output: "WinPcap version 4.1.3"

Npcap requires thenpcap service to be running. A code sample from Nmap showing how to check the status of the service ishere.

For software that want to use Npcap first when Npcap and WinPcap coexist

Prerequisite: Uncheck theInstall Npcap in WinPcap API-compatible Mode option at install-time (which is by default).

DLL loading

Npcap installs its DLLs intoC:\Windows\System32\Npcap\ instead of WinPcap'sC:\Windows\System32\. Because of how Windows'DLL search path works, your application will use WinPcap first by default when Npcap and WinPcap coexist, asC:\Windows\System32\ is prior toC:\Windows\System32\Npcap\. So when Npcap and WinPcap coexist, an application that want to use Npcap instead of WinPcap must makeC:\Windows\System32\Npcap\ precedent to theC:\Windows\System32\ in the DLL search path. Here are two ways to modify this search path to make your application load Npcap's DLLs first, based on how your application links Npcap/WinPcap's library (wpcap.dll).

If the applicationimplicitly links`wpcap.dll`

Implicit linking means that either you specifiedwpcap.lib in yourProject Properties ->Configuration Properties ->Linker ->Input ->Additional Dependencies in Visual Studio, or specified#pragma comment(linker, "wpcap.lib") in your code.

You need to do the following two steps:

Specifywpcap.dll as a delay-loaded DLL: In Visual Studio, open theProject Properties window. Go to:Configuration Properties ->Linker ->Input ->Delay Loaded Dlls. Enterwpcap.dll in that option.
Before calling anywpcap.dll functions, callSetDllDirectory to addC:\Windows\System32\Npcap\ to DLL search path.

Here is an example called WinDump, a simple packet capture tool using Npcap/WinPcap. Andthis commit makes it able to use Npcap first when Npcap and WinPcap coexist.

If the applicationexplicitly links`wpcap.dll`

Explicit linking means that you explicitly calledLoadLibrary to loadwpcap.dll and calledGetProcAddress to get the function pointers.

You need to do the following one step:

Before callingLoadLibrary to loadwpcap.dll, callSetDllDirectory to addC:\Windows\System32\Npcap\ to DLL search path.

The functioninit_npcap_dll_path is provided in the following example:WinDump

Service name

Because Npcap is a NDIS 6 LWF filter driver it is designed to run at system boot, so software will generally not need to start it, unlike WinPcap which was often installed in a demand-start configuration.

Npcap uses service name“npcap” instead of WinPcap's“npf”, so applications usingnet start npf for starting service must change to this: runnet start npcap.

For software that uses Npcap loopback feature

Npcap 0.9983 and newer support loopback traffic capture and injection without requiring a particular installation option.

Npcap's loopback adapter device is reported bypcap_findalldevs() as“\Device\NPF_Loopback”. This name is always available even if“Legacy loopback support” was chosen at install time, which puts the name of the legacy loopback adapter in theLoopbackAdapter REG_SZ value of theHKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npcap\Parameters. Registry key.

Traffic captured and injected on the loopback adapter uses theDLT_NULL data link type, which consists of a 4-byte header in host byte order that is either 2 for IPv4 packets or 24 for IPv6 packets.

The MTU of“Npcap Loopback Adapter” is hard-coded to 65536 by Npcap. Software using Npcap should get this value automatically and no special handling is needed. This value is arbitrary and does not imply a limitation on the Windows loopback stack, so it may be possible to capture packets with a size larger than the adapter's MTU.

Don't try to make OID requests to“Npcap Loopback Adapter” exceptOID_GEN_MAXIMUM_TOTAL_SIZE (MTU). Those requests will still succeed like other adapters do, but they only make sense for NDIS adapters and Npcap doesn't even use the NDIS way to handle the loopback traffic. The only handled OID request by Npcap isOID_GEN_MAXIMUM_TOTAL_SIZE. If you query its value, you will always get 65550 (65536 + 14). If you try to set its value, the operation will always fail.

If you use IP Helper API to get adapter list, you will get an interface named like“Loopback Pseudo-Interface 1”. This interface is a DUMMY interface by Microsoft and can't be seen in NDIS layer. And it also takes the 127.0.0.1/::1 IP address. A good practice for software is replacing theAdapterName of the“Loopback Pseudo-Interface 1” entry with“NPF_Loopback”, as Nmap does in its enhancements to libdnet.

“Legacy loopback support” installs a copy of the Microsft KM-TEST loopback adapter named“Npcap Loopback Adapter” for software that expects to find the loopback adapter via ordinary Windows API calls. The features and operation are no different from standard loopback support, but the name of the adapter will be written to theLoopbackAdapter Registry value.

For software that uses Npcap raw 802.11 feature

Prerequisite: Check theSupport raw 802.11 traffic (and monitor mode) for wireless adapters option at install-time.

Steps

Install the latest version Npcap with theSupport raw 802.11 traffic (and monitor mode) for wireless adapters option checked in the installation wizard. With this option checked, Npcap will see packets withRadiotap + 802.11 headers for wireless adapters. Otherwise, Npcap will see packets withfake Ethernet headers for wireless adapters.
RunWlanHelper.exe withAdministrator privilege. If you use-i, follow the interactive prompts to choose your wireless adapter and select“Network Monitor” mode.WlanHelper.exe also supports parameters to be used in an API manner, runWlanHelper.exe -h for details.
Use the Npcap API from your user software as usual. For example, launch Wireshark and capture on the wireless adapter, viewingall 802.11 packets (data + control + management).
If you need to return to“Managed Mode”, runWlanHelper.exe again, following the prompts or selecting the appropriate command-line options to switch off the“Monitor Mode”.

Tips

You can useWlanHelper.exe tool to switch on the“Monitor Mode” in order to see802.11 control and management packets. You can also use thepcap_set_rfmon function within your code, as Wireshark does.
Switching on the“Monitor Mode” will disconnect your wireless network from the AP, you can switch back to“Managed Mode” using the sameWlanHelper.exe tool.
TheWlanHelper.exe tool is installed to“%SYSTEMROOT%\System32\Npcap” after installing Npcap.

Terminology

“Managed Mode” (for Linux) =“Extensible Station Mode” (aka“ExtSTA”, for Windows)

“Monitor Mode” (for Linux) =“Network Monitor Mode” (aka“NetMon”, for Windows)

“Master Mode” (for Linux) =“Extensible Access Point” (aka“ExtAP”, for Windows)

WlanHelper

WlanHelper is used to set/get the operation mode (like“Monitor Mode”) for a wireless adapter on Windows. WlanHelper tries to follow the grammar ofiwconfig, a wireless management tool for Linux. So if you renameWlanHelper.exe toiwconfig.exe, your command lines for WlanHelper will be exactly the same with the iwconfig tool.

WlanHelper's Usage

Note:WlanHelper must run underAdministrator privilege.

Interactive way

RunWlanHelper with the-i option.

Command-line API way

Runnetsh wlan show interfaces, get theName orGUID for the interface.
RunWlanHelper -h to see the man page.

Example 1. WlanHelper Man

C:\>WlanHelper.exeWlanHelper for Npcap 0.91 ( https://npcap.com )Usage: WlanHelper [Commands]or: WlanHelper {Interface Name or GUID} [Options]OPTIONS:mode                  : Get interface operation modemode <managed|monitor|master|..>  : Set interface operation modemodes                 : Get all operation modes supported by the interface, comma-separatedchannel               : Get interface channelchannel <1-14>            : Set interface channel (only works in monitor mode)freq                  : Get interface frequencyfreq <VALUE>              : Set interface frequency (only works in monitor mode)modu                  : Get interface modulationmodu <dsss|fhss|irbaseband|ofdm|hrdsss|erp|ht|vht|ihv (VALUE)|..> : Set interface modulationmodus                 : Get all modulations supported by the interface, comma-separatedCOMMANDS:-i                    : Enter the interactive mode-h                    : Print this help summary pageOPERATION MODES:managed   : The Extensible Station (ExtSTA) operation modemonitor   : The Network Monitor (NetMon) operation modemaster    : The Extensible Access Point (ExtAP) operation mode (supported from Windows 7 and later)wfd_device    : The Wi-Fi Direct Device operation mode (supported from Windows 8 and later)wfd_owner : The Wi-Fi Direct Group Owner operation mode (supported from Windows 8 and later)wfd_client    : The Wi-Fi Direct Client operation mode (supported from Windows 8 and later)802.11 MODULATIONS (https://en.wikipedia.org/wiki/IEEE_802.11):802.11-1997   : dsss, fhss802.11a   : ofdm802.11b   : dsss802.11g   : ofdm802.11n   : mimo-ofdm802.11ac  : mimo-ofdmEXAMPLES:WlanHelper Wi-Fi modeWlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da channel 11WlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da freq 2WlanHelper "Wireless Network Connection" mode monitorSEE THE MAN PAGE (https://github.com/nmap/npcap) FOR MORE OPTIONS AND EXAMPLES

An example:

Example 2. WlanHelper API Usage

C:\>netsh wlan show interfacesThere is 1 interface on the system:Name                   :<Wi-Fi>Description            : Qualcomm Atheros AR9485WB-EG Wireless Network AdapterGUID                   :<42dfd47a-2764-43ac-b58e-3df569c447da>Physical address       : a4:db:30:d9:3a:9aState                  : connectedSSID                   : LUO-PC_NetworkBSSID                  : d8:15:0d:72:8c:18Network type           : InfrastructureRadio type             : 802.11nAuthentication         : WPA2-PersonalCipher                 : CCMPConnection mode        : Auto ConnectChannel                : 1Receive rate (Mbps)    : 150Transmit rate (Mbps)   : 150Signal                 : 100%Profile                : LUO-PC_NetworkHosted network status  : Not availableC:\>WlanHelper.exe<wi-fi> modemanagedC:\>WlanHelper.exe<wi-fi> mode monitorSuccessC:\>WlanHelper.exe<wi-fi> modemonitorC:\>WlanHelper.exe<wi-fi> mode managedSuccessC:\>WlanHelper.exe<wi-fi> modemanaged