From 178a40f281b777859fb504abdebfdd020d6e67e1 Mon Sep 17 00:00:00 2001 From: pgpickering Date: Fri, 1 Aug 2008 20:33:56 +0000 Subject: [PATCH] updated NSEDoc documentation for snmp.lua, pop3.lua, base64.lua --- nselib/base64.lua | 20 +++++++- nselib/pop3.lua | 50 +++++++++++++++++-- nselib/snmp.lua | 125 +++++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 183 insertions(+), 12 deletions(-) diff --git a/nselib/base64.lua b/nselib/base64.lua index f42863d49..644d0f767 100644 --- a/nselib/base64.lua +++ b/nselib/base64.lua @@ -95,7 +95,10 @@ local bpack = bin.pack 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 local function b64enc6bit(bits) -- local byte -- local _, byte = bunpack("C", bpack("B", "00" .. bits)) @@ -106,12 +109,22 @@ local function b64enc6bit(bits) return b64table[byte] end + +--- +-- Decodes a base64 encoded character into binary digits +--@param b64byte Single base64 encoded character +--@return String of six decoded bits local function b64dec6bit(b64byte) local bits = b64dctable[b64byte] if bits then return bits end return '' end + +--- +-- Encodes a string to base64 +--@param bdata Data to be encoded +--@return Base64 encoded string function enc(bdata) local pos = 1 local byte @@ -140,6 +153,11 @@ function enc(bdata) return concat(b64dataBuf) end + +--- +-- Decodes base64 encoded data +--@param b64data Base64 encoded data +--@return Decoded data function dec(b64data) local bdataBuf = {} local pos = 1 diff --git a/nselib/pop3.lua b/nselib/pop3.lua index a8bd33c28..c6ec6ad48 100644 --- a/nselib/pop3.lua +++ b/nselib/pop3.lua @@ -14,14 +14,22 @@ err = { informationMissing = 3 } - +--- +-- Checks POP3 response for +--@param line First line returned from an POP3 request +--@return Found "+OK" string or nil function stat(line) return string.match(line, "+OK") end - +--- +-- Try to login using USER/PASS commands +--@param socket Socket connected to POP3 server +--@param user User string +--@param pw Password string +--@return Success as boolean and error code as in err table function login_user(socket, user, pw) socket:send("USER " .. user .. "\r\n") status, line = socket:receive_lines(1) @@ -37,6 +45,12 @@ function login_user(socket, user, pw) end +--- +-- Try to login using AUTH command using SASL/Plain method +--@param socket Socket connected to POP3 server +--@param user User string +--@param pw Password string +--@return Success as boolean and error code as in err table function login_sasl_plain(socket, user, pw) local auth64 = base64.enc(user .. "\0" .. user .. "\0" .. pw) @@ -51,6 +65,12 @@ function login_sasl_plain(socket, user, pw) end end +--- +-- Try to login using AUTH command using SASL/Login method +--@param user User string +--@param pw Password string +--@param pw String containing password to login +--@return Success as boolean and error code as in err table function login_sasl_login(socket, user, pw) local user64 = base64.enc(user) @@ -83,7 +103,13 @@ function login_sasl_login(socket, user, pw) end end - +--- +-- Try to login using APOP command +--@param socket Socket connected to POP3 server +--@param user User string +--@param pw Password string +--@param challenge String containing challenge from POP3 server greeting +--@return Success as boolean and error code as in err table function login_apop(socket, user, pw, challenge) if type(challenge) ~= "string" then return false, err.informationMissing end @@ -99,6 +125,11 @@ function login_apop(socket, user, pw, challenge) end end +--- +-- Asks POP3 server for capabilities +--@param host Host to be queried +--@param port Port to connect to +--@return Table containing capabilities function capabilities(host, port) local socket = nmap.new_socket() local capas = {} @@ -139,7 +170,11 @@ function capabilities(host, port) return capas end - +--- +-- Calculate HMAC-MD5 hash +--@param key Key for hash calculation +--@param msg Message to be hashed +--@return HMAC-MD5 of given message function hmacMD5(key, msg) local ipad = {} local opad = {} @@ -162,7 +197,12 @@ function hmacMD5(key, msg) return hash.md5(table.concat(opad) .. hash.md5bin(table.concat(ipad) .. msg)) end - +--- +-- Try to login using AUTH command using SASL/CRAM-MD5 method +--@param socket Socket connected to POP3 server +--@param user User string +--@param pw Password string +--@return Success as boolean and error code as in err table function login_sasl_crammd5(socket, user, pw) socket:send("AUTH CRAM-MD5\r\n") diff --git a/nselib/snmp.lua b/nselib/snmp.lua index 07162a844..130df175b 100644 --- a/nselib/snmp.lua +++ b/nselib/snmp.lua @@ -4,6 +4,11 @@ module(...,package.seeall) + +--- +-- 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 @@ -37,6 +42,11 @@ local function encodeInt(val) end end + +--- +-- 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 = "" @@ -52,6 +62,12 @@ local function encodeLength(val) end 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 function encode(val) local vtype = type(val) if (vtype == 'number') then @@ -100,6 +116,13 @@ function encode(val) return '' 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 local function decodeLength(encStr, pos) local elen pos, elen = bin.unpack('C', encStr, pos) @@ -117,6 +140,14 @@ local function decodeLength(encStr, pos) return pos, elen 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 local function decodeInt(encStr, len, pos) local hexStr pos, hexStr = bin.unpack("H" .. len, encStr, pos) @@ -127,6 +158,13 @@ local function decodeInt(encStr, len, pos) return pos, value 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 local function decodeSeq(encStr, len, pos) local seq = {} local sPos = 1 @@ -141,6 +179,12 @@ local function decodeSeq(encStr, len, pos) return pos, seq 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) function decode(encStr, pos) local etype, elen pos, etype = bin.unpack("H1", encStr, pos) @@ -227,6 +271,12 @@ function decode(encStr, pos) return pos, nil 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) function dec(encStr, pos) local result local _ @@ -234,6 +284,11 @@ function dec(encStr, pos) return result 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 function buildPacket(PDU, version, commStr) local comm = nmap.registry.args.snmpcommunity if (not comm) then comm = nmap.registry.snmpcommunity end @@ -248,10 +303,16 @@ function buildPacket(PDU, version, commStr) return packet 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 function buildGetRequest(options, ...) if not options then options = {} end - if not options.reqId then options.reqId = math.mod(nmap.clock_ms(), 65000) end + if not options.reqId then options.reqId = math.mod(nmap.clock_ms(), 65000) end if not options.err then options.err = 0 end if not options.errIdx then options.errIdx = 0 end @@ -274,6 +335,12 @@ function buildGetRequest(options, ...) return req 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 function buildGetNextRequest(options, ...) if not options then options = {} end @@ -300,7 +367,14 @@ function buildGetNextRequest(options, ...) return req end -function buildSetRequest(options, oid, value) -- directly uses value if value is a table +--- +-- 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 +function buildSetRequest(options, oid, value) if not options then options = {} end if not options.reqId then options.reqId = math.mod(nmap.clock_ms(), 65000) end @@ -329,6 +403,14 @@ function buildSetRequest(options, oid, value) -- directly uses value if value is return req end +--- +-- Create SNMP Trap PDU +--@param enterpriseOid +--@param agentIp +--@param genTrap +--@param specTrap +--@param timeStamp +--@return Table representing PDU function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp) local req = {} req._snmp = 'A4' @@ -354,7 +436,14 @@ function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp) return req end -function buildGetResponse(options, oid, value) -- directly uses value if value is a table +--- +-- 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 +function buildGetResponse(options, oid, value) if not options then options = {} end -- if really a response, should use reqId of request! @@ -385,7 +474,10 @@ function buildGetResponse(options, oid, value) -- directly uses value if value i return resp 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 function str2oid(oidStr) local oid = {} for n in string.gmatch(oidStr, "%d+") do @@ -395,18 +487,29 @@ function str2oid(oidStr) return oid end - +--- +-- 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 function ip2str(ip) if (type(ip) ~= "table") then return 'invalid ip' end return table.concat(ip, '.') end + +--- +-- 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 @@ -416,6 +519,11 @@ function str2ip(ipStr) return ip 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 function fetchResponseValues(resp) if (type(resp) == "string") then local _, resp = decode(resp) @@ -456,6 +564,11 @@ function fetchResponseValues(resp) return {} end + +--- +-- Fetches first value from a SNMP 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]