From 114e1420bbadf2ae607c44f615fae3da83c5a9b1 Mon Sep 17 00:00:00 2001 From: david Date: Fri, 24 Oct 2008 03:56:55 +0000 Subject: [PATCH] Proofread and update documentation format in base64, bin, bit, comm, datafiles, and dns. --- nselib/base64.lua | 28 +++--- nselib/bin.luadoc | 98 +++++++++---------- nselib/bit.luadoc | 27 +++--- nselib/comm.lua | 27 +++--- nselib/datafiles.lua | 95 ++++++++++--------- nselib/dns.lua | 221 ++++++++++++++++++++++++------------------- nselib/nmap.luadoc | 2 +- 7 files changed, 266 insertions(+), 232 deletions(-) diff --git a/nselib/base64.lua b/nselib/base64.lua index 0be069085..6fb89ea56 100644 --- a/nselib/base64.lua +++ b/nselib/base64.lua @@ -1,5 +1,5 @@ ---- Base64 library. Follows RFC4648. ---@author Philip Pickering +--- Base64 encoding and decoding. Follows RFC 4648. +-- @author Philip Pickering -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html -- thanks to Patrick Donnelly for some optimizations @@ -95,9 +95,9 @@ local bunpack = bin.unpack local concat = table.concat --- --- Encode six bits to a base64 encoded character. ---@param bits String of six bits to be encoded. ---@return Encoded character. +-- Encode six bits to a Base64-encoded character. +-- @param bits String of six bits to be encoded. +-- @return Encoded character. local function b64enc6bit(bits) -- local byte -- local _, byte = bunpack("C", bpack("B", "00" .. bits)) @@ -110,9 +110,9 @@ end --- --- Decodes a base64 encoded character into binary digits. ---@param b64byte Single base64 encoded character. ---@return String of six decoded bits. +-- Decodes a Base64-encoded character into a string of binary digits. +-- @param b64byte A single base64-encoded character. +-- @return String of six decoded bits. local function b64dec6bit(b64byte) local bits = b64dctable[b64byte] if bits then return bits end @@ -121,9 +121,9 @@ end --- --- Encodes a string to base64. ---@param bdata Data to be encoded. ---@return Base64 encoded string. +-- Encodes a string to Base64. +-- @param bdata Data to be encoded. +-- @return Base64-encoded string. function enc(bdata) local pos = 1 local byte @@ -152,9 +152,9 @@ end --- --- Decodes base64 encoded data. ---@param b64data Base64 encoded data. ---@return Decoded data. +-- Decodes Base64-encoded data. +-- @param b64data Base64 encoded data. +-- @return Decoded data. function dec(b64data) local bdataBuf = {} local pos = 1 diff --git a/nselib/bin.luadoc b/nselib/bin.luadoc index 6a84bfb00..fec29881a 100644 --- a/nselib/bin.luadoc +++ b/nselib/bin.luadoc @@ -1,6 +1,5 @@ - --- 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 @@ -8,33 +7,33 @@ -- 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 --- * 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 --- \n\n +-- characters: +-- * 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 +-- -- Note that the endian operators work as modifiers to all the -- characters following them in the format string. @@ -42,33 +41,34 @@ module "bin" --- 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 +-- +-- 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. +-- +-- 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. ---@param ... The values to pack. ---@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, ...) --- 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. +-- stopped. This can be used as the init value for subsequent +-- calls. The following return values 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 c3f6432fd..ea343a090 100644 --- a/nselib/bit.luadoc +++ b/nselib/bit.luadoc @@ -1,21 +1,21 @@ --- 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), +-- 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 +-- clashing with reserved words; although xor isn't a +-- reserved word, it seemed better to use bxor for -- consistency. -- -- @author Reuben Thomas @@ -23,13 +23,13 @@ module "bit" ---- Cast a to an internally-used integer type. +--- Cast a to an internal integer type. -- @param a Number. function bit.cast(a) ---- Return the one's complement of a. +--- Returns the one's complement of a. -- @param a Number. --- @return The one's complement of a. +-- @return The one's complement of a. function bit.bnot(a) --- Returns the bitwise and of all its arguments. @@ -47,22 +47,23 @@ function bit.bor(...) -- @return The exclusive ored result. function bit.bxor(...) ---- Returns a left shifted by b places. +--- Returns a left-shifted by b places. -- @param a Number to perform the shift on. -- @param b Number of shifts. function bit.lshift(a, b) ---- Returns a right shifted by b places. +--- Returns a right-shifted by b places. -- @param a Number to perform the shift on. -- @param b Number of shifts. function bit.rshift(a, b) ---- Returns a arithmetically shifted by b places. +--- Returns a arithmetically right-shifted by b +-- places. -- @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. +--- Returns the integer remainder of a divided by b. -- @param a Dividend. -- @param b Divisor. function bit.mod(a, b) diff --git a/nselib/comm.lua b/nselib/comm.lua index 69f7c6e92..495cd47d1 100644 --- a/nselib/comm.lua +++ b/nselib/comm.lua @@ -77,14 +77,16 @@ local read = function(sock, opts) end --- This function simply connects to the specified port number on the --- specified host and returns any data received. bool is a Boolean value --- indicating success. If bool is true, then the second returned value --- is the response from the target host. If bool is false, an error --- message is returned as the second value instead of a response. +-- specified host and returns any data received. +-- +-- The first return value is true to signal success or false to signal +-- failure. On success the second return value is the response from the +-- remote host. On failure the second return value is an error message. -- @param host The host to connect to. -- @param port The port on the host. --- @param opts The options. See module description. --- @return bool, data +-- @param opts The options. See the module description. +-- @return Status (true or false). +-- @return Data (if status is true) or error string (if status is false). get_banner = function(host, port, opts) opts = initopts(opts) @@ -105,15 +107,16 @@ end --- This function connects to the specified port number on the specified -- host, sends data, then waits for and returns the response, if any. --- bool is a Boolean value indicating success. If bool is true, then the --- second returned value is the response from the target host. If bool is --- false, an error message is returned as the second value instead of a --- response. +-- +-- The first return value is true to signal success or false to signal +-- failure. On success the second return value is the response from the +-- remote host. On failure the second return value is an error message. -- @param host The host to connect to. -- @param port The port on the host. -- @param data The data to send initially. --- @param opts The options. See module description. --- @return bool, data +-- @param opts The options. See the module description. +-- @return Status (true or false). +-- @return Data (if status is true) or error string (if status is false). exchange = function(host, port, data, opts) opts = initopts(opts) diff --git a/nselib/datafiles.lua b/nselib/datafiles.lua index fbcd3424d..f52c6f38f 100644 --- a/nselib/datafiles.lua +++ b/nselib/datafiles.lua @@ -1,10 +1,9 @@ ---- Read and parse some of Nmap's data files: nmap-protocols, nmap-rpc, --- and nmap-services. --- \n\n --- The functions in this module return values appropriate for use with --- exception handling via nmap.new_try(). On success, they return true --- and the function result. On failure, they return false and an error --- message. +--- Read and parse some of Nmap's data files: nmap-protocols, +-- nmap-rpc, and nmap-services. +-- +-- The functions in this module return values appropriate for use with exception +-- handling via nmap.new_try(). On success, they return true and +-- the function result. On failure, they return false and an error message. -- @author Kris Katterjohn 03/2008 -- @author jah 08/2008 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html @@ -30,11 +29,12 @@ local common_files = { --- --- Read and parse nmap-protocols. --- \n\n --- On success, return true and a table mapping protocol numbers to --- protocol names. --- @return bool, table|err +-- Read and parse nmap-protocols. +-- +-- On success, return true and a table mapping protocol numbers to protocol +-- names. +-- @return Status (true or false). +-- @return Table (if status is true) or error string (if status is false). -- @see parse_file parse_protocols = function() local status, protocols_table = parse_file("nmap-protocols") @@ -47,10 +47,11 @@ end --- --- Read and parse nmap-rpc. --- \n\n +-- Read and parse nmap-rpc. +-- -- On success, return true and a table mapping RPC numbers to RPC names. --- @return bool, table|err +-- @return Status (true or false). +-- @return Table (if status is true) or error string (if status is false). -- @see parse_file parse_rpc = function() local status, rpc_table = parse_file("nmap-rpc") @@ -63,15 +64,17 @@ end --- --- Read and parse nmap-services. --- \n\n --- On success, return true and a table containing two subtables, indexed --- by the keys "tcp" and "udp". The tcp table maps TCP port numbers to --- service names, and the udp table is the same for UDP. You can pass --- "tcp" or "udp" as an argument to parse_services to get only one of --- the results tables. --- @param protocol The protocol table to return ("tcp" of "udp"). --- @return bool, table|err +-- Read and parse nmap-services. +-- +-- On success, return true and a table containing two subtables, indexed by the +-- keys "tcp" and "udp". The tcp subtable maps TCP port numbers to +-- service names, and the udp subtable is the same for UDP. You can +-- pass "tcp" or "udp" as an argument to parse_services() to get +-- only one of the results tables. +-- @param protocol The protocol table to return ("tcp" or +-- "udp"). +-- @return Status (true or false). +-- @return Table (if status is true) or error string (if status is false). -- @see parse_file parse_services = function(protocol) if protocol and protocol ~= "tcp" and protocol ~= "udp" then @@ -90,14 +93,15 @@ end --- -- Read and parse a generic data file. The other parse functions are -- defined in terms of this one. --- \n\n --- If filename is a key in common_files, use the corresponding capture --- pattern. Otherwise the second argument must be a table of the kind --- taken by parse_lines. -- +-- If filename is a key in common_files, use the corresponding +-- capture pattern. Otherwise the second argument must be a table of the kind +-- taken by parse_lines. +-- @param filename Name of the file to parse. +-- @param ... A table of capture patterns. -- @return A table whose structure mirrors that of the capture table, -- filled in with captured values. -function parse_file( filename, ... ) +function parse_file(filename, ...) local data_struct @@ -150,16 +154,15 @@ end --- -- Generic parsing of an array of strings. --- -- @param lines An array of strings to operate on. -- @param data_struct A table containing capture patterns to be applied -- to each string in the array. A capture will be applied to each string --- using string.match() and may also be enclosed within a table or a --- function. If a function, it must accept a string as its parameter and +-- using string.match() and may also be enclosed within a table or +-- a function. If a function, it must accept a string as its parameter and -- should return one value derived from that string. -- @return A table whose structure mirrors that of the capture table, -- filled in with captured values. -function parse_lines( lines, data_struct ) +function parse_lines(lines, data_struct) if type( lines ) ~= "table" or #lines < 1 then return false, "Error in datafiles.parse_lines: No lines to parse." @@ -204,9 +207,10 @@ end --- -- Read a file, line by line, into a table. --- @param file String with the name of the file to read. --- @return Boolean True on success, False on error --- @return Table (array-style) of lines read from the file or error message in case of an error. +-- @param file String with the name of the file to read. +-- @return Status (true or false). +-- @return Array of lines read from the file (if status is true) or error +-- message (if status is false). function read_from_file( file ) -- get path to file @@ -236,9 +240,10 @@ end --- -- Return an array-like table of values captured from each line. --- @param lines table of strings containing the lines to process --- @param v_pattern pattern to use on the lines to produce the value for the array -get_array = function( lines, v_pattern ) +-- @param lines Table of strings containing the lines to process. +-- @param v_pattern Pattern to use on the lines to produce the value for the +-- array. +get_array = function(lines, v_pattern) local ret = {} for _, line in ipairs( lines ) do assert( type( line ) == "string" ) @@ -255,11 +260,13 @@ end --- --- Return an associative array table of index-value pairs captured from each line. --- @param lines table of strings containing the lines to process --- @param i_pattern pattern to use on the lines to produce the key for the associative array --- @param v_pattern pattern to use on the lines to produce the value for the associative array -get_assoc_array = function( lines, i_pattern, v_pattern ) +-- Return a table of index-value pairs captured from each line. +-- @param lines Table of strings containing the lines to process. +-- @param i_pattern Pattern to use on the lines to produce the key for the +-- associative array. +-- @param v_pattern Pattern to use on the lines to produce the value for the +-- associative array. +get_assoc_array = function(lines, i_pattern, v_pattern) local ret = {} for _, line in ipairs(lines) do assert( type( line ) == "string" ) diff --git a/nselib/dns.lua b/nselib/dns.lua index be83d0335..26c7fe1a4 100644 --- a/nselib/dns.lua +++ b/nselib/dns.lua @@ -1,9 +1,9 @@ -module(... or "dns", package.seeall) - --- Simple DNS library supporting packet creation, encoding, decoding, -- and querying. -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html +module(... or "dns", package.seeall) + require("ipOps") require("stdnse") @@ -27,6 +27,10 @@ types = { } +--- +-- Table of error codes. +-- @name err +-- @class table err = { noSuchName = 3, noServers = 9 @@ -35,12 +39,13 @@ err = { --- -- Repeatedly sends UDP packets to host, waiting for an answer. ---@param data Data to be sent. ---@param host Host to connect to. ---@param port Port to connect to. ---@param timeout Number of ms to wait for a response. ---@param cnt Number of tries. ---@return success as boolean and response if available. +-- @param data Data to be sent. +-- @param host Host to connect to. +-- @param port Port to connect to. +-- @param timeout Number of ms to wait for a response. +-- @param cnt Number of tries. +-- @return Status (true or false). +-- @return Response (if status is true). local function sendPackets(data, host, port, timeout, cnt) local socket = nmap.new_socket() socket:set_timeout(timeout) @@ -63,8 +68,8 @@ end --- -- Checks if a DNS response packet contains a useful answer. ---@param rPkt decoded DNS response packet. ---@return true if useful, false if not. +-- @param rPkt Decoded DNS response packet. +-- @return True if useful, false if not. local function gotAnswer(rPkt) -- have we even got answers? if #rPkt.answers > 0 then @@ -95,8 +100,8 @@ end --- -- Tries to find the next nameserver with authority to get a result for -- query. ---@param rPkt decoded DNS response packet ---@return string or table of next server(s) to query or false +-- @param rPkt Decoded DNS response packet +-- @return String or table of next server(s) to query, or false. local function getAuthDns(rPkt) if #rPkt.auth == 0 then if #rPkt.answers == 0 then @@ -125,16 +130,18 @@ end --- -- Query DNS servers for a DNS record. ---@param dname wanted domain name entry ---@param options \n --- dtype wanted DNS record type (default: A).\n --- host DNS server to be queried (default: DNS servers known to Nmap).\n --- port Port of DNS server to connect to (default: 53).\n --- tries How often should query try to contact another server (for non-recursive queries).\n --- retAll Return all answers, not just the first.\n --- retPkt Return the packet instead of using the answer fetching mechanism.\n --- norecurse If true, do not set the recursion (RD) flags.\n ---@return Nice answer string by an answer fetcher on success or false and an error code (see: dns.err.*) +-- @param dname Desired domain name entry. +-- @param options A table containing any of the following fields: +-- * dtype: Desired DNS record type (default: "A"). +-- * host: DNS server to be queried (default: DNS servers known to Nmap). +-- * port: Port of DNS server to connect to (default: 53). +-- * tries: How often should query try to contact another server (for non-recursive queries). +-- * retAll: Return all answers, not just the first. +-- * retPkt: Return the packet instead of using the answer-fetching mechanism. +-- * norecurse If true, do not set the recursion (RD) flag. +-- @return Nice answer string by an answer fetcher on success or false on error. +-- @return An error code on error. +-- @see dns.err function query(dname, options) if not options then options = {} end @@ -227,8 +234,9 @@ end --- -- Formats an IP address for reverse lookup. ---@param ip IP address string. ---@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa. +-- @param ip IP address string. +-- @return "Domain"-style representation of IP as subdomain of in-addr.arpa or +-- ip6.arpa. function reverse(ip) ip = ipOps.expand_ip(ip) if type(ip) ~= "string" then return nil end @@ -267,9 +275,9 @@ local answerFetcher = {} --- -- Answer fetcher for TXT records. ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return first entry (or all) treated as TXT. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return First entry (or all of them), treated as TXT. answerFetcher[types.TXT] = function(dec, retAll) if not retAll then @@ -285,9 +293,9 @@ answerFetcher[types.TXT] = --- -- Answer fetcher for A records ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return first IP (or all) of response packet. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return First IP (or all of them) of response packet. answerFetcher[types.A] = function(dec, retAll) local answers = {} @@ -307,9 +315,9 @@ answerFetcher[types.A] = --- -- Answer fetcher for CNAME records. ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return Domain entry of first answer RR (or all) in response packet. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return Domain entry of first answer RR (or all of them) in response packet. answerFetcher[types.CNAME] = function(dec, retAll) if not retAll then @@ -325,9 +333,9 @@ answerFetcher[types.CNAME] = --- -- Answer fetcher for MX records. ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return Domain entry of first answer RR (or all) in response packet. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return Domain entry of first answer RR (or all of them) in response packet. answerFetcher[types.MX] = function(dec, retAll) if not retAll then @@ -351,9 +359,9 @@ answerFetcher[types.PTR] = answerFetcher[types.CNAME] --- -- Answer fetcher for AAAA records. ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return first IPv6 (or all) of response packet. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return First IPv6 (or all of them) of response packet. answerFetcher[types.AAAA] = function(dec, retAll) local answers = {} @@ -372,12 +380,15 @@ answerFetcher[types.AAAA] = --- --- Calls the answer fetcher for dtype or returns an error code on a no --- such name error. ---@param dtype DNS resource record type. ---@param dec Decoded DNS response. ---@param retAll If true return all entries, not just the first. ---@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error. +-- Calls the answer fetcher for dtype or returns an error code in +-- case of a "no such name" error. +-- @param dtype DNS resource record type. +-- @param dec Decoded DNS response. +-- @param retAll If true, return all entries, not just the first. +-- @return Answer according to the answer fetcher for dtype, +-- dec if no answer fetcher is known for dtype, or +-- false if flags indicate an error. +-- @return Error code on error. function findNiceAnswer(dtype, dec, retAll) if (#dec.answers > 0) then if answerFetcher[dtype] then @@ -394,8 +405,8 @@ end --- -- Encodes the question part of a DNS request. ---@param questions Table of questions. ---@return Encoded question string. +-- @param questions Table of questions. +-- @return Encoded question string. local function encodeQuestions(questions) if type(questions) ~= "table" then return nil end local encQ = "" @@ -412,8 +423,9 @@ end --- -- Encodes DNS flags to a binary digit string. ---@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx). ---@return Binary digit string representing flags. +-- @param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, +-- RA, RCx). +-- @return Binary digit string representing flags. local function encodeFlags(flags) if type(flags) == "string" then return flags end if type(flags) ~= "table" then return nil end @@ -436,10 +448,12 @@ local function encodeFlags(flags) end --- --- Takes a table representing a DNS packet to encode. +-- Encode a DNS packet. +-- -- Caution: doesn't encode answer, authority and additional part. ---@param pkt Table representing DNS packet, initialized by newPacket(). ---@return Encoded DNS packet. +-- @param pkt Table representing DNS packet, initialized by +-- newPacket(). +-- @return Encoded DNS packet. function encode(pkt) if type(pkt) ~= "table" then return nil end local encFlags = encodeFlags(pkt.flags) @@ -450,10 +464,11 @@ end --- --- Decodes a domain in a DNS packet, Handles "compressed" data too. ---@param data Complete DNS packet. ---@param pos Starting position in packet. ---@return Position after decoding and decoded domain. +-- Decodes a domain in a DNS packet. Handles "compressed" data too. +-- @param data Complete DNS packet. +-- @param pos Starting position in packet. +-- @return Position after decoding. +-- @return Decoded domain. local function decStr(data, pos) local partlen local parts = {} @@ -477,10 +492,11 @@ end --- -- Decodes questions in a DNS packet. ---@param data Complete DNS packet. ---@param count Value of question counter in header. ---@param pos Starting position in packet. ---@return Position after decoding and table of decoded questions. +-- @param data Complete DNS packet. +-- @param count Value of question counter in header. +-- @param pos Starting position in packet. +-- @return Position after decoding. +-- @return Table of decoded questions. local function decodeQuestions(data, count, pos) local q = {} for i = 1, count do @@ -498,8 +514,8 @@ end local decoder = {} --- --- Decodes IP of A record, puts it in entry.ip. ---@param entry RR in packet. +-- Decodes IP of A record, puts it in entry.ip. +-- @param entry RR in packet. decoder[types.A] = function(entry) local ip = {} @@ -509,8 +525,8 @@ decoder[types.A] = end --- --- Decodes IP of AAAA record, puts it in entry.ipv6. ---@param entry RR in packet. +-- Decodes IP of AAAA record, puts it in entry.ipv6. +-- @param entry RR in packet. decoder[types.AAAA] = function(entry) local ip = {} @@ -524,11 +540,12 @@ decoder[types.AAAA] = end --- --- Decodes SSH fingerprint record, puts it in entry.SSHFP as defined in RFC 4255: --- .algorithm --- .fptype --- .fingerprint ---@param entry RR in packet. +-- Decodes SSH fingerprint record, puts it in entry.SSHFP as +-- defined in RFC 4255. +-- +-- entry.SSHFP has the fields algorithm, +-- fptype, and fingerprint. +-- @param entry RR in packet. decoder[types.SSHFP] = function(entry) local _ @@ -539,10 +556,14 @@ decoder[types.SSHFP] = --- --- Decodes SOA record, puts it in entry.SOA.*. ---@param entry RR in packet ---@param data Complete encoded DNS packet ---@param pos Position in packet after RR +-- Decodes SOA record, puts it in entry.SOA. +-- +-- entry.SOA has the fields mname, rname, +-- serial, refresh, retry, +-- expire, and minimum. +-- @param entry RR in packet. +-- @param data Complete encoded DNS packet. +-- @param pos Position in packet after RR. decoder[types.SOA] = function(entry, data, pos) @@ -561,11 +582,11 @@ decoder[types.SOA] = end --- --- Decodes records which consist only of one domain, for example CNAME, --- NS, PTR. Puts result in entry.domain. ---@param entry RR in packet. ---@param data Complete encoded DNS packet. ---@param pos Position in packet after RR. +-- Decodes records that consist only of one domain, for example CNAME, NS, PTR. +-- Puts result in entry.domain. +-- @param entry RR in packet. +-- @param data Complete encoded DNS packet. +-- @param pos Position in packet after RR. local function decDomain(entry, data, pos) local np = pos - #entry.data local _ @@ -581,10 +602,13 @@ decoder[types.PTR] = decDomain decoder[types.TXT] = function () end --- --- Decodes MX record, puts it in entry.MX.*. ---@param entry RR in packet. ---@param data Complete encoded DNS packet. ---@param pos Position in packet after RR. +-- Decodes MX record, puts it in entry.MX. +-- +-- entry.MX has the fields pref and +-- server. +-- @param entry RR in packet. +-- @param data Complete encoded DNS packet. +-- @param pos Position in packet after RR. decoder[types.MX] = function(entry, data, pos) local np = pos - #entry.data + 2 @@ -596,12 +620,11 @@ decoder[types.MX] = --- --- Decodes returned resource records (answer, authority or additional --- part). ---@param data Complete encoded DNS packet. ---@param count Value of according counter in header. ---@param pos Starting position in packet. ---@return Table of RRs. +-- Decodes returned resource records (answer, authority, or additional part). +-- @param data Complete encoded DNS packet. +-- @param count Value of according counter in header. +-- @param pos Starting position in packet. +-- @return Table of RRs. local function decodeRR(data, count, pos) local ans = {} for i = 1, count do @@ -623,9 +646,9 @@ local function decodeRR(data, count, pos) end --- --- Splits string up into table of single characters. ---@param str String to be split up. ---@return Table of characters. +-- Splits a string up into a table of single characters. +-- @param str String to be split up. +-- @return Table of characters. local function str2tbl(str) local tbl = {} for i = 1, #str do @@ -636,8 +659,8 @@ end --- -- Decodes DNS flags. ---@param Flags as binary digit string. ---@return Table representing flags. +-- @param Flags as a binary digit string. +-- @return Table representing flags. local function decodeFlags(flgStr) flags = {} flgTbl = str2tbl(flgStr) @@ -659,8 +682,8 @@ end --- -- Decodes a DNS packet. ---@param data Encoded DNS packet. ---@return Table representing DNS packet. +-- @param data Encoded DNS packet. +-- @return Table representing DNS packet. function decode(data) local pos local pkt = {} @@ -684,7 +707,7 @@ end --- -- Creates a new table representing a DNS packet. ---@return Table representing a DNS packet. +-- @return Table representing a DNS packet. function newPacket() local pkt = {} pkt.id = 1 @@ -700,9 +723,9 @@ end --- -- Adds a question to a DNS packet table. ---@param pkt Table representing DNS packet. ---@param dname Domain name to be asked. ---@param dtype RR to be asked. +-- @param pkt Table representing DNS packet. +-- @param dname Domain name to be asked. +-- @param dtype RR to be asked. function addQuestion(pkt, dname, dtype) if type(pkt) ~= "table" then return nil end if type(pkt.questions) ~= "table" then return nil end diff --git a/nselib/nmap.luadoc b/nselib/nmap.luadoc index a2a013e21..d4af10db5 100644 --- a/nselib/nmap.luadoc +++ b/nselib/nmap.luadoc @@ -233,7 +233,7 @@ function socket: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 returns true. If the send +-- 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