diff --git a/nselib/nmap.luadoc b/nselib/nmap.luadoc
index eb51e35f1..61d4becae 100644
--- a/nselib/nmap.luadoc
+++ b/nselib/nmap.luadoc
@@ -1,57 +1,60 @@
--- Interface with Nmap internals.
--- \n\n
--- The nmap module is an interface with Nmap's internal functions and data
--- structures. The API provides target host details such as port states and
--- version detection results. It also offers an interface to the Nsock library
--- for efficient network I/O.
+--
+-- The nmap module is an interface with Nmap's internal functions
+-- and data structures. The API provides target host details such as port
+-- states and version detection results. It also offers an interface to the
+-- Nsock library for efficient network I/O.
-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
module "nmap"
--- Returns the debugging level as a non-negative integer.
--- \n\n
--- The debugging level can be set with the -d option.
+--
+-- The debugging level can be set with the -d option.
-- @return The debugging level.
-- @usage if nmap.debugging() > 0 then ... end
function debugging()
--- Determines whether Nmap was compiled with SSL support.
--- \n\n
+--
-- This can be used to avoid sending SSL probes when SSL is not available.
--- @return true if Nmap was compiled with SSL support, false otherwise.
+-- @return True if Nmap was compiled with SSL support, false otherwise.
function have_ssl()
--- Returns the verbosity level as a non-negative integer.
--- \n\n
--- The verbosity level can be set with the -v option.
+--
+-- The verbosity level can be set with the -v option.
-- @return The verbosity level.
-- @usage if nmap.verbosity() > 0 then ... end
function verbosity()
--- Searches for the specified file and returns a string containing its path if
-- it is found and readable (to the process).
--- \n\n
--- If the file is not found, not readable, or is a directory, nil is returned.
--- The call nmap.fetchfile("nmap-rpc") will search for the data file nmap-rpc
--- and, assuming it's found (which it should be), return a string like
--- "/usr/local/share/nmap/nmap-rpc".
+--
+-- If the file is not found, not readable, or is a directory, nil
+-- is returned.
+-- @usage
+-- nmap.fetchfile("nmap-rpc") --> "/usr/local/share/nmap/nmap-rpc"
-- @param filename Filename to search for.
--- @return String representing the full path to the file or nil.
+-- @return String representing the full path to the file or nil.
function fetchfile(filename)
---- Returns the timing level as a non-negative integer. Possible return values
--- vary from 0 to 5, corresponding to the six built-in Nmap timing templates.
--- The timing level can be set with the -T option.
+--- Returns the timing level as a non-negative integer.
+--
+-- Possible return values vary from 0 to 5,
+-- corresponding to the six built-in Nmap timing templates. The timing level
+-- can be set with the -T option.
-- @return The timing level.
function timing_level()
--- Gets a port table for a port on a given host.
--- \n\n
+--
-- This function takes a host table and a port table and returns a port table
-- for the queried port. The port table returned is similar in structure to the
--- ones passed to the rule and action functions.
--- \n\n
--- You can of course reuse the host and port tables passed to the port rule
+-- ones passed to the hostrule, portrule, and
+-- action functions.
+--
+-- You can of course reuse the host and port tables passed to a script's rule
-- function. The purpose of this call is to be able to match scripts against
-- more than one open port. For example if the target host has an open port 22
-- and a running identd server, then you can write a script which will only fire
@@ -59,50 +62,58 @@ function timing_level()
-- While it is possible to specify IP addresses different to the currently
-- scanned target, the result will only be correct if the target is in the
-- currently scanned group of hosts.
--- @param host Host table, containing an "ip" field.
--- @param port Port table, containing "number" and "protocol" fields.
+-- @param host Host table, containing an ip field.
+-- @param port Port table, containing number and
+-- protocol fields.
-- @return A new port table holding the status and information for the port.
-- @usage p = nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
function get_port_state(host, port)
--- Sets the state of a port on a given host.
--- \n\n
--- Using this function, the final port state, reflected in Nmap's results,
--- can be changed for a target. This is useful when Nmap detects a port as
--- "open|filtered", but the script successfully connects to that port. In this
--- case, the script can set the port state to "open". Note that the port.state
--- value, which is passed to the script's action function will not be changed by
--- this call.
--- @param host Host table, containing an "ip" field.
--- @param port Port table, containing "number" and "protocol" fields.
--- @param state Port state, like "open" or "closed".
+--
+-- Using this function, the final port state, reflected in Nmap's results, can
+-- be changed for a target. This is useful when Nmap detects a port as
+-- open|filtered, but the script successfully connects to that
+-- port. In this case, the script can set the port state to open.
+-- This function doesn't change the original port table passed a script's
+-- action function.
+-- @param host Host table, containing an ip field.
+-- @param port Port table, containing number and
+-- protocol fields.
+-- @param state Port state, like "open" or "closed".
function set_port_state(host, port, state)
--- Sets version information on a port.
--- \n\n
+--
-- NSE scripts are sometimes able to determine the service name and application
--- version listening on a port. A whole script category (version) was designed
--- for this purpose. set_port_version function is used to record version
+-- version listening on a port. A whole script category (version)
+-- was designed for this purpose. This function is used to record version
-- information when it is discovered.
--- \n\n
+--
-- The host and port arguments to this function should either be the tables
-- passed to the action method or they should have the same structure. The port
--- argument specifies the port to operate on through its "number" and "protocol"
--- fields. and also contains the new version information to set. The version
--- detection fields this function looks at are "name", "product", "version",
--- "extrainfo", "hostname", "ostype", "devicetype", and "service_tunnel". All
--- these keys are optional.
--- \n\n
--- The probestate argument describes the state in which the script completed. It
--- is a string, one of: "hardmatched", "softmatched", "nomatch", "tcpwrapped",
--- or "incomplete". "hardmatched" is almost always used, as it signifies a
+-- argument specifies the port to operate on through its number
+-- and protocol fields. and also contains the new version
+-- information to set. The version detection fields this function looks at are
+-- name, product, version,
+-- extrainfo, hostname, ostype,
+-- devicetype, and service_tunnel. All these keys are
+-- optional.
+--
+-- The probestate argument describes the state in which the script
+-- completed. It is a string, one of: "hardmatched",
+-- "softmatched", "nomatch",
+-- "tcpwrapped", or "incomplete".
+-- "hardmatched" is almost always used, as it signifies a
-- successful match. The other possible states are generally only used for
-- standard version detection rather than the NSE enhancement.
--- @param host Host table, containing and "ip" field.
--- @param port Port table, containing "number" and "protocol" fields, as well as
--- any additional version information fields.
--- @param probestate The state of the probe: "hardmatched", "softmatched",
--- "nomatch", "tcpwrapped", or "incomplete".
+-- @param host Host table, containing and ip field.
+-- @param port Port table, containing number and
+-- protocol fields, as well as any additional version information
+-- fields.
+-- @param probestate The state of the probe: "hardmatched",
+-- "softmatched", "nomatch",
+-- "tcpwrapped", or "incomplete".
function set_port_version(host, port, probestate)
--- Returns the current date and time in milliseconds.
@@ -112,49 +123,46 @@ function set_port_version(host, port, probestate)
function clock_ms()
--- Gets the link-level hardware type of an interface.
--- \n\n
+--
-- This function takes a dnet-style interface name and returns a string
-- representing the hardware type of the interface. Possible return values are
--- "ethernet", "loopback", "p2p", or nil if none of the other types apply.
+-- "ethernet", "loopback", "p2p", or
+-- nil if none of the other types apply.
-- @param interface_name The name of the interface.
--- @return "ethernet", "loopback", "p2p", or nil.
+-- @return "ethernet", "loopback",
+-- "p2p", or nil.
-- @usage iface_type = nmap.get_interface_list("eth0")
function get_interface_link(interface_name)
--- Create a mutex on an object.
--- \n\n
+--
-- This function returns another function that works as a mutex on the object
--- passed. This object can be any Lua data type except nil, booleans, and
--- numbers. The returned function allows you to lock, try to lock, and release
--- the mutex. The returned function takes only one argument, which must be one
--- of\n
--- "lock": makes a blocking lock on the mutex. If the mutex is busy then
--- the thread will yield and wait. The function returns with the mutex locked.\n
--- "trylock": makes a non-blocking lock on the mutex. If the mutex is
--- busy then it immediately returns with a return value of false. Otherwise,
--- the mutex locks the mutex and returns true.\n
--- "done": releases the mutex and allows another thread to lock it. If
--- the thread does not have a lock on the mutex, an error will be raised.\n
--- "running": returns the thread locked on the mutex or nil if no thread
--- is locked. This should only be used for debugging as it interferes with
--- finished threads from being collected.
+-- passed. This object can be any Lua data type except nil,
+-- Booleans, and numbers. The returned function allows you to lock, try to
+-- lock, and release the mutex. The returned function takes only one argument,
+-- which must be one of
+-- * "lock": makes a blocking lock on the mutex. If the mutex is busy then the thread will yield and wait. The function returns with the mutex locked.
+-- * "trylock": makes a non-blocking lock on the mutex. If the mutex is busy then it immediately returns with a return value of false. Otherwise, the mutex locks the mutex and returns true.
+-- * "done": releases the mutex and allows another thread to lock it. If the thread does not have a lock on the mutex, an error will be raised.
+-- * "running": returns the thread locked on the mutex or nil if no thread is locked. This should only be used for debugging as it interferes with finished threads from being collected.
-- @param object Object to create a mutex for.
--- @return Mutex function which takes one of the following arguments: "lock",
--- "trylock", "done", or "running".
+-- @return Mutex function which takes one of the following arguments:
+-- "lock", "trylock", "done", or
+-- "running".
-- @usage
--- id = "My Script's Unique ID";\n
--- \n
--- local mutex = nmap.mutex(id);\n
--- function action(host, port)\n
--- mutex "lock";\n
--- -- do stuff\n
--- mutex "done";\n
--- return script_output;\n
+-- id = "My Script's Unique ID"
+--
+-- local mutex = nmap.mutex(id)
+-- function action(host, port)
+-- mutex "lock"
+-- -- do stuff
+-- mutex "done"
+-- return script_output
-- end
function mutex(object)
--- Creates a new exception handler.
--- \n\n
+--
-- This function returns another function, an exception handler. The returned
-- function takes a variable number of arguments, which are assumed to be the
-- return values of another function. It checks the return values for an
@@ -165,69 +173,69 @@ function mutex(object)
-- closing a socket.
-- @param handler Exception handler function (optional).
-- @usage
--- local result, socket, try, catch\n
--- \n
--- result = ""\n
--- socket = nmap.new_socket()\n
--- catch = function()\n
--- socket:close()\n
--- end\n
--- try = nmap.new_try(catch)\n
--- try(socket:connect(host.ip, port.number))\n
--- result = try(socket:receive_lines(1))\n
+-- local result, socket, try, catch
+--
+-- result = ""
+-- socket = nmap.new_socket()
+-- catch = function()
+-- socket:close()
+-- end
+-- try = nmap.new_try(catch)
+-- try(socket:connect(host.ip, port.number))
+-- result = try(socket:receive_lines(1))
-- try(socket:send(result))
function new_try(handler)
--- Returns a new NSE socket object.
--- \n\n
+--
-- To allow for efficient and parallelizable network I/O, NSE provides an
-- interface to Nsock, the Nmap socket library. The smart callback mechanism
-- Nsock uses is fully transparent to NSE scripts. The main benefit of NSE's
-- sockets is that they never block on I/O operations, allowing many scripts to
-- be run in parallel. The I/O parallelism is fully transparent to authors of
--- NSE scripts. In NSE you can either program as if you were using a single non
--- blocking socket or you can program as if your connection is blocking.
+-- NSE scripts. In NSE you can either program as if you were using a single
+-- non-blocking socket or you can program as if your connection is blocking.
-- Seemingly blocking I/O calls still return once a specified timeout has been
-- exceeded.
--- \n\n
+--
-- NSE sockets are the recommended way to do network I/O. They support
--- connect-style sending and receiving over TCP and UDP (and SSL), as well as
--- raw socket receiving.
+-- connect-style sending and receiving over TCP and UDP (and SSL),
+-- as well as raw socket receiving.
-- @return A new NSE socket.
-- @see pcap_open
-- @usage local socket = nmap.new_socket()
function new_socket()
--- Establishes a connection.
--- \n\n
--- The connect puts a socket in a state ready for communication. It takes as
+--
+-- This method puts a socket in a state ready for communication. It takes as
-- arguments a host descriptor (either an IP address or a hostname), a port
--- number and optionally a protocol. The protocol must be one of "tcp", "udp" or
--- "ssl"; it is "tcp" if not specified.
--- \n\n
+-- number and optionally a protocol. The protocol must be one of
+-- "tcp", "udp" or "ssl"; it is
+-- "tcp" if not specified.
+--
-- On success the function returns true. On failure it returns false and an
--- error string. Those strings are taken from the gai_strerror C function. They
--- are (with the error code in parentheses):\n
--- "Address family for hostname not supported" (EAI_ADDRFAMILY)\n
--- "Temporary failure in name resolution" (EAI_AGAIN)\n
--- "Bad value for ai_flags" (EAI_BADFLAGS)\n
--- "Non-recoverable failure in name resolution" (EAI_FAIL)\n
--- "ai_family not supported" (EAI_FAMILY)\n
--- "Memory allocation failure" (EAI_MEMORY)\n
--- "No address associated with hostname" (EAI_NODATA)\n
--- "Name or service not known" (EAI_NONAME)\n
--- "Servname not supported for ai_socktype" (EAI_SERVICE)\n
--- "ai_socktype not supported" (EAI_SOCKTYPE)\n
--- "System error" (EAI_SYSTEM)\n
--- In addition to these standard system error based messages are the following
--- two NSE-specific errors:\n
--- "Sorry, you don't have OpenSSL" occurs if the protocol is "ssl" but but Nmap
--- was compiled without OpenSSL support.\n
--- "invalid connection method" occurs if the second parameter is not one of
--- "tcp", "udp", and "ssl".
+-- error string. Those strings are taken from the gai_strerror() C
+-- function. They are (with the error code in parentheses):
+-- * "Address family for hostname not supported" (EAI_ADDRFAMILY)
+-- * "Temporary failure in name resolution" (EAI_AGAIN)
+-- * "Bad value for ai_flags" (EAI_BADFLAGS)
+-- * "Non-recoverable failure in name resolution" (EAI_FAIL)
+-- * "ai_family not supported" (EAI_FAMILY)
+-- * "Memory allocation failure" (EAI_MEMORY)
+-- * "No address associated with hostname" (EAI_NODATA)
+-- * "Name or service not known" (EAI_NONAME)
+-- * "Servname not supported for ai_socktype" (EAI_SERVICE)
+-- * "ai_socktype not supported" (EAI_SOCKTYPE)
+-- * "System error" (EAI_SYSTEM)
+-- In addition to these standard system error messages there are two
+-- NSE-specific errors:
+-- * "Sorry, you don't have OpenSSL": The protocol is "ssl" but but Nmap was compiled without OpenSSL support.
+-- * "invalid connection method": The second parameter is not one of "tcp", "udp", and "ssl".
-- @param hostid Hostname or IP address.
-- @param port Port number.
--- @param protocol "tcp", "udp", or "ssl" (default "tcp").
+-- @param protocol "tcp", "udp", or
+-- "ssl" (default "tcp").
-- @return Status (true or false).
-- @return Error code (if status is false).
-- @see new_socket
@@ -235,19 +243,17 @@ function new_socket()
function connect(hostid, port, protocol)
--- Sends data on an open socket.
--- \n\n
--- The send method sends the data contained in the data string through an open
--- connection. On success the function returns true. If the send
--- operation has failed, the function returns true along with an error string.
--- The error strings are:\n
--- "Trying to send through a closed socket": there was no call to socket:connect
--- before the send operation.\n
--- "TIMEOUT": the operation took longer than the specified timeout for the
--- socket.\n
--- "ERROR": an error occurred inside the underlying Nsock library.\n
--- "CANCELLED": the operation was cancelled.\n
--- "KILL": for example the script scan is aborted due to a faulty script.\n
--- "EOF": an EOF was read (probably will not occur for a send operation).\n
+--
+-- This socket method sends the data contained in the data string through an
+-- open connection. On success the function returns true. If the send operation
+-- has failed, the function returns true along with an error string. The error
+-- strings are
+-- * "Trying to send through a closed socket": There was no call to socket:connect before the send operation.
+-- * "TIMEOUT": The operation took longer than the specified timeout for the socket.
+-- * "ERROR": An error occurred inside the underlying Nsock library.
+-- * "CANCELLED": The operation was cancelled.
+-- * "KILL": For example the script scan is aborted due to a faulty script.
+-- * "EOF": An EOF was read (probably will not occur for a send operation).
-- @param data The data to send.
-- @return Status (true or false).
-- @return Error code (if status is false).
@@ -256,14 +262,14 @@ function connect(hostid, port, protocol)
function send(data)
--- Receives data from an open socket.
--- \n\n
+--
-- The receive method does a non-blocking receive operation on an open socket.
--- On success the function returns true along with the received data. If
--- receiving data has failed, the function returns false along with an error
--- string. A failure occurs for example if receive is called on a closed socket.
--- The receive call returns to the NSE script all the data currently stored in
--- the receive buffer of the socket. Error conditions are the same as for the
--- send operation.
+-- On success the function returns true along with the received data. On
+-- failure the function returns false along with an error string. A failure
+-- occurs for example if receive is called on a closed socket. The
+-- receive call returns to the NSE script all the data currently stored in the
+-- receive buffer of the socket. Error conditions are the same as for
+-- send.
-- @return Status (true or false).
-- @return Data (if status is true) or error string (if status is false).
-- @see new_socket
@@ -271,16 +277,18 @@ function send(data)
function receive()
--- Receives lines from an open connection.
--- \n\n
--- Tries to receive at least n lines from an open connection. A line is a string
--- delimited with \n characters. If it was not possible to receive at least n
--- lines before the operation times out a "TIMEOUT" error occurs. On the other
--- hand, if more than n lines were received, all are returned, not just n. Use
--- stdnse.make_buffer to guarantee one line is returned per call.
--- \n\n
+--
+-- Tries to receive at least n lines from an open connection. A
+-- line is a string delimited with \n characters. If it was not
+-- possible to receive at least n lines before the operation times
+-- out a "TIMEOUT" error occurs. On the other hand, if more than
+-- n lines were received, all are returned, not just
+-- n. Use stdnse.make_buffer to guarantee only one
+-- line is returned per call.
+--
-- On success the function returns true along with the received data. If
-- receiving data has failed, the function returns false along with an error
--- string. Error conditions are the same as for the send operation.
+-- string. Error conditions are the same as for send.
-- @param n Minimum number of lines to read.
-- @return Status (true or false).
-- @return Data (if status is true) or error string (if status is false).
@@ -289,15 +297,16 @@ function receive()
function receive_lines(n)
--- Receives bytes from an open connection.
--- \n\n
--- Tries to receive at least n bytes from an open connection. Like in
--- receive_lines, n is the minimum amount of characters we would like to
--- receive. If more arrive, we get all of them. If fewer than n characters
--- arrive before the operation times out, a "TIMEOUT" error occurs.
--- \n\n
+--
+-- Tries to receive at least n bytes from an open connection. Like
+-- in receive_lines, n is the minimum amount of
+-- characters we would like to receive. If more arrive, we get all of them. If
+-- fewer than n characters arrive before the operation times out,
+-- a "TIMEOUT" error occurs.
+--
-- On success the function returns true along with the received data. If
-- receiving data has failed, the function returns false along with an error
--- string. Error conditions are the same as for the send operation.
+-- string. Error conditions are the same as for send.
-- @param n Minimum number of bytes to read.
-- @return Status (true or false).
-- @return Data (if status is true) or error string (if status is false).
@@ -306,40 +315,37 @@ function receive_lines(n)
function receive_bytes(n)
--- Reads from a socket using a buffer and an arbitrary delimiter.
--- \n\n
--- The receive_buf method reads data from the network until it encounters the
--- given delimiter string (or matches the function passed in). This function
+--
+-- This method reads data from the network until it encounters the given
+-- delimiter string (or matches the function passed in). This function
-- continues to read from the network until the delimiter is found or the
--- function times out. If data is read beyond the delimiter, that data is saved
--- in a buffer for the next call to receive_buf. This buffer is cleared on
--- subsequent calls to other Network I/O API functions.
--- \n\n
+-- function times out. If data is read beyond the delimiter, that data is
+-- saved in a buffer for the next call to receive_buf. This
+-- buffer is cleared on subsequent calls to other Network I/O API functions.
+--
-- The first argument may be either a pattern or a function. If a pattern, that
--- pattern is used to separate the data. If a function, it must take exactly one
--- parameter (the buffer) and its return values must be in the same format as
--- string.find (offsets to the start and the end of the delimiter inside the
--- buffer, or nil if the delimiter is not found). The nselib match.lua module
--- provides functions for matching against regular expressions or byte counts.
--- These functions are suitable as arguments to receive_buf.
--- \n\n
--- The second argument to receive_buf is a Boolean value controlling whether the
--- delimiting string is returned along with the received data (true) or
--- discarded (false).
--- \n\n
--- On success the function returns true along with the received data. If
--- receiving data has failed, the function returns false along with an error
--- string. Possible error messages are the same as those that the other receive
--- function can return, with the addition of\n
--- "Error inside splitting-function": the first argument was a function which
--- caused an error while being called.\n
--- "Error in string.find (nsockobj:receive_buf)!": a string was provided as the
--- first argument, and string.find() yielded an error while being called.\n
--- "Expected either a function or a string!": the first argument was neither a
--- function nor a string.\n
--- "Delimiter has negative size!": the returned start offset is greater than the
--- end offset.\n
+-- pattern is used to separate the data. If a function, it must take exactly
+-- one parameter (the buffer) and its return values must be in the same format
+-- as those of string.find (offsets to the start and the end of
+-- the delimiter inside the buffer, or nil if the delimiter is not
+-- found). The nselib match.lua module provides functions for
+-- matching against regular expressions or byte counts. These functions are
+-- suitable as arguments to receive_buf.
+--
+-- The second argument to receive_buf is a Boolean value
+-- controlling whether the delimiting string is returned along with the
+-- received data (true) or discarded (false).
+--
+-- On success the function returns true along with the received data. On failure
+-- the function returns false along with an error string. Possible error
+-- messages are the same as those that the other receive functions can return,
+-- with the addition of
+-- * "Error inside splitting-function": The first argument was a function which caused an error while being called.
+-- * "Error in string.find (nsockobj:receive_buf)!": A string was provided as the first argument, and string.find() yielded an error while being called.
+-- * "Expected either a function or a string!": The first argument was neither a function nor a string.
+-- * "Delimiter has negative size!": The returned start offset is greater than the end offset.
-- @param delimiter A Lua pattern or a function with return values like those of
--- string.find.
+-- string.find.
-- @param keeppattern Whether to return the delimiter string with any returned
-- data.
-- @return Status (true or false).
@@ -349,12 +355,12 @@ function receive_bytes(n)
function receive_buf(delimiter, keeppattern)
--- Closes an open connection.
--- \n\n
+--
-- On success the function returns true. If the close fails, the function
-- returns false and an error string. Currently the only error message is
--- "Trying to close a closed socket", which is issued if the socket has already
--- been closed.
--- \n\n
+-- "Trying to close a closed socket", which is issued if the
+-- socket has already been closed.
+--
-- Sockets are subject to garbage collection. Should you forget to close a
-- socket, it will get closed before it gets deleted (on the next occasion Lua's
-- garbage collector is run). However since garbage collection cycles are
@@ -366,14 +372,14 @@ function receive_buf(delimiter, keeppattern)
function close()
--- Gets information about a socket.
--- \n\n
--- This function returns information about the socket object. It returns 5
--- values. If an error occurred, the first value is nil and the second value
--- describes the error condition. Otherwise the first value describes the
--- success of the operation and the remaining 4 values describe both endpoints
--- of the TCP connection. If you put the call in a try() statement the status
--- value is consumed. The call can be used for example if you want to query an
--- authentication server.
+--
+-- This function returns information about a socket object. It returns five
+-- values. If an error occurred, the first value is nil and the
+-- second value is an error string. Otherwise the first value is true and the
+-- remaining 4 values describe both endpoints of the TCP connection. If you put
+-- the call inside an exception handler created by new_try() the
+-- status value is consumed. The call can be used for example if you want to
+-- query an authentication server.
-- @return Status (true or false).
-- @return Local IP address (if status is true) or error string (if status is
-- false).
@@ -385,7 +391,7 @@ function close()
function get_info()
--- Sets a timeout for socket input and output operations.
--- \n\n
+--
-- After this time, given in milliseconds, socket operations will time out and
-- return. The default value is 30,000 (30 seconds). The lowest allowed value is
-- 10 ms, since this is the granularity of NSE network I/O.
@@ -395,20 +401,20 @@ function get_info()
function set_timeout(t)
--- Opens a socket for raw packet capture.
--- \n\n
+--
-- The callback function is a function that receives a packet with headers and
--- computes a "packet hash"--some value derived from the packet. For example,
+-- computes a "packet hash", some value derived from the packet. For example,
-- the callback function could extract the source IP address from a packet. The
-- hash of each packet received is compared against all the strings registered
--- with the pcap_register function.
+-- with the pcap_register function.
-- @param device The dnet-style interface name of the device you want to capture
-- from.
-- @param snaplen The length of each packet you want to capture (similar to the
--- -s option to tcpdump)\n
--- @param promisc Should be set to 1 if the interface should activate
--- promiscuous mode, and 0 otherwise.
+-- -s option to tcpdump)
+-- @param promisc Set to 1 if the interface should activate promiscuous mode,
+-- and 0 otherwise.
-- @param test_function Callback function used to compute the packet hash.
--- @param bpf A string describing a Berkeley packet filter expression (like
+-- @param bpf A string describing a Berkeley Packet Filter expression (like
-- those provided to tcpdump).
-- @see new_socket, pcap_register, pcap_receive
-- @usage
@@ -416,19 +422,20 @@ function set_timeout(t)
-- socket:pcap_open("eth0", 64, 0, callback, "tcp")
function pcap_open(device, snaplen, promisc, test_function, bpf)
---- Starts listening for incoming packages.
--- \n\n
--- The provided packet_hash is a binary string which has to match the hash
--- returned by the test_function parameter provided to pcap_open(). If you want
--- to receive all packets, just provide the empty string (""). There has to be a
--- call to pcap_register() before a call to pcap_receive().
+--- Starts listening for incoming packets.
+--
+-- The provided packet_hash is a binary string which has to match
+-- the hash returned by the test_function parameter provided to
+-- pcap_open(). If you want to receive all packets, just provide
+-- the empty string (""). There has to be a call to
+-- pcap_register() before a call to pcap_receive().
-- @param packet_hash A binary string that is compared against packet hashes.
-- @see pcap_open, pcap_receive
-- @usage socket:pcap_register("")
function pcap_register(packet_hash)
--- Receives a captured packet.
--- \n\n
+--
-- If an error or timeout occurs, the function returns false and an error
-- message. Otherwise, the function returns true followed by the packet length,
-- the layer two header, and the layer three header.
@@ -442,7 +449,7 @@ function pcap_register(packet_hash)
-- @usage status, plen, l2_data, l3_data = socket:pcap_receive()
function pcap_receive()
---- Closes the pcap device.
+--- Closes a pcap device.
-- @see close, pcap_close
-- @usage socket:pcap_close()
function pcap_close()
@@ -452,29 +459,29 @@ function pcap_close()
function new_dnet()
--- Opens an ethernet interface for raw packet sending.
--- \n\n
--- An error ("device is not valid ethernet interface") is thrown in case the
--- provided argument is not valid.
+--
+-- An error ("device is not valid ethernet interface") is thrown
+-- in case the provided argument is not valid.
-- @param interface_name The dnet-style name of the interface to open.
-- @see new_dnet
-- @usage dnet:ethernet_open("eth0")
function ethernet_open(interface_name)
--- Sends a raw ethernet frame.
--- \n\n
+--
-- The dnet object must be associated with a previously opened interface. The
--- packet must include the IP and ethernet headers If there was no previous
--- valid call to ethernet_open() an error is thrown ("dnet is not valid opened
--- ethernet interface").
+-- packet must include the IP and ethernet headers. If there was no previous
+-- valid call to ethernet_open() an error is thrown
+-- ("dnet is not valid opened ethernet interface").
-- @param packet An ethernet frame to send.
-- @see new_dnet
-- @usage dnet:ethernet_open(packet)
function ethernet_send(packet)
--- Closes an ethernet interface.
--- \n\n
--- An error ("device is not valid ethernet interface") is thrown in case the
--- provided argument is not valid.
+--
+-- An error ("device is not valid ethernet interface") is thrown
+-- in case the provided argument is not valid.
-- @see new_dnet, ethernet_open
-- @usage dnet:ethernet_close()
function ethernet_close()
diff --git a/nselib/openssl.luadoc b/nselib/openssl.luadoc
index 0f97698d5..ef277c230 100644
--- a/nselib/openssl.luadoc
+++ b/nselib/openssl.luadoc
@@ -1,20 +1,19 @@
--- OpenSSL bindings.
--- \n\n
+--
-- This module is a wrapper for OpenSSL functions that provide encryption and
-- decryption, hashing, and multiprecision integers.
--- \n\n
--- The openssl module may not always be available--it depends on whether
--- OpenSSL support was enabled at compile time. Scripts using the module should
--- be made to fail gracefully using code like the following:
--- \n\n
+--
+-- The openssl module may not always be available. It depends on
+-- whether OpenSSL support was enabled at compile time. Scripts using the
+-- module should be made to fail gracefully using code like the following:
--
--- if not pcall(require, "openssl") then\n
--- action = function(host, port)\n
--- stdnse.print_debug(2, "Skipping \"%s\" because OpenSSL is missing.", id)\n
--- end\n
--- end\n
--- action = action or function(host, port)\n
--- ...\n
+-- if not pcall(require, "openssl") then
+-- action = function(host, port)
+-- stdnse.print_debug(2, "Skipping \"%s\" because OpenSSL is missing.", id)
+-- end
+-- end
+-- action = action or function(host, port)
+-- ...
-- end
--
-- @author Sven Klemm
@@ -22,102 +21,168 @@
module "openssl"
---- Returns the size of bignum in bits.
+--- Returns the size of bignum in bits.
+-- @param bignum bignum to operate on.
+-- @return Size of bignum.
function bignum_num_bits(bignum)
---- Returns the size of bignum in bytes.
+--- Returns the size of bignum in bytes.
+-- @param bignum bignum to operate on.
+-- @return Size of bignum.
function bignum_num_bytes(bignum)
---- Sets the bit at position in bignum.
+--- Sets the bit at position in bignum.
+-- @param bignum bignum to operate on.
+-- @param position Bit position.
function bignum_set_bit(bignum, position)
---- Clears the bit at position in bignum.
+--- Clears the bit at position in bignum.
+-- @param bignum bignum to operate on.
+-- @param position Bit position.
function bignum_clear_bit(bignum, position)
---- Gets the state of the bit at position in bignum.
+--- Gets the state of the bit at position in bignum.
+-- @param bignum bignum to operate on.
+-- @param position Bit position.
+-- @return True if the selected bit is set, false otherwise.
function bignum_is_bit_set(bignum, position)
---- Sets the sign of bignum. If negative is true the sign becomes negative,
--- otherwise it becomes positive.
+--- Sets the sign of bignum.
+-- @param bignum bignum to operate on.
+-- @param negative If true, the sign becomes negative, otherwise it becomes
+-- positive.
function bignum_set_negative(bignum, negative)
---- Returns true if bignum is negative, false otherwise.
+--- Gets the sign of bignum.
+-- @param bignum bignum to operate on.
+-- @return True if bignum is negative, false otherwise.
function bignum_is_negative(bignum)
---- Converts the binary-encoded string into a bignum.
+--- Converts a binary-encoded string into a bignum.
+-- @param string Binary string.
+-- @return bignum.
function bignum_bin2bn(string)
---- Converts the decimal-encoded string into a bignum.
+--- Converts a decimal-encoded string into a bignum.
+-- @param string Decimal string.
+-- @return bignum.
function bignum_dec2bn(string)
---- Converts the hex-encoded string into a bignum.
+--- Converts a hex-encoded string into a bignum.
+-- @param string Hex string.
+-- @return bignum.
function bignum_hex2bn(string)
---- Converts bignum into a binary-encoded string.
+--- Converts bignum into a binary-encoded string.
+-- @param bignum bignum to operate on.
+-- @return Binary string.
function bignum_bn2bin(bignum)
---- Converts bignum into a decimal-encoded string.
+--- Converts bignum into a decimal-encoded string.
+-- @param bignum bignum to operate on.
+-- @return Decimal string.
function bignum_bn2dec(bignum)
---- Converts bignum into a hex-encoded string.
+--- Converts bignum into a hex-encoded string.
+-- @param bignum bignum to operate on.
+-- @return Hex string.
function bignum_bn2hex(bignum)
---- Returns a random bignum with a
+--- Returns a random bignum.
+-- @param bits Size of the returned bignum in bits.
+-- @return Random bignum.
function bignum_rand(bits)
---- Returns a pseudorandom bignum with a the given size in bits.
+--- Returns a pseudorandom bignum.
+-- @param bits Size of the returned bignum in bits.
+-- @return Pseudoandom bignum.
function bignum_pseudo_rand(bits)
---- Returns the bignum which is the result of a^p mod m.
+--- Returns the bignum which is the result of a^p mod
+-- m.
+-- @param a Base.
+-- @param p Exponent.
+-- @param m Modulus.
+-- @return bignum.
function bignum_mod_exp(a, p, m)
---- Returns a string of length bytes containing random data.
+--- Returns a string containing random data.
+-- @param bytes Length of the returned string in bytes.
+-- @return Random string.
function rand_bytes(bytes)
---- Returns a string of length bytes containing pseudorandom data.
+--- Returns a string containing pseudorandom data.
+-- @param bytes Length of the returned string in bytes.
+-- @return Pseudorandom string.
function rand_pseudo_bytes(bytes)
---- Returns the MD2 digest of message.
+--- Returns the MD2 digest of a string.
+-- @param message String to digest.
+-- @return MD2 digest.
function md2(message)
---- Returns the MD4 digest of message.
+--- Returns the MD4 digest of a string.
+-- @param message String to digest.
+-- @return MD4 digest.
function md4(message)
---- Returns the MD5 digest of message.
+--- Returns the MD5 digest of a string.
+-- @param message String to digest.
+-- @return MD5 digest.
function md5(message)
---- Returns the SHA-1 digest of message.
+--- Returns the SHA-1 digest of a string.
+-- @param message String to digest.
+-- @return SHA-1 digest.
function sha1(message)
---- Returns the RIPEMD-160 digest of message.
+--- Returns the RIPEMD-160 digest of a string.
+-- @param message String to digest.
+-- @return RIPEMD-160 digest.
function ripemd160(message)
---- Returns the digest of message using the algorithm given by the string
--- algorithm. The algorithm name may be anything returned by the
--- openssl.supported_digests function.
+--- Returns the digest of a string using a named algorithm.
+-- @param algorithm Any of the strings returned by
+-- openssl.supported_digests.
+-- @param message String to digest.
function digest(algorithm, message)
---- Returns the message authentication code of message using the given algorithm
--- and key. algorithm may be anything returned by the openssl.supported_digests
--- function.
+--- Returns the message authentication code of a string using a named algorithm.
+-- @param algorithm Any of the strings returned by
+-- openssl.supported_digests.
+-- @param key Key.
+-- @param message String.
function hmac(algorithm, key, message)
---- Encrypt data with the given algorithm, key, and initialization vector.
--- algorithm may be anything returned by the openssl.supported_ciphers function.
--- If padding is true then a partial final block will be padded and encrypted.
-function encrypt(algorithm, key, iv, data, padding = false)
+--- Encrypt data with a given algorithm, key, and initialization vector.
+-- @param algorithm Any of the strings returned by
+-- openssl.supported_ciphers.
+-- @param key Key.
+-- @param iv Initialization vector.
+-- @param data Data to encrypt.
+-- @param padding If true, then a partial final block will be padded and
+-- encrypted (default false).
+function encrypt(algorithm, key, iv, data, padding)
---- Encrypt data with the given algorithm, key, and initialization vector.
--- algorithm may be anything returned by the openssl.supported_ciphers function.
--- If padding is true then the final block must be padded correctly.
-function decrypt(algorithm, key, iv, data, padding = false)
+--- Descrypt data with a given algorithm, key, and initialization vector.
+-- @param algorithm Any of the strings returned by
+-- openssl.supported_ciphers.
+-- @param key Key.
+-- @param iv Initialization vector.
+-- @param data Data to encrypt.
+-- @param padding If true, then the final block must be padded correctly
+-- (default false).
+function decrypt(algorithm, key, iv, data, padding)
--- Returns a table with the names of the supported cipher algorithms.
+-- @return Array containing cipher names as strings.
function supported_ciphers()
--- Returns a table with the names of the supported digest algorithms.
+-- @return Array containing digest names as strings.
function supported_digests()
---- Converts data, which must be a 7-byte string, into an 8-byte DES key and
--- sets the parity.
+--- Converts a 56-bit DES key into a 64-bit key with the correct parity.
+-- @param data A 7-byte string.
+-- @return An 8-byte string.
function DES_string_to_key(string data)
diff --git a/nselib/packet.lua b/nselib/packet.lua
index 7a7356643..6b20cfb8d 100644
--- a/nselib/packet.lua
+++ b/nselib/packet.lua
@@ -8,18 +8,27 @@ require "bit"
----------------------------------------------------------------------------------------------------------------
---- Get an 8-bit integer at a 0-based byte offset in a binary string.
+--- Get an 8-bit integer at a 0-based byte offset in a byte string.
+-- @param b A byte string.
+-- @param i Offset.
+-- @return An 8-bit integer.
function u8(b, i)
return string.byte(b, i+1)
end
---- Get a 16-bit integer at a 0-based byte offset in a binary string.
+--- Get a 16-bit integer at a 0-based byte offset in a byte string.
+-- @param b A byte string.
+-- @param i Offset.
+-- @return A 16-bit integer.
function u16(b, i)
local b1,b2
b1, b2 = string.byte(b, i+1), string.byte(b, i+2)
-- 2^8 2^0
return b1*256 + b2
end
---- Get a 32-bit integer at a 0-based byte offset in a binary string.
+--- Get a 32-bit integer at a 0-based byte offset in a byte string.
+-- @param b A byte string.
+-- @param i Offset.
+-- @return A 32-bit integer.
function u32(b,i)
local b1,b2,b3,b4
b1, b2 = string.byte(b, i+1), string.byte(b, i+2)
@@ -28,20 +37,29 @@ function u32(b,i)
return b1*16777216 + b2*65536 + b3*256 + b4
end
---- Set an 8-bit integer at a 0-based byte offset in a binary string
+--- Set an 8-bit integer at a 0-based byte offset in a byte string
-- (big-endian).
+-- @param b A byte string.
+-- @param i Offset.
+-- @param num Integer to store.
function set_u8(b, i, num)
local s = string.char(bit.band(num, 0xff))
return b:sub(0+1, i+1-1) .. s .. b:sub(i+1+1)
end
---- Set a 16-bit integer at a 0-based byte offset in a binary string
+--- Set a 16-bit integer at a 0-based byte offset in a byte string
-- (big-endian).
+-- @param b A byte string.
+-- @param i Offset.
+-- @param num Integer to store.
function set_u16(b, i, num)
local s = string.char(bit.band(bit.rshift(num, 8), 0xff)) .. string.char(bit.band(num, 0xff))
return b:sub(0+1, i+1-1) .. s .. b:sub(i+1+2)
end
---- Set a 32-bit integer at a 0-based byte offset in a binary string
+--- Set a 32-bit integer at a 0-based byte offset in a byte string
-- (big-endian).
+-- @param b A byte string.
+-- @param i Offset.
+-- @param num Integer to store.
function set_u32(b,i, num)
local s = string.char(bit.band(bit.rshift(num,24), 0xff)) ..
string.char(bit.band(bit.rshift(num,16), 0xff)) ..
@@ -51,8 +69,9 @@ function set_u32(b,i, num)
end
--- Checksum
---- Calculate a standard Internet checksum.
+--- Calculate a standard Internet checksum.
+-- @param b Data to checksum.
+-- @return Checksum.
function in_cksum(b)
local sum = 0
local c
@@ -101,14 +120,14 @@ IPPROTO_UDPLITE = 136 -- UDP-Lite (RFC 3828)
Packet = {}
--- Create a new Packet object.
--- @param packet binary string with packet data.
--- @param packet_len packet length, it could be more than string.len(packet).
--- @param force_continue whether error in parsing headers should be
--- fatal or not. Especially useful at parsing ICMP packets, where a
--- small ICMP payload could be a TCP header. The problem is that parsing
--- this payload normally would fail (broken packet, because TCP header
--- is too small) The basic question is if too short TCP header should be
--- treated as fatal error.
+-- @param packet Binary string with packet data.
+-- @param packet_len Packet length. It could be more than
+-- string.len(packet).
+-- @param force_continue whether an error in parsing headers should be fatal or
+-- not. This is especially useful when parsing ICMP packets, where a small ICMP
+-- payload could be a TCP header. The problem is that parsing this payload
+-- normally would fail because the TCP header is too small.
+-- @return A new Packet.
function Packet:new(packet, packet_len, force_continue)
local o = setmetatable({}, {__index = Packet})
o.buf = packet
@@ -131,8 +150,10 @@ end
-- Helpers
---- Convert a dotted-quad IP address string (like 1.2.3.4) to a raw
--- string four bytes long.
+--- Convert a dotted-quad IP address string (like "1.2.3.4") to a
+-- raw string four bytes long.
+-- @param str IP address string.
+-- @return Four-byte string.
function iptobin(str)
local ret = ""
for c in string.gmatch(str, "[0-9]+") do
@@ -141,6 +162,8 @@ function iptobin(str)
return ret
end
--- Convert a four-byte raw string to a dotted-quad IP address string.
+-- @param raw_ip_addr Four-byte string.
+-- @return IP address string.
function toip(raw_ip_addr)
if not raw_ip_addr then
return "?.?.?.?"
@@ -148,42 +171,59 @@ function toip(raw_ip_addr)
return string.format("%i.%i.%i.%i", string.byte(raw_ip_addr,1,4))
end
--- Get an 8-bit integer at a 0-based byte offset in the packet.
+-- @param index Offset.
+-- @return An 8-bit integer.
function Packet:u8(index)
return u8(self.buf, index)
end
--- Get a 16-bit integer at a 0-based byte offset in the packet.
+-- @param index Offset.
+-- @return A 16-bit integer.
function Packet:u16(index)
return u16(self.buf, index)
end
--- Get a 32-bit integer at a 0-based byte offset in the packet.
+-- @param index Offset.
+-- @return An 32-bit integer.
function Packet:u32(index)
return u32(self.buf, index)
end
---- Return the packet contents as a byte string.
+--- Return part of the packet contents as a byte string.
+-- @param index The beginning of the part of the packet to extract.
+-- @param length The length of the part of the packet to extract.
+-- @return A string.
function Packet:raw(index, length)
return string.char(string.byte(self.buf, index+1, index+1+length-1))
end
--- Set an 8-bit integer at a 0-based byte offset in the packet.
-- (big-endian).
+-- @param index Offset.
+-- @param num Integer to store.
function Packet:set_u8(index, num)
self.buf = set_u8(self.buf, index, num)
return self.buf
end
--- Set a 16-bit integer at a 0-based byte offset in the packet.
-- (big-endian).
+-- @param index Offset.
+-- @param num Integer to store.
function Packet:set_u16(index, num)
self.buf = set_u16(self.buf, index, num)
return self.buf
end
--- Set a 32-bit integer at a 0-based byte offset in the packet.
-- (big-endian).
+-- @param index Offset.
+-- @param num Integer to store.
function Packet:set_u32(index, num)
self.buf = set_u32(self.buf, index, num)
return self.buf
end
--- Parse an IP packet header.
+-- @param force_continue Ignored.
+-- @return Whether the parsing succeeded.
function Packet:ip_parse(force_continue)
self.ip_offset = 0
if string.len(self.buf) < 20 then -- too short
@@ -222,14 +262,17 @@ function Packet:ip_set_hl(len)
self.ip_hl = bit.band(self:u8(self.ip_offset + 0), 0x0F) -- header_length or data_offset
end
--- Set the packet length field.
+-- @param len Packet length.
function Packet:ip_set_len(len)
self:set_u16(self.ip_offset + 2, len)
end
--- Set the TTL.
+-- @param ttl TTL.
function Packet:ip_set_ttl(ttl)
self:set_u8(self.ip_offset + 8, ttl)
end
--- Set the checksum.
+-- @param checksum Checksum.
function Packet:ip_set_checksum(checksum)
self:set_u16(self.ip_offset + 10, checksum)
end
@@ -240,12 +283,14 @@ function Packet:ip_count_checksum()
self:ip_set_checksum(csum)
end
--- Set the source IP address.
+-- @param binip The source IP address as a byte string.
function Packet:ip_set_bin_src(binip)
nrip = u32(binip, 0)
self:set_u32(self.ip_offset + 12, nrip)
self.ip_bin_src = self:raw(self.ip_offset + 12,4) -- raw 4-bytes string
end
--- Set the destination IP address.
+-- @param binip The destination IP address as a byte string.
function Packet:ip_set_bin_dst(binip)
nrip = u32(binip, 0)
self:set_u32(self.ip_offset + 16, nrip)
@@ -253,6 +298,7 @@ function Packet:ip_set_bin_dst(binip)
end
--- Set the IP options field (and move the data, count new length,
-- etc.).
+-- @param ipoptions IP options.
function Packet:ip_set_options(ipoptions)
-- packet = + ipoptions +
local buf = self.buf:sub(0+1,self.ip_offset + 20) .. ipoptions .. self.buf:sub(self.ip_data_offset+1)
@@ -271,7 +317,8 @@ function Packet:ip_set_options(ipoptions)
end
end
---- Return a short string representation of the IP header.
+--- Get a short string representation of the IP header.
+-- @return A string representation of the IP header.
function Packet:ip_tostring()
return string.format(
"IP %s -> %s",
@@ -280,6 +327,9 @@ function Packet:ip_tostring()
end
--- Parse IP/TCP options into a table.
+-- @param offset Offset at which options start.
+-- @param length Length of options.
+-- @return Table of options.
function Packet:parse_options(offset, length)
local options = {}
local op = 1
@@ -307,7 +357,8 @@ function Packet:parse_options(offset, length)
return options
end
---- Return a short string representation of the packet.
+--- Get a short string representation of the packet.
+-- @return A string representation of the packet.
function Packet:tostring()
if self.tcp then
return self:tcp_tostring()
@@ -321,6 +372,8 @@ end
----------------------------------------------------------------------------------------------------------------
--- Parse an ICMP packet header.
+-- @param force_continue Ignored.
+-- @return Whether the parsing succeeded.
function Packet:icmp_parse(force_continue)
self.icmp_offset = self.ip_data_offset
if string.len(self.buf) < self.icmp_offset + 8 then -- let's say 8 bytes minimum
@@ -342,13 +395,16 @@ function Packet:icmp_parse(force_continue)
end
return true
end
---- Return a short string representation of the ICMP header.
+--- Get a short string representation of the ICMP header.
+-- @return A string representation of the ICMP header.
function Packet:icmp_tostring()
return self:ip_tostring() .. " ICMP(" .. self.icmp_payload:tostring() .. ")"
end
----------------------------------------------------------------------------------------------------------------
-- Parse a TCP packet header.
+-- @param force_continue Whether a short packet causes parsing to fail.
+-- @return Whether the parsing succeeded.
function Packet:tcp_parse(force_continue)
self.tcp = true
self.tcp_offset = self.ip_data_offset
@@ -388,7 +444,8 @@ function Packet:tcp_parse(force_continue)
return true
end
---- Return a short string representation of the TCP packet.
+--- Get a short string representation of the TCP packet.
+-- @return A string representation of the ICMP header.
function Packet:tcp_tostring()
return string.format(
"TCP %s:%i -> %s:%i",
@@ -420,26 +477,32 @@ function Packet:tcp_parse_options()
end
--- Set the TCP source port.
+-- @param port Source port.
function Packet:tcp_set_sport(port)
self:set_u16(self.tcp_offset + 0, port)
end
--- Set the TCP destination port.
+-- @param port Destination port.
function Packet:tcp_set_dport(port)
self:set_u16(self.tcp_offset + 2, port)
end
--- Set the TCP sequence field.
+-- @param new_seq Sequence.
function Packet:tcp_set_seq(new_seq)
self:set_u32(self.tcp_offset + 4, new_seq)
end
--- Set the TCP flags field (like SYN, ACK, RST).
+-- @param new_flags Flags, represented as an 8-bit number.
function Packet:tcp_set_flags(new_flags)
self:set_u8(self.tcp_offset + 13, new_flags)
end
--- Set the urgent pointer field.
+-- @param urg_ptr Urgent pointer.
function Packet:tcp_set_urp(urg_ptr)
self:set_u16(self.tcp_offset + 18, urg_ptr)
end
--- Set the TCP checksum field.
+-- @param checksum Checksum.
function Packet:tcp_set_checksum(checksum)
self:set_u16(self.tcp_offset + 16, checksum)
end
@@ -459,6 +522,7 @@ function Packet:tcp_count_checksum()
end
--- Map an MTU to a link type string. Stolen from p0f.
+-- @return A string describing the link type.
function Packet:tcp_lookup_link()
local mtu_def = {
{["mtu"]=256, ["txt"]= "radio modem"},
@@ -521,7 +585,9 @@ end
-- UTILS
---- Convert a binary string to a hex string.
+--- Convert a byte string to a hex string.
+-- @param str Byte string.
+-- @return Hex string.
function bintohex(str)
local b = ""
if not str then -- nil
@@ -535,14 +601,17 @@ end
---- Convert a hex string to a binary string.
--- \n\n
--- Only bytes [a-f0-9A-F] from input are interpreted. The rest is ignored.
--- Number of interpreted bytes _must_ be even. *The input is interpreted in pairs*.\n
--- hextobin("20 20 20") -> " "\n
--- hextobin("414243") -> "ABC"\n
--- hextobin("\\41\\42\\43") -> "ABC"\n
--- hextobin(" 41 42 43 ")-> "ABC"
+--- Convert a hex string to a byte string.
+--
+-- Only bytes [a-f0-9A-F] from input are interpreted. The rest is
+-- ignored. The number of interpreted bytes must be even.
+-- @param str Hex string.
+-- @return Byte string.
+-- @usage
+-- hextobin("20 20 20") --> " "
+-- hextobin("414243") --> "ABC"
+-- hextobin("\\41\\42\\43") --> "ABC"
+-- hextobin(" 41 42 43 ") --> "ABC"
function hextobin(str)
local ret = ""
local a,b
diff --git a/nselib/pcre.luadoc b/nselib/pcre.luadoc
index a7a0d08da..148cd75a6 100644
--- a/nselib/pcre.luadoc
+++ b/nselib/pcre.luadoc
@@ -1,5 +1,5 @@
--- Perl Compatible Regular Expressions.
--- \n\n
+--
-- One of Lua's quirks is its string patterns. While they have great performance
-- and are tightly integrated into the Lua interpreter, they are very different
-- in syntax and not as powerful as standard regular expressions. So we have
@@ -15,10 +15,10 @@
-- separate pattern compilation step, which saves execution time when patterns
-- are reused. Compiled patterns can be cached in the NSE registry and reused
-- by other scripts.
--- \n\n
+--
-- The documentation for this module is derived from that supplied by the PCRE
-- Lua lib.
--- \n\n
+--
-- Warning: PCRE has a history of security vulnerabilities allowing attackers
-- who are able to compile arbitrary regular expressions to execute arbitrary
-- code. More such vulnerabilities may be discovered in the future. These have
@@ -32,50 +32,53 @@
module "pcre"
--- Returns a compiled regular expression.
--- \n\n
+--
-- The resulting compiled regular expression is ready to be matched against
-- strings. Compiled regular expressions are subject to Lua's garbage
-- collection.
--- \n\n
+--
-- The compilation flags are set bitwise. If you want to set the 3rd
-- (corresponding to the number 4) and the 1st (corresponding to 1) bit for
-- example you would pass the number 5 as a second argument. The compilation
-- flags accepted are those of the PCRE C library. These include flags for case
--- insensitive matching (1), matching line beginnings (^) and endings ($) even
--- in multiline strings (i.e. strings containing newlines) (2) and a flag for
--- matching across line boundaries (4). No compilation flags yield a default
--- value of 0.
--- @param pattern a string describing the pattern, such as "^foo$".
+-- insensitive matching (1), matching line beginnings
+-- (^) and endings ($) even in multiline strings
+-- (i.e. strings containing newlines) (2) and a flag for matching
+-- across line boundaries (4). No compilation flags yield a
+-- default value of 0.
+-- @param pattern a string describing the pattern, such as "^foo$".
-- @param flags a number describing which compilation flags are set.
-- @param locale a string describing the locale which should be used to compile
-- the regular expression (optional). The value is a string which is passed to
--- the C standard library function setlocale. For more information on this
--- argument refer to the documentation of setlocale.
+-- the C standard library function setlocale. For more
+-- information on this argument refer to the documentation of
+-- setlocale.
-- @usage local regex = pcre.new("pcre-pattern",0,"C")
function new(pattern, flags, locale)
--- Returns a table of the available PCRE option flags (numbers) keyed by their
-- names (strings).
--- \n\n
+--
-- Possible names of the available strings can be retrieved from the
-- documentation of the PCRE library used to link against Nmap. The key is the
--- option name in the manual minus the PCRE prefix. PCRE_CASELESS becomes
--- CASELESS for example.
+-- option name in the manual minus the PCRE_ prefix.
+-- PCRE_CASELESS becomes CASELESS for example.
function flags()
--- Returns the version of the PCRE library in use as a string.
--- \n\n
--- For example "6.4 05-Sep-2005".
+--
+-- For example "6.4 05-Sep-2005".
function version()
--- Matches a string against a compiled regular expression.
--- \n\n
+--
-- Returns the start point and the end point of the first match of the compiled
--- regular expression pcre_obj in the string.
+-- regular expression in the string.
-- @param string the string to match against.
-- @param start where to start the match in the string (optional).
-- @param flags execution flags (optional).
--- @return nil if no match, otherwise the start point of the first match.
+-- @return nil if no match, otherwise the start point of the first
+-- match.
-- @return the end point of the first match.
-- @return a table which contains false in the positions where the pattern did
-- not match. If named sub-patterns were used, the table also contains substring
@@ -87,34 +90,38 @@ function match(string, start, flags)
--- Matches a string against a compiled regular expression, returning positions
-- of substring matches.
--- \n\n
--- This function is like match() except that a table returned as a third result
--- contains offsets of substring matches rather than substring matches
--- themselves. That table will not contain string keys, even if named
+--
+-- This function is like match() except that a table returned as a
+-- third result contains offsets of substring matches rather than substring
+-- matches themselves. That table will not contain string keys, even if named
-- sub-patterns are used. For example, if the whole match is at offsets 10, 20
-- and substring matches are at offsets 12, 14 and 16, 19 then the function
--- returns the following: 10, 20, {12,14,16,19}
+-- returns 10, 20, {12,14,16,19}.
-- @param string the string to match against.
-- @param start where to start the match in the string (optional).
-- @param flags execution flags (optional).
--- @return a table which contains a list of substring match start and end
--- positions.
+-- @return nil if no match, otherwise the start point of the match
+-- of the whole string.
+-- @return the end point of the match of the whole string.
+-- @return a table containing a list of substring match start and end positions.
-- @usage
-- i, j, substrings = regex:exec("string to be searched", 0, 0)
-- if (i) then ... end
function exec(string, start, flags)
--- Matches a string against a regular expression multiple times.
--- \n\n
--- Tries to match the regular expression pcre_obj against string up to n times
--- (or as many as possible if n is either not given or is not a positive
--- number), subject to the execution flags ef. Each time there is a match, func
--- is called as func(m, t), where m is the matched string and t is a table of
--- substring matches. This table contains false in the positions where the
--- corresponding sub-pattern did not match. If named sub-patterns are used then
--- the table also contains substring matches keyed by their correspondent
--- sub-pattern names (strings). If func returns a true value, then gmatch
--- immediately returns; gmatch returns the number of matches made.
+--
+-- Tries to match the regular expression pcre_obj against string up to
+-- n times (or as many as possible if n is not given
+-- or is not a positive number), subject to the execution flags
+-- ef. Each time there is a match, func is called as
+-- func(m, t), where m is the matched string and
+-- t is a table of substring matches. This table contains false in
+-- the positions where the corresponding sub-pattern did not match. If named
+-- sub-patterns are used then the table also contains substring matches keyed
+-- by their correspondent sub-pattern names (strings). If func
+-- returns a true value, then gmatch() immediately returns;
+-- gmatch() returns the number of matches made.
-- @param string the string to match against.
-- @param func the function to call for each match.
-- @param n the maximum number of matches to do (optional).