forked from nmap/npcap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnpcap-intro.xml
262 lines (221 loc) · 14.8 KB
/
npcap-intro.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<sect1 id="npcap-intro">
<title>Introduction</title>
<para>This Manual describes the programming interface and the source code of
Npcap. It provides detailed descriptions of the functions and structures
exported to programmers, along with complete documentation of the Npcap
internals. Several tutorials and examples are provided as well.</para>
<sect2 id="npcap-description">
<title>What is Npcap?</title>
<para>Npcap is an architecture for packet capture and network analysis for
Windows operating systems, consisting of a software library and a network
driver.</para>
<para>Most networking applications access the network through widely-used
operating system primitives such as sockets. It is easy to access data on
the network with this approach since the operating system copes with the
low level details (protocol handling, packet reassembly, etc.) and
provides a familiar interface that is similar to the one used to read and
write files.</para>
<para>Sometimes, however, the <quote>easy way</quote> is not up to the task,
since some applications require direct access to packets on the network.
That is, they need access to the <quote>raw</quote> data on the network
without the interposition of protocol processing by the operating
system.</para>
<para>The purpose of Npcap is to give this kind of access to Windows
applications. It provides facilities to:</para>
<itemizedlist>
<listitem>capture raw packets, both the ones destined to the machine where
it's running and the ones exchanged by other hosts (on shared media)</listitem>
<listitem>filter the packets according to user-specified rules before
dispatching them to the application</listitem>
<listitem>transmit raw packets to the network</listitem>
<listitem>gather statistical information on the network traffic</listitem>
</itemizedlist>
<para>This set of capabilities is obtained by means of a device driver,
which is installed inside the networking portion of the Windows kernel,
plus a couple of DLLs.</para>
<para>All of these features are exported through a powerful programming
interface, easily usable by applications. The main goal of this manual is
to document this interface, with the help of several examples.</para>
<sect3>
<title>What kind of programs use Npcap?</title>
<para>The Npcap programming interface can be used by many types of
network tools for analysis, troubleshooting, security and monitoring.
In particular, classical tools that rely on Npcap are:</para>
<itemizedlist>
<listitem>network and protocol analyzers</listitem>
<listitem>network monitors</listitem>
<listitem>traffic loggers</listitem>
<listitem>traffic generators</listitem>
<listitem>user-level bridges and routers</listitem>
<listitem>network intrusion detection systems (NIDS)</listitem>
<listitem>network scanners</listitem>
<listitem>security tools</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>What Npcap can't do</title>
<para>Npcap receives and sends the packets independently from the host
protocols, like TCP/IP. This means that it isn't able to block, filter or
manipulate the traffic generated by other programs on the same machine: it
simply <quote>sniffs</quote> the packets that transit on the wire. Therefore, it does not
provide the appropriate support for applications like traffic shapers, QoS
schedulers and personal firewalls. </para>
</sect3>
</sect2>
<sect2 id="npcap-winpcap">
<title>Npcap and WinPcap</title>
<para>Npcap is an update of <ulink role="hidepdf" url="http://www.winpcap.org/">WinPcap</ulink>
to the <ulink role="hidepdf" url="https://msdn.microsoft.com/en-us/library/windows/hardware/ff565492(v=vs.85).aspx">NDIS 6 Light-Weight Filter (LWF)</ulink> API.
It supports <command>Windows Vista, 7, 8 and 10</command>. It is developed
by the <ulink role="hidepdf" url="http://nmap.org/">Nmap Project</ulink>
as a continuation of the project started by Yang Luo
under <ulink role="hidepdf" url="https://www.google-melange.com/gsoc/project/details/google/gsoc2013/hsluoyz/5727390428823552">Google Summer of Code 2013</ulink> and
<ulink role="hidepdf" url="https://www.google-melange.com/gsoc/project/details/google/gsoc2015/hsluoyz/5723971634855936">2015</ulink>.
It also received many helpful tests from <ulink role="hidepdf" url="https://www.wireshark.org/">Wireshark</ulink>
and <ulink role="hidepdf" url="http://www.netscantools.com/">NetScanTools</ulink>.
</para>
<sect3 id="npcap-features">
<title>Feature comparison with WinPcap</title>
<para>Npcap carries on the WinPcap legacy, but is not without its own
innovations. Here are some of the most exciting improvements and new
features that Npcap adds:</para>
<itemizedlist>
<listitem><para><emphasis>NDIS 6 Support</emphasis>: Npcap makes use of the new NDIS Lightweight Filter driver in
Windows Vista and later. This driver type is faster and has less overhead
than the legacy <ulink role="hidepdf" url="https://msdn.microsoft.com/en-us/library/windows/hardware/ff557012(v=vs.85).aspx">NDIS 5 Intermediate Driver</ulink>
type used by WinPcap.
</para></listitem>
<listitem><para><emphasis>Latest libpcap API Support</emphasis>: Npcap provides support
for the latest <ulink role="hidepdf" url="https://github.com/the-tcpdump-group/libpcap">libpcap API</ulink>
by accepting libpcap as a <ulink role="hidepdf" url="https://git-scm.com/docs/git-submodule">Git submodule</ulink>.
The latest libpcap 1.8 has integrated more fascinating features and functions than the
<ulink role="hidepdf" url="https://www.winpcap.org/misc/changelog.htm">deprecated libpcap 1.0.0 shipped by WinPcap</ulink>.
Moreover, since Linux already has a good support for latest libpcap API, using
Npcap on Windows facilitates your software to base on the same API on both Windows and Linux.</para></listitem>
<listitem><para><emphasis><quote>Admin-only Mode</quote> Support</emphasis>: Npcap supports to restrict its
use to Administrators for safety purpose. If Npcap is installed with
the option <quote>Restrict Npcap driver's access to Administrators only</quote> checked,
when a non-Admin user tries to start a user software (Nmap, Wireshark, etc),
the <ulink role="hidepdf" url="http://windows.microsoft.com/en-us/windows/what-is-user-account-control#1TC=windows-7">User Account Control (UAC)</ulink>
dialog will prompt asking for Administrator privilege. Only when the end
user chooses Yes, the driver can be accessed. This is similar to UNIX
where you need root access to capture packets.</para></listitem>
<listitem><para><emphasis>Loopback Packet Capture</emphasis>: Npcap is able to
see Windows loopback packets using the
<ulink role="hidepdf" url="https://msdn.microsoft.com/en-us/library/windows/desktop/aa366510(v=vs.85).aspx">
Windows Filtering Platform (WFP)</ulink>. After installation, Npcap will create an
adapter named <quote>Npcap
Loopback Adapter</quote> for you. If you are a Wireshark user, choose this adapter
to capture, you will see all loopback traffic the same way as other
non-loopback adapters. Try it by typing in commands like <command>ping 127.0.0.1</command>
(IPv4) or <command>ping ::1</command> (IPv6).</para></listitem>
<listitem><para><emphasis>Loopback Packets Injection</emphasis>: Besides loopback packets
capturing, Npcap can also send out loopback packets using the
<ulink role="hidepdf" url="https://msdn.microsoft.com/en-us/library/windows/hardware/ff556958(v=vs.85).aspx">Winsock Kernel (WSK)</ulink>
technique. A user software (e.g. Nmap) can just send packets
out using <quote>Npcap Loopback Adapter</quote> like other adapters.
<quote>Npcap Loopback Adapter</quote>
will automatically remove the packet's Ethernet header and
inject the payload into Windows TCP/IP stack.</para></listitem>
<listitem><para><emphasis>Raw 802.11 Packets Capture Support</emphasis>: Npcap is able to see
<emphasis>802.11</emphasis> packets instead of <emphasis>fake Ethernet</emphasis> packets on ordinary wireless
adapters. You need to select the <option>Support raw 802.11 traffic (and monitor
mode) for wireless adapters</option> option in the installation wizard to enable
this feature. When your adapter is in <quote>Monitor Mode</quote>, Npcap will supply all
<emphasis>802.11 data + control + management</emphasis> packets with radiotap headers. When
your adapter is in <quote>Managed Mode</quote>, Npcap will only supply <emphasis>Ethernet</emphasis>
packets. Npcap directly supports to use Wireshark to capture in <quote>Monitor Mode</quote>.
Meantime, Npcap also provides the <filename>WlanHelper.exe</filename>
tool to help you switch to <quote>Monitor Mode</quote> on your own. See more details
about this feature in section
<quote><link linkend="npcap-feature-dot11" endterm="npcap-feature-dot11.title"/></quote>.
See more details about radiotap here:
<ulink role="hidepdf" url="http://www.radiotap.org/">http://www.radiotap.org/</ulink></para></listitem>
<listitem><para><emphasis><quote>WinPcap API-compatible Mode</quote>
Support</emphasis>: <quote>WinPcap API-compatible Mode</quote> makes Npcap a
strict WinPcap replacement by using the same DLL location and service name as
WinPcap. This is useful for testing or migrating from software that only uses
WinPcap, but because Npcap is masquerading as WinPcap, software will not be
able to be aware of and use Npcap's newer features. It's notable that before
installing in this mode, any existing WinPcap installation will be
uninstalled and replaced.
</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Purpose of this manual</title>
<para>The purpose of this manual is to provide a comprehensive and easy way
to browse the documentation of the Npcap architecture. You will find
three main sections: <xref linkend="npcap-users-guide" />,
<xref linkend="npcap-devguide" />,
and <xref linkend="npcap-internals" />.</para>
<para><xref linkend="npcap-users-guide" /> is for end users of Npcap, and
primarily concerns installation options, hardware compatibility, and bug
reporting procedures.</para>
<para><xref linkend="npcap-devguide" /> is for programmers who need to use
Npcap from an application: it contains information about functions and
data structures exported by the Npcap API, a manual for writing packet
filters, and information on how to include it in an application. A
tutorial with several code samples is provided as well; it can be used to
learn the basics of the Npcap API using a step-by-step approach, but it
also offers code snippets that demonstrate advanced features.</para>
<para><xref linkend="npcap-internals" /> is intended for Npcap developers
and maintainers, or for people who are curious about how this system
works: it provides a general description of the Npcap architecture and
explains how it works. Additionally, it documents the complete device
driver structure, the source code, the Packet.dll interface and the
low-level Npcap API. If you want to understand what happens inside Npcap
or if you need to extend it, this is the section you will want to
read.</para>
</sect2>
<sect2>
<title>Terminology</title>
<para>We call Npcap an <wordasword>architecture</wordasword> rather than
<wordasword>library</wordasword> because packet capture is a low level
mechanism that requires a strict interaction with the network adapter and
with the operating system, in particular with its networking
implementation, so a simple library is not sufficient.</para>
<para>For consistency with the literature, we will use the term
<wordasword>packet</wordasword> even though
<wordasword>frame</wordasword> is more accurate since the capture process
is done at the data-link layer and the data-link header is included in
the captured data.</para>
</sect2>
<sect2 id="npcap-license">
<title>Npcap License</title>
<para>Even though Npcap source code is publicly available for review, it is
not open source software and my not be redistributed without special
permission from the Nmap Project. The
<ulink url="https://github.com/nmap/npcap/blob/master/LICENSE">Npcap License</ulink>
allows end users to download, install, and use Npcap from our site for
free. Software providers (open source or otherwise) which want to use
Npcap functionality are welcome to point their users to npcap.org for
those users to download and install.</para>
<para>We fund the Npcap project by selling licenses to companies who wish
to redistribute Npcap within their products. The
<ulink url="https://nmap.org/npcap/oem/">Npcap OEM edition</ulink> allows
companies to silently and seamlessly install Npcap during their product's
installation rather than asking users to download and install Npcap
themselves. The Npcap OEM commercial license also includes support,
updates and indemnification. This is similar to the commercial licenses
we offer for embedding <ulink url="https://nmap.org/">Nmap</ulink> in
commercial software. More details are available from <ulink
url="https://nmap.org/npcap/oem/">the Npcap OEM page</ulink>.</para>
</sect2>
<sect2 id="npcap-download">
<title>Obtaining Npcap</title>
<para>The latest Npcap release can always be found
<ulink url="https://nmap.org/npcap/#download">on the Npcap
website</ulink> as an executable installer and as a source code
archive.</para>
</sect2>
<sect2 id="npcap-guide-copyright">
<title>Acknowledgements and copyright</title>
<para>Portions of this guide were adapted from the WinPcap documentation.
Copyright © 2002-2005 Politecnico di Torino. Copyright ©
2005-2010 CACE Technologies. Copyright © 2010-2013 Riverbed
Technology. Copyright © 2018 Insecure.Com, LLC. All rights
reserved.</para>
</sect2>
</sect1>