diff --git a/docs/scripting.xml b/docs/scripting.xml index 5ab19db86..0aa9ff4a5 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -1202,65 +1202,67 @@ socket:close() Raw packet network I/O raw packetsin NSE - For those cases where the connection-oriented approach is too inflexible, - NSE provides script developers with a more powerful option: - raw packet network I/O. The greater flexibility comes, however, at - the cost of a slightly more complex API. Receiving raw packets is - accomplished via a wrapper around + For those cases where the connection-oriented approach is too high-level, + NSE provides script developers with the + option of raw packet network I/O. + + Raw packet reception is handled through a a Libpcaplibpcap - inside the - Nsock library.Nsock + wrapper inside the Nsock + library.Nsock + The steps are to open a capture device, register listeners + with the device, and then process packets as they are + received. - For efficiency, the interface for raw packet capturing - works in three steps. First, a capture device is opened. - Second, listeners are registered with the interface. Third, - packets are received. - - A handle for raw socket reads is created from an - ordinary socket object using the - pcap_open() method. This method takes a - callback function, which computes a so-called packet hash from - a packet along with its headers. This hash can return any + The pcap_open method creates a handle for raw socket reads from an + ordinary socket object. This method takes a + callback function, which computes a packet hash from + a packet (including its headers). This hash can return any binary string, which is later compared to the strings - registered with the pcap_register() - function. Normally the packet hash callback will extract some + registered with the pcap_register + function. The packet hash callback will normally extract some portion of the packet, such as its source address. The pcap reader is instructed to listen for certain - packets using the pcap_register() function. + packets using the pcap_register function. The function takes a binary string which is compared against the hash value of every packet received. Those packets whose hashes match any registered strings will be returned by the - pcap_receive() method. Register the empty + pcap_receive method. Register the empty string to receive all packets. - A script then receives packets for which a listener has + A script receives all packets for which a listener has been registered by calling the - pcap_receive() method. The method blocks + pcap_receive method. The method blocks until a packet is received or a timeout occurs. The more general the packet hash computing function is kept, the more scripts may receive the packet and proceed with - their execution. To use the packet capturing inside your - script you have to create a socket with - nmap.new_socket() and later close the socket - with socket_object:close()—just like + their execution. To handle packet capture inside your + script you first have to create a socket with + nmap.new_socket and later close the socket + with socket_object:close—just like with the connection-based network I/O. - Receiving raw packets is a great feature, but it is also only half - the job. Now for sending raw packets: To accomplish this NSE has - access to a wrapper around the - dnet library.libdnet + Receiving raw packets is important, but sending them is a key feature as well. To accomplish this, NSE can + access a wrapper around the + libdnet library.libdnet Raw packet writes do not + use a standard socket object like reads do. Instead, call the function + nmap.new_dnet to create a dnet object + with ethernet sending methods. Then open an interface with the + ethernet_open method. Raw ethernet + frames can then be sent + with ethernet_send. When you're done, + close the ethernet handle + with ethernet_close. + + Sometimes the easiest ways to understand complex APIs + is by example. The sniffer-detect.nse + script included with Nmap uses raw packet capture and + sending in an attempt to detect promiscuous-mode machines on + the network (those running sniffers). - Unlike raw socket reads, raw packet writes are not - through a standard socket object. Instead, the function - nmap.new_dnet() creates a dnet object - with ethernet sending methods. Open an interface with the - ethernet_open() method. Send raw ethernet - frames with ethernet_send(). Close the - ethernet handle with ethernet_close() when - you're done.