Reformat and merge documentation for stdnse, shortport, strbuf, snmp, ssh1,

ssh2, smb, pop3, and msrpc.

nselib/snmp.lua

@@ -1,4 +1,4 @@
---- SNMP functions
+--- SNMP functions.
 --@copyright See nmaps COPYING for licence
 
 
@@ -6,9 +6,9 @@ module(... or "snmp",package.seeall)
 
 
 ---
--- Encodes an Integer according to ASN.1 basic encoding rules
---@param val Value to be encoded
---@return encoded integer 
+-- Encodes an Integer according to ASN.1 basic encoding rules.
+--@param val Value to be encoded.
+--@return encoded integer.
 local function encodeInt(val)
    local lsb = 0
    if val > 0 then
@@ -44,9 +44,9 @@ end
 
 
 ---
--- Encodes the length part of a ASN.1 encoding triplet
---@param val Value to be encoded
---@return encoded length value
+-- Encodes the length part of a ASN.1 encoding triplet.
+--@param val Value to be encoded.
+--@return encoded length value.
 local function encodeLength(val)
    if (val >= 128) then
       local valStr = ""
@@ -65,9 +65,9 @@ end
 
 ---
 -- Encodes a given value according to ASN.1 basic encoding
--- rules for SNMP packet creation
---@param val Value to be encoded
---@return encoded value
+-- rules for SNMP packet creation.
+--@param val Value to be encoded.
+--@return encoded value.
 function encode(val)
    local vtype = type(val)
    if (vtype == 'number') then
@@ -119,10 +119,10 @@ end
 
 ---
 -- Decodes length part of encoded value according to 
--- ASN.1 basic encoding rules
---@param encStr Encoded string
---@param pos Current position in the string
---@return The position after decoding and the length of the following value
+-- ASN.1 basic encoding rules.
+--@param encStr Encoded string.
+--@param pos Current position in the string.
+--@return The position after decoding and the length of the following value.
 local function decodeLength(encStr, pos)
    local elen
    pos, elen = bin.unpack('C', encStr, pos)
@@ -143,11 +143,11 @@ end
 
 ---
 -- Decodes an Integer according to ASN.1 basic 
--- encoding rules
---@param encStr Encoded string
---@param len Length of integer in bytes
---@param pos Current position in the string
---@return The position after decoding and the decoded integer
+-- encoding rules.
+--@param encStr Encoded string.
+--@param len Length of integer in bytes.
+--@param pos Current position in the string.
+--@return The position after decoding and the decoded integer.
 local function decodeInt(encStr, len, pos)
    local hexStr
    pos, hexStr = bin.unpack("H" .. len, encStr, pos)
@@ -160,11 +160,11 @@ end
 
 ---
 -- Decodes a sequence according to ASN.1 basic 
--- encoding rules
---@param encStr Encoded string
---@param len Length of sequence in bytes
---@param pos Current position in the string
---@return The position after decoding and the decoded sequence as a table
+-- encoding rules.
+--@param encStr Encoded string.
+--@param len Length of sequence in bytes.
+--@param pos Current position in the string.
+--@return The position after decoding and the decoded sequence as a table.
 local function decodeSeq(encStr, len, pos)
    local seq = {}
    local sPos = 1
@@ -181,10 +181,10 @@ end
 
 ---
 -- Decodes an SNMP packet or a part of it according 
--- to ASN.1 basic encoding rules
---@param encStr Encoded string
---@param pos Current position in the string
---@return The position after decoding and the decoded value(s)
+-- to ASN.1 basic encoding rules.
+--@param encStr Encoded string.
+--@param pos Current position in the string.
+--@return The position after decoding and the decoded value(s).
 function decode(encStr, pos)
    local etype, elen
    pos, etype = bin.unpack("H1", encStr, pos)
@@ -273,10 +273,10 @@ end
 
 ---
 -- Decodes an SNMP packet or a part of it according 
--- to ASN.1 basic encoding rules
---@param encStr Encoded string
---@param pos Current position in the string
---@return The decoded value(s)
+-- to ASN.1 basic encoding rules.
+--@param encStr Encoded string.
+--@param pos Current position in the string.
+--@return The decoded value(s).
 function dec(encStr, pos)
    local result
    local _
@@ -285,10 +285,10 @@ function dec(encStr, pos)
 end
 
 ---
--- Create SNMP packet
---@param PDU SNMP Protocol Data Unit to be encapsulated in the packet
---@param version SNMP version, default 0 (SNMP V1)
---@param commStr community string, if not already supplied in registry or as script argument
+-- Create SNMP packet.
+--@param PDU SNMP Protocol Data Unit to be encapsulated in the packet.
+--@param version SNMP version, default 0 (SNMP V1).
+--@param commStr community string, if not already supplied in registry or as script argument.
 function buildPacket(PDU, version, commStr)
    local comm = nmap.registry.args.snmpcommunity
    if (not comm) then comm = nmap.registry.snmpcommunity end
@@ -305,10 +305,13 @@ end
 
 
 --- 
--- Create SNMP Get Request PDU
---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx)
---@param OIDs Object identifiers to be queried
---@return Table representing PDU
+-- Create SNMP Get Request PDU.
+--@param options A table containing the following keys and values:\n
+--"reqId": request ID\n
+--"err": error\n
+--"errIdx": error index
+--@param ... Object identifiers to be queried.
+--@return Table representing PDU.
 function buildGetRequest(options, ...)
    if not options then options = {} end
 
@@ -337,10 +340,13 @@ end
 
 
 --- 
--- Create SNMP Get Next Request PDU
---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx)
---@param OIDs Object identifiers to be queried
---@return Table representing PDU
+-- Create SNMP Get Next Request PDU.
+--@param options A table containing the following keys and values:\n
+--"reqId": request ID\n
+--"err": error\n
+--"errIdx": error index
+--@param ... Object identifiers to be queried.
+--@return Table representing PDU.
 function buildGetNextRequest(options, ...)
    if not options then options = {} end
 
@@ -368,12 +374,16 @@ function buildGetNextRequest(options, ...)
 end
 
 --- 
--- Create SNMP Set Request PDU
--- Takes one OID/value pair or an already prepared table
---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx)
---@param OIDs Object identifiers of object to be set
---@param value To which value object should be set. If given a table, use table instead of OID/value pair
---@return Table representing PDU
+-- Create SNMP Set Request PDU.
+-- \n\n
+-- Takes one OID/value pair or an already prepared table.
+--@param options A table containing the following keys and values:\n
+--"reqId": request ID\n
+--"err": error\n
+--"errIdx": error index
+--@param oid Object identifiers of object to be set.
+--@param value To which value object should be set. If given a table, use table instead of OID/value pair.
+--@return Table representing PDU.
 function buildSetRequest(options, oid, value)
    if not options then options = {} end
 
@@ -437,12 +447,16 @@ function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp)
 end
 
 --- 
--- Create SNMP Get Response PDU
--- Takes one OID/value pair or an already prepared table
---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx)
---@param OIDs Object identifiers of object to be sent back
---@param value To which value object or returned object. If given a table, use table instead of OID/value pair
---@return Table representing PDU
+-- Create SNMP Get Response PDU.
+-- \n\n
+-- Takes one OID/value pair or an already prepared table.
+--@param options A table containing the following keys and values:\n
+--"reqId": request ID\n
+--"err": error\n
+--"errIdx": error index
+--@param oid Object identifiers of object to be sent back.
+--@param value To which value object or returned object. If given a table, use table instead of OID/value pair.
+--@return Table representing PDU.
 function buildGetResponse(options, oid, value) 
    if not options then options = {} end
 
@@ -475,9 +489,9 @@ function buildGetResponse(options, oid, value)
 end
 
 --- 
--- Transforms a string into an object identifier table
---@param oidStr Object identifier as string, for example "1.3.6.1.2.1.1.1.0"
---@return Table representing OID
+-- Transforms a string into an object identifier table.
+--@param oidStr Object identifier as string, for example "1.3.6.1.2.1.1.1.0".
+--@return Table representing OID.
 function str2oid(oidStr)
    local oid = {}
    for n in string.gmatch(oidStr, "%d+") do
@@ -488,18 +502,18 @@ function str2oid(oidStr)
 end
 
 ---
--- Transforms a table representing an object identifier to a string
---@param oid Object identifier table
---@return OID string
+-- Transforms a table representing an object identifier to a string.
+--@param oid Object identifier table.
+--@return OID string.
 function oid2str(oid)
    if (type(oid) ~= "table") then return 'invalid oid' end
    return table.concat(oid, '.')
 end
 
 ---
--- Transforms a table representing an IP to a string
---@param ip IP table
---@return IP string
+-- Transforms a table representing an IP to a string.
+--@param ip IP table.
+--@return IP string.
 function ip2str(ip)
    if (type(ip) ~= "table") then return 'invalid ip' end
    return table.concat(ip, '.')
@@ -507,9 +521,9 @@ end
 
 
 ---
--- Transforms a string into an IP table
---@param ipStr IP as string
---@return Table representing IP
+-- Transforms a string into an IP table.
+--@param ipStr IP as string.
+--@return Table representing IP.
 function str2ip(ipStr)
    local ip = {}
    for n in string.gmatch(ipStr, "%d+") do
@@ -521,9 +535,9 @@ end
 
 
 ---
--- Fetches values from a SNMP response
---@param resp SNMP Response (will be decoded if necessary)
---@result Table with all decoded responses and their OIDs
+-- Fetches values from a SNMP response.
+--@param resp SNMP Response (will be decoded if necessary).
+--@result Table with all decoded responses and their OIDs.
 function fetchResponseValues(resp)
    if (type(resp) == "string") then
       local _
@@ -568,8 +582,8 @@ end
 
 ---
 -- Fetches first value from a SNMP response.
---@param response SNMP Response (will be decoded if necessary)
---@return First decoded value of the response
+--@param response SNMP Response (will be decoded if necessary).
+--@return First decoded value of the response.
 function fetchFirst(response)
    local result = fetchResponseValues(response)
    if type(result) == "table" and result[1] and result[1][1] then return result[1][1]