| Operator | Description |
|---|
--- | H | hex string |
--- | B | bit string |
--- | x | null byte |
--- | z | zero-terminated string |
--- | p | string preceded by 1-byte integer length |
--- | P | string preceded by 2-byte integer length |
--- | a | string preceded by 4-byte integer length |
--- | A | string |
--- | f | float |
--- | d | double |
--- | n | Lua number |
--- | c | char (1-byte integer) |
--- | C | byte = unsigned char (1-byte unsigned integer) |
--- | s | short (2-byte integer) |
--- | S | unsigned short (2-byte unsigned integer) |
--- | i | int (4-byte integer) |
--- | I | unsigned int (4-byte unsigned integer) |
--- | l | long (8-byte integer) |
--- | L | unsigned long (8-byte unsigned integer) |
--- | < | little endian modifier |
--- | > | big endian modifier |
--- | = | native endian modifier |
---
+--- Pack and unpack binary data.
+-- \n\n
+-- A problem script authors often face is the necessity of encoding values
+-- into binary data. For example after analyzing a protocol the starting
+-- point to write a script could be a hex dump, which serves as a preamble
+-- to every sent packet. Although it is possible work with the
+-- functionality Lua provides, it's not very convenient. Therefore NSE includes
+-- Binlib, based on lpack (http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/)
+-- by Luiz Henrique de Figueiredo.
+-- \n\n
+-- The Binlib functions take a format string to encode and decode binary
+-- data. Packing and unpacking are controlled by the following operator
+-- characters:\n
+-- H: hex string\n
+-- B: bit string\n
+-- x: null byte\n
+-- z: zero-terminated string\n
+-- p: string preceded by 1-byte integer length\n
+-- P: string preceded by 2-byte integer length\n
+-- a: string preceded by 4-byte integer length\n
+-- A: string\n
+-- f: float\n
+-- d: double\n
+-- n: Lua number\n
+-- c: char (1-byte integer)\n
+-- C: byte = unsigned char (1-byte unsigned integer)\n
+-- s: short (2-byte integer)\n
+-- S: unsigned short (2-byte unsigned integer)\n
+-- i: int (4-byte integer)\n
+-- I: unsigned int (4-byte unsigned integer)\n
+-- l: long (8-byte integer)\n
+-- L: unsigned long (8-byte unsigned integer)\n
+-- <: little endian modifier\n
+-- >: big endian modifier\n
+-- =: native endian modifier
+-- \n\n
-- Note that the endian operators work as modifiers to all the
-- characters following them in the format string.
module "bin"
---- Packs values according to format string.
--- Note: on Windows packing of 64 bit values > 2^63 currently
+--- Returns a binary packed string.
+-- \n\n
+-- The format string describes how the parameters (p1, ...) will be interpreted.
+-- Numerical values following operators stand for operator repetitions and need
+-- an according amount of parameters. Operators expect appropriate parameter
+-- types.
+-- \n\n
+-- Note: on Windows packing of 64 bit values > 2^63 currently
-- results in packing exactly 2^63.
---@param format Format string, used to pack following arguments
---@return String containing packed data
+--@param format Format string, used to pack following arguments.
+--@param ... The values to pack.
+--@return String containing packed data.
function bin.pack(format, ...)
---- Unpacks values according to format string.
---@param format Format string, used to unpack values out of data string
---@param data String containing packed data
---@param init Optional starting position within the string
---@return First returned value is the position in the data string where unpacking stopped, following returned values are the unpacked values.
+--- Returns values read from the binary packed data string.
+-- \n\n
+-- The first return value of this function is the position at which unpacking
+-- stopped. This can be used as init value for subsequent calls. The following
+-- results are the values according to the format string. Numerical values in
+-- the format string are interpreted as repetitions like in pack, except if used
+-- with A, B or H, in which cases the number tells unpack how many bytes to
+-- read. Unpack stops if either the format string or the binary data string are
+-- exhausted.
+--@param format Format string, used to unpack values out of data string.
+--@param data String containing packed data.
+--@param init Optional starting position within the string.
+--@return Position in the data string where unpacking stopped.
+--@return All unpacked values.
function bin.unpack(format, data, init)
diff --git a/nselib/bit.luadoc b/nselib/bit.luadoc
index 0855420d1..c3f6432fd 100644
--- a/nselib/bit.luadoc
+++ b/nselib/bit.luadoc
@@ -1,10 +1,28 @@
-module "bit"
-
---- BitLib is a library by Reuben Thomas that provides facilities for
--- bitwise operations on Integer values.
+--- Bitwise operations on integers.
+-- \n\n
+-- Lua does not provide bitwise logical operations. Since they are often useful
+-- for low-level network communication, Reuben Thomas' BitLib
+-- (http://luaforge.net/projects/bitlib) for Lua has been integrated into NSE.
+-- The arguments to the bitwise operation functions should be integers. The
+-- number of bits available for logical operations depends on the data type used
+-- to represent Lua numbers--this is typically 8-byte IEEE floats (double),
+-- which give 53 bits (the size of the mantissa).
+-- \n\n
+-- This implies that the bitwise operations won't work (as expected) for numbers
+-- larger than 10^14. You can use them with 32-bit wide numbers without any
+-- problems. Operations involving 64-bit wide numbers, however, may not return
+-- the expected result.
+-- \n\n
+-- The logical operations start with "b" to avoid
+-- clashing with reserved words; although xor isn't a
+-- reserved word, it seemed better to use bxor for
+-- consistency.
+--
-- @author Reuben Thomas
-- @copyright BSD License
+module "bit"
+
--- Cast a to an internally-used integer type.
-- @param a Number.
function bit.cast(a)
@@ -43,3 +61,8 @@ function bit.rshift(a, b)
-- @param a Number to perform the shift on.
-- @param b Number of shifts.
function bit.arshift(a, b)
+
+--- Returns the integer remainder of a divided by b.
+-- @param a Dividend.
+-- @param b Divisor.
+function bit.mod(a, b)
diff --git a/nselib/tab.lua b/nselib/tab.lua
index d3b2d6565..24ac58ce3 100644
--- a/nselib/tab.lua
+++ b/nselib/tab.lua
@@ -1,13 +1,25 @@
---- Provide NSE scripts with a way to output structured tables similar to
--- NmapOutputTable.cc.
+--- Arrange output into tables.
+-- \n\n
+-- This module provides NSE scripts with a way to output structured tables
+-- similar to NmapOutputTable.cc.
+-- \n\n
+-- Example usage:\n
+-- local t = tab.new(2)\n
+-- tab.add(t, 1, 'A1')\n
+-- tab.add(t, 2, 'A2')\n
+-- tab.nextrow(t)\n
+-- tab.add(t, 1, 'BBBBBBBBB1')\n
+-- tab.add(t, 2, 'BBB2')\n
+-- tab.dump(t)
--@copyright See nmaps COPYING for license
module(... or "tab",package.seeall)
require('strbuf')
---- Create and return a new table with a number of columns equal to col and
+--- Create and return a new table with a number of columns equal to cols and
-- the row counter set to 1.
+-- @param cols the number of columns the table will hold.
function new(cols)
assert(cols > 0)
local table ={}
@@ -18,9 +30,14 @@ function new(cols)
return table
end
---- Add a new string item (v) in a previously initialised table (t)
--- at column position 'c'. The data will be added to the current
--- row, if nextrow() hasn't been called yet that will be row 1.
+--- Add a new string item to a table at a given column position.
+-- \n\n
+-- The item will be added to the current row. If nextrow hasn't been called yet
+-- that will be row 1.
+--
+-- @param t the table.
+-- @param v the string to add.
+-- @param c the column position at which to add the item.
function add(t, c, v)
assert(t)
assert(v)
@@ -42,9 +59,12 @@ function add(t, c, v)
end
--- Add a complete row to the table and move on to the next row.
--- Calls add() for each argument starting with the second argument
--- and after that calls nextrow().
-function addrow(t,...)
+-- \n\n
+-- Calls add for each argument starting with the second argument
+-- and after that calls nextrow.
+-- @param t the table.
+-- @param ... the elements to add to the row.
+function addrow(t, ...)
for i=1, arg['n'] do
add( t, i, tostring(arg[i]) )
end
@@ -54,16 +74,18 @@ end
--- Move on to the next row in the table. If this is not called
-- then previous column values will be over-written by subsequent
-- values.
+-- @param t the table.
function nextrow(t)
assert(t)
assert(t['rows'])
t['rows'] = t['rows'] + 1
end
---- Once items have been added to a table, call this to return a
--- string which contains an equally spaced table. Number of spaces
--- is based on the largest element of a column with an additional
--- two spaces for padding.
+--- Return a formatted string representation of the table.
+-- \n\n
+-- The number of spaces in a column is based on the largest element in the
+-- column with an additional two spaces for padding.
+-- @param t the table.
function dump(t)
assert(t)
assert(t['rows'])
@@ -99,15 +121,3 @@ function dump(t)
return strbuf.dump(table)
end
-
---[[ Example Usage
-
-local t = tab.new(2)
-tab.add(t, 1, 'A1')
-tab.add(t, 2, 'A2')
-tab.nextrow(t)
-tab.add(t, 1, 'BBBBBBBBB1')
-tab.add(t, 2, 'BBB2')
-tab.dump(t)
-
---]]
diff --git a/nselib/unpwdb.lua b/nselib/unpwdb.lua
index 796cf50af..a4d8ff93e 100644
--- a/nselib/unpwdb.lua
+++ b/nselib/unpwdb.lua
@@ -1,12 +1,13 @@
---- Username/Password Database Library.
+--- Username/password database library.
+-- \n\n
-- The usernames and passwords functions return multiple values for use
-- with exception handling via nmap.new_try().
-- The first value is the boolean success indicator, the second value is
-- the closure.
---
+-- \n\n
-- The closures can take a parameter of "reset" to rewind the list to the
-- beginning.
---
+-- \n\n
-- You can select your own username and/or password database to read from with
-- the script arguments userdb and passdb, respectively. Comments are allowed
-- in these files, prefixed with "#!comment:". Comments cannot be on the same
@@ -89,11 +90,12 @@ end
--- Returns the suggested number of seconds to attempt a brute
-- force attack, based on Nmap's timing values (-T4, etc) and whether or not a
--- user-defined list is used. You can use the script argument "notimelimit" to
--- make this function return nil, which means the brute-force should run until
--- the list is empty. If "notimelimit" is not used, be sure to still check for
--- nil return values on the above two functions in case you finish before the
--- time limit is up.
+-- user-defined list is used.
+-- \n\n
+-- You can use the script argument "notimelimit" to make this function return
+-- nil, which means the brute-force should run until the list is empty. If
+-- "notimelimit" is not used, be sure to still check for nil return values on
+-- the above two functions in case you finish before the time limit is up.
timelimit = function()
-- If we're reading from a user-defined username or password list,
-- we'll give them a timeout 1.5x the default. If the "notimelimit"
@@ -116,8 +118,8 @@ end
--- Returns a function closure which returns a new username with every call
-- until the username list is exhausted (in which case it returns nil).
--- @return boolean Status
--- @return function The usernames iterator
+-- @return boolean Status.
+-- @return function The usernames iterator.
usernames = function()
local path = userfile()
@@ -134,8 +136,8 @@ end
--- Returns a function closure which returns a new password with every call
-- until the password list is exhausted (in which case it returns nil).
--- @return boolean Status
--- @return function The passwords iterator
+-- @return boolean Status.
+-- @return function The passwords iterator.
passwords = function()
local path = passfile()
diff --git a/nselib/url.lua b/nselib/url.lua
index a3dfb1aab..7aa486df2 100644
--- a/nselib/url.lua
+++ b/nselib/url.lua
@@ -1,14 +1,14 @@
---- URI parsing, composition and relative URL resolution.
+--- URI parsing, composition, and relative URL resolution.
+-- @author Diego Nehab
+-- @author Eddie Bell