Add/improve NSEdoc for ike.lua

nselib/ike.lua

@@ -2,6 +2,7 @@
 --A very basic IKE library.
 --
 --The current functionality includes:
+--
 --  1. Generating a Main or Aggressive Mode IKE request packet with a variable amount of transforms and a vpn group.
 --  2. Sending a packet
 --  3. Receiving the response
@@ -10,11 +11,11 @@
 --  6. returning a parsed info table
 --
 --This library is meant for extension, which could include:
+--
 --  1. complete parsing of the response packet (might allow for better fingerprinting)
 --  2. adding more options to the request packet
 --     vendor field (might give better fingerprinting of services, e.g. Checkpoint)
 --  3. backoff pattern analyses
---  ...
 --
 --An a implementation resembling 'ike-scan' could be built.
 --
@@ -289,11 +290,14 @@ end
 
 ---
 -- Handle a response packet
--- A very limited response parser
--- Currently only the VIDs are extracted
+--
+-- A very limited response parser.
+-- Currently only the VIDs are extracted.
 -- This could be made more advanced to
 -- allow for fingerprinting via the order
 -- of the returned headers
+-- @param packet A received IKE packet
+-- @return A table of parsed response values
 function response(packet)
   local resp = { ["mode"] = "", ["info"] = nil, ['vids']={}, ['success'] = false }
 
@@ -325,10 +329,13 @@ function response(packet)
 end
 
 
--- Send a request
--- The 'packet' argument must be generated by the function 'request'
--- and is a hex string
+--- Send a request and parse the response
 --
+-- Sends an IKE request such as generated by <code>ike.request()</code>,
+-- binding to the same source port as the destination port.
+-- @param host Destination host
+-- @param port Destination port (table)
+-- @return Parsed IKE response (output of <code>ike.response()</code>)
 function send_request( host, port, packet )
 
   local socket = nmap.new_socket()
@@ -474,10 +481,17 @@ local function generate_transforms(transform_table)
 end
 
 
--- Create a request packet
+--- Create a request packet
+--
 -- Support for multiple transforms, which minimizes the
 -- the amount of traffic/packets needed to be sent
---
+-- @param port Associated port number
+-- @param proto Associated protocol
+-- @param mode "Aggressive" or "Main"
+-- @param transforms Table of IKE transforms
+-- @param diffie DH group number
+-- @param id Identification data
+-- @return IKE request datagram
 function request(port, proto, mode, transforms, diffie, id)
   local payload_after_sa, str_aggressive, l, l_sa, l_pro
   local number_transforms, transform_string