Npcap Users' Guide

You may notice that Npcap has several version strings. The installer name can be something like npcap-0.07-r5.exe. “0.07” is the version number, and “r5” is the revision number. We use a version number less than “1.00” to imply that it's still a beta release. This naming follows the Nmap's convension. However, WinPcap follows a different version system. It has three dotted figures like “4.1.3”, which is more Wireshark-like. One thing you need to know here is that Npcap starts the development based on the latest WinPcap “4.1.3”. So any Npcap release is more advanced than WinPcap's latest release. Another thing needs to notice is that, the “0.07” version number can be obtained from the pcap_lib_version function. The “r5” revision number only appears in the installer filename, it doesn't show its existence in any code or functions. So you'd better not determine anything based on Npcap revision number. Just use the latest release.

The executable file version (aka e-version in this document) is another thing we need to notice. A e-version has four dotted figures on Windows. Npcap's e-version is something like “5.0.7.424”. “5” here is used to advance Npcap version than the legacy WinPcap's e-version “4.1.0.2980” because “5.0.7.424” is larger than “4.1.0.2980”. The legacy WinPcap installer and Wireshark uses e-version to check the version of WinPcap. Usually these legacy codes don't even know Npcap. So Npcap needs to make them simply think Npcap is a newer version of WinPcap. “0” and “7” in Npcap's e-version corresponds to Npcap's version “0.07”. “424” means that this release is built at date “4.24” (aka 24th, April). When Npcap version jumps to a new version (like from “0.06” to “0.07”), the e-version will also change (like from “0.6.0.301” to “0.7.0.424”). A revision update won't cause a change of version or e-version.

You can check the existence of C:\Program Files\Npcap\NPFInstall.exe to detect Npcap's existence. If Npcap exists, you can check the file version of C:\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 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF
IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $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\npf (WinPcap compatible mode) or HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npcap (Non-WinPcap compatible mode). the entries like AdminOnly, Loopback, DltNull,Dot11Support, VlanSupport, WinPcapCompatible, etc. show the installation options. Loopback is REG_SZ type. A non-NULL value indicates the option is CHECKED. All other entries are REG_DWORD type. A 0x00000001 value indicates the option is CHECKED.

Npcap and WinPcap can be installed together on a symtem. Which capture library is used by the user software relies on the DLL loading path. If Npcap's wpcap.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 use pcap_lib_version to get the Npcap/WinPcap version string.

char *pcap_version = pcap_lib_version();
printf("%s", pcap_version);
// Npcap output:
// Npcap version 0.07
//
// WinPcap output:
// WinPcap version 4.1.3

Considering Npcap has different driver service name in different modes, we provide a way to get the current service name: Npcap exports a pcap_get_servicename function in its libpcap API. It returns the string of Npcap service name (aka %SERVICE_NAME%), which can be used to start the service using net start %SERVICE_NAME% command. %SERVICE_NAME% is NPF if Npcap is installed in “WinPcap Compatible Mode” and NPCAP if Npcap is installed at “Non-WinPcap Compatible Mode” (Notice: the returned string is upper-case, and you don't need to free its memory). You need to dynamically import this function if you want to call it because WinPcap doesn't have this function and it's obviously not in the WinPcap SDK. The C code of the pcap_get_servicename usage is shown below.

typedef char* (__cdecl *MY_PCAP_GET_SERVICENAME) ();

HINSTANCE hinstLib;
// Get a handle to the wpcap DLL module.
hinstLib = LoadLibrary(TEXT("wpcap.dll"));
MY_PCAP_GET_SERVICENAME pcap_get_servicename;
char *servicename_buf;

// If the handle is valid, try to get the function address.  
if (hinstLib != NULL)
{
	pcap_get_servicename = (MY_PCAP_GET_SERVICENAME)GetProcAddress(hinstLib, "pcap_get_servicename");
	// If the function address is valid, call the function.  

	if (pcap_get_servicename != NULL)
	{
		printf("Notice: You are using Npcap.\n");
		servicename_buf = pcap_get_servicename();
		// servicename_buf = "NPF" or "NPCAP"
		printf("Npcap service name: %s\n", servicename_buf);
	}
	else
	{
		printf("Notice: You are using WinPcap.\n");
	}

	// Free the DLL module.  
	FreeLibrary(hinstLib);
}
else
{
	printf("Notice: Neither Npcap nor WinPcap is installed.\n");
}

“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 is used to set/get the operation mode (like “Monitor Mode”) for a wireless adapter on Windows. WlanHelper tries to follow the grammar of iwconfig, a wireless management tool for Linux. So if you rename WlanHelper.exe to iwconfig.exe, your command lines for WlanHelper will be exactly the same with the iwconfig tool.

C:\> WlanHelper.exe
WlanHelper for Npcap 0.07 (http://npcap.org)
Usage: WlanHelper {Interface Name or GUID} [Options]
Options:
  mode: get interface operation mode
  mode <managed|monitor|master|wfd_device|wfd_owner|wfd_client>: set interface operation mode
  modes: get all operation modes supported by the interface, comma-separated
  channel: get interface channel
  channel <1-11>: set interface channel (only works at monitor mode)
  freq: get interface frequency
  freq <0-200>: set interface frequency (only works at monitor mode)
Operation Modes:
  managed - the Extensible Station (ExtSTA) operation mode
  monitor - the Network Monitor (NetMon) operation mode
  master - the Extensible Access Point (ExtAP) operation mode (supported for Windows 7 and later)
  wfd_device - the Wi-Fi Direct Device operation mode (supported for Windows 8 and later)
  wfd_owner - the Wi-Fi Direct Group Owner operation mode (supported for Windows 8 and later)
  wfd_client - the Wi-Fi Direct Client operation mode (supported for Windows 8 and later)
Examples:
  WlanHelper wi-fi mode
  WlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da channel 11
  WlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da freq 2
See the MAN Page (https://github.com/nmap/npcap) for more options and examples
        

C:\> netsh wlan show interfaces

There is 1 interface on the system:

    Name                   : Wi-Fi
    Description            : Qualcomm Atheros AR9485WB-EG Wireless Network Adapter
    GUID                   : 42dfd47a-2764-43ac-b58e-3df569c447da
    Physical address       : a4:db:30:d9:3a:9a
    State                  : connected
    SSID                   : LUO-PC_Network
    BSSID                  : d8:15:0d:72:8c:18
    Network type           : Infrastructure
    Radio type             : 802.11n
    Authentication         : WPA2-Personal
    Cipher                 : CCMP
    Connection mode        : Auto Connect
    Channel                : 1
    Receive rate (Mbps)    : 150
    Transmit rate (Mbps)   : 150
    Signal                 : 100%
    Profile                : LUO-PC_Network

    Hosted network status  : Not available

C:\> WlanHelper.exe wi-fi mode
managed
C:\> WlanHelper.exe wi-fi mode monitor
Success
C:\> WlanHelper.exe wi-fi mode 
monitor
C:\> WlanHelper.exe wi-fi mode managed
Success
C:\> WlanHelper.exe wi-fi mode
managed
        

The current Npcap installation options by default are (for both “GUI Mode” and “Silent Mode”):

/admin_only=no /loopback_support=yes /dlt_null=no /dot11_support=no /vlan_support=no /winpcap_mode=no

Default options for Npcap installer GUI can be changed. An example is:

npcap-nmap-0.07.exe /admin_only=no /loopback_support=yes /dlt_null=no /dot11_support=no /vlan_support=no /winpcap_mode=yes

or even simpler:

npcap-nmap-0.07.exe /winpcap_mode=yes

As the default option of /winpcap_mode is no. Running the installer directly without options will see Install Npcap in WinPcap API-compatible Mode UNCHECKED by default in the “Installation Options” page. However, the above two commands will launch the installer GUI, and in the “Installation Options” page, the Install Npcap in WinPcap API-compatible Mode option will be CHECKED by default.

An example of changing option feature for silent installation is:

npcap-nmap-0.07.exe /S /admin_only=no /loopback_support=yes /dlt_null=no /dot11_support=no /vlan_support=no /winpcap_mode=yes

Npcap has its own SDK for “Non-WinPcap Compatible Mode”. By using it, your software will run under “Non-WinPcap Compatible Mode”. We don't update the SDK as frequently as the binaries. The latest SDK is Npcap SDK 0.07 r9.

If you only want to build your software under “WinPcap Compatible Mode” (which is NOT recommended), please use the legacy WinPcap 4.1.2 Developer's Pack instead.

This document currently only addresses the Npcap particular features. It doesn't show you the basics about the general WinPcap usage. As Npcap shares the libpcap API with WinPcap, you can always refer to the WinPcap documentation for general usage of Npcap.

You can refer to WinPcap's examples to see the usage.

I also provided an example: UserBridge, which is a tool to redirect all packets from an interface to another.