/nselib/rpcap.lua

---
-- This library implements the fundamentals needed to communicate with the
-- WinPcap Remote Capture Deamon. It currently supports authenticating to
-- the service using either NULL-, or Password-based authentication.
-- In addition it has the capabilities to list the interfaces that may be
-- used for sniffing.
--
-- The library consist of classes handling <code>Request</code> and classes
-- handling <code>Response</code>. The communication with the service is
-- handled by the <code>Comm</code> class, and the main interface for script
-- writers is kept under the <code>Helper</code> class.
--
-- The following code snipplet illustrates how to connect to the service and
-- extract information about network interfaces:
-- <code>
--   local helper = rpcap.Helper:new(host, port)
--   helper:connect()
--   helper:login()
--   helper:findAllInterfaces()
--   helper:close()
-- </code>
--
-- For a more complete example, consult the rpcap-info.nse script.
--
-- @author "Patrik Karlsson <patrik@cqure.net>"


local bin = require "bin"
local ipOps = require "ipOps"
local match = require "match"
local nmap = require "nmap"
local stdnse = require "stdnse"
local table = require "table"
_ENV = stdnse.module("rpcap", stdnse.seeall)

RPCAP = {
	
	MessageType = {
		ERROR				= 1,
		FIND_ALL_INTERFACES	= 2,
		AUTH_REQUEST		= 8,
	},
	
	-- Holds the two supported authentication mechanisms PWD and NULL
	Authentication = {

		PWD = {

			new = function(self, username, password)
				local o = { 
					type = 1,
					username = username,
					password = password,
				}
				setmetatable(o, self)
				self.__index = self
				return o
	  		end,
	
			__tostring = function(self)
				local DUMMY = 0
				return bin.pack(">SSSSAA", self.type, DUMMY, #self.username, #self.password, self.username, self.password)
			end,
			
		},
		
		NULL = {
	
			new = function(self)
				local o = { 
					type = 0,
				}
				setmetatable(o, self)
				self.__index = self
				return o
	  		end,
	
			__tostring = function(self)
				local DUMMY = 0
				return bin.pack(">SSSS", self.type, DUMMY, 0, 0)
			end,
						
		}	
		
	},
	
	-- The common request and response header
	Header = {
		size = 8,		
		new = function(self, type, value, length)
			local o = {
				version = 0,
				type = type,
				value= value or 0,
				length = length or 0
			}
			setmetatable(o, self)
			self.__index = self
			return o
	  	end,
	
		parse = function(data)
			local header = RPCAP.Header:new()
			local pos
			pos, header.version, header.type, header.value, header.length = bin.unpack(">CCSI", data)
			return header
		end,
		
		__tostring = function(self)
			return bin.pack(">CCSI", self.version, self.type, self.value, self.length)
		end,

	},
	
	-- The implemented request types are kept here	
	Request = {
				
		Authentication = {
			
			new = function(self, data)
				local o = {
					header = RPCAP.Header:new(RPCAP.MessageType.AUTH_REQUEST, nil, #data),
					data = data,
				}
				setmetatable(o, self)
				self.__index = self
				return o
		  	end,
			
			__tostring = function(self)
				return tostring(self.header) .. tostring(self.data)
			end,
			
		},
		
		FindAllInterfaces = {
			
			new = function(self)
				local o = {
					header = RPCAP.Header:new(RPCAP.MessageType.FIND_ALL_INTERFACES)
				}
				setmetatable(o, self)
				self.__index = self
				return o
		  	end,
			
			__tostring = function(self)
				return tostring(self.header)
			end,
			
			
		}
		
	},	
	
	-- Parsers for responses are kept here
	Response = {
		
		Authentication = {		
			new = function(self)
				local o = { }
				setmetatable(o, self)
				self.__index = self
				return o
		  	end,
			
			parse = function(data)
				local resp = RPCAP.Response.Authentication:new()
				local pos = RPCAP.Header.size + 1
				resp.header = RPCAP.Header.parse(data)
				return resp
			end
		},
		
		Error = {
			new = function(self)
				local o = { }
				setmetatable(o, self)
				self.__index = self
				return o
		  	end,

			parse = function(data)
				local err = RPCAP.Response.Error:new()
				local pos = RPCAP.Header.size + 1
				err.header = RPCAP.Header.parse(data)
				pos, err.error = bin.unpack("A" .. err.header.length, data, pos)
				return err
			end
			
		},
		
		FindAllInterfaces = {
			new = function(self)
				local o = { }
				setmetatable(o, self)
				self.__index = self
				return o
			end,
			
			parse = function(data)

				-- Each address is made up of 4 128 byte fields, this function
				-- parses these fields and return the response, if it
				-- understands it. Otherwise it simply increases the pos by the
				-- correct offset, to get us to the next field.
				local function parseField(data, pos)
					local offset = pos
					local family, port
					pos, family, port = bin.unpack(">SS", data, pos)
					
					if ( family == 0x0017 ) then
						-- not sure why...
						pos = pos + 4
						
						local ipv6
						pos, ipv6 = bin.unpack("B16", data, pos)
						return offset + 128, ipOps.bin_to_ip(ipv6)
					elseif ( family == 0x0002 ) then
						local ipv4
						pos, ipv4 = bin.unpack("B4", data, pos)
						return offset + 128, ipOps.bin_to_ip(ipv4)
					end
						
					return offset + 128, nil
				end
				
				-- Parses one of X addresses returned for an interface
				local function parseAddress(data, pos)
					local fields = {"ip", "netmask", "bcast", "p2p"}
					local addr = {}
					
					for _, f in ipairs(fields) do
						pos, addr[f] = parseField(data, pos)
					end

					return pos, addr
				end
			
				local resp = RPCAP.Response.FindAllInterfaces:new()
				local pos = RPCAP.Header.size + 1
				resp.header = RPCAP.Header.parse(data)
				resp.ifaces = {}
				
				for i=1, resp.header.value do
					local name_len, desc_len, iface_flags, addr_count, dummy
					pos, name_len, desc_len, iface_flags, addr_count, dummy = bin.unpack(">SSISS", data, pos)

					local name, desc
					pos, name, desc = bin.unpack("A" .. name_len .. "A" .. desc_len, data, pos)

					local addrs = {}
					for j=1, addr_count do
						local addr
						pos, addr = parseAddress(data, pos)
						local cidr
						if ( addr.netmask ) then
							local bits = ipOps.ip_to_bin(addr.netmask)
							local ones = bits:match("^(1*)")
							cidr = #ones
							table.insert(addrs, ("%s/%d"):format(addr.ip,cidr))
						else
							table.insert(addrs, addr.ip)
						end
					end
					table.insert(resp.ifaces, { name = name, desc = desc, addrs = addrs })
				end
				return resp
			end,
		}
		
		
	}
	
}

-- Maps packet types to classes
RPCAP.TypeToClass = {
	[1] 	= RPCAP.Response.Error,
	[130]	= RPCAP.Response.FindAllInterfaces,
	[136]	= RPCAP.Response.Authentication,
}


-- The communication class
Comm = {
	
	-- Creates a new instance of the Comm class
	-- @param host table
	-- @param port table
	-- @return o instance of Comm
	new = function(self, host, port)
		local o = { host = host, port = port, socket = nmap.new_socket() }
		setmetatable(o, self)
		self.__index = self
		return o
	end,
	
	-- Connects the socket to the server
	connect = function(self)
		return self.socket:connect(self.host, self.port)
	end,
	
	-- Sends an instance of the request class to the server
	-- @param req class instance
	-- @return status true on success, false on failure
	-- @return err string containing error message if status is false
	send = function(self, req)
		return self.socket:send(req)
	end,

	-- receives a packet and attempts to parse it if it has a supported parser
	-- in RPCAP.TypeToClass
	-- @return status true on success, false on failure
	-- @return resp instance of a Response class or
	--         err string containing the error message	
	recv = function(self)
		local status, hdr_data = self.socket:receive_buf(match.numbytes(RPCAP.Header.size), true)
		if ( not(status) ) then
			return status, hdr_data
		end

		local header = RPCAP.Header.parse(hdr_data)
		if ( not(header) ) then
			return false, "rpcap: Failed to parse header"
		end
		
		local status, data = self.socket:receive_buf(match.numbytes(header.length), true)
		if ( not(status) ) then
			return false, "rpcap: Failed to read packet data"
		end

		if ( RPCAP.TypeToClass[header.type] ) then
			local resp = RPCAP.TypeToClass[header.type].parse(hdr_data .. data)
			if ( resp ) then
				return true, resp
			end
		end
		
		return false, "Failed to receive response from server"
	end,
	
	-- Sends and request and receives the response
	-- @param req the instance of the Request class to send
	-- @return status true on success, false on failure
	-- @return resp instance of a Response class or
	--         err string containing the error message
	exch = function(self, req)
		local status, data = self:send(tostring(req))
		if ( not(status) ) then
			return status, data
		end
		return self:recv()
	end,
	
	-- closes the socket
	close = function(self)
		return self.socket:close()
	end,
	
}


Helper = {
	
	-- Creates a new instance of the Helper class
	-- @param host table
	-- @param port table
	-- @return o instance of Helper
	new = function(self, host, port)
		local o = { 
			host = host,
			port = port,
			comm = Comm:new(host, port)
		}
		setmetatable(o, self)
		self.__index = self
		return o
  	end,

	-- Connects to the server
	connect = function(self)
		return self.comm:connect(self.host, self.port)
	end,
	
	-- Authenticates to the service, in case no username or password is given
	-- NULL authentication is assumed.
	-- @param username [optional]
	-- @param password [optional]
	-- @return status true on success, false on failure
	-- @return err string containing error mesage on failure
	login = function(self, username, password)
		local auth
		
		if ( username and password ) then
			auth = RPCAP.Authentication.PWD:new(username, password)
		else
			auth = RPCAP.Authentication.NULL:new()
		end
	
		local req = RPCAP.Request.Authentication:new(tostring(auth))
		local status, resp = self.comm:exch(req)
	
		if ( not(status) ) then
			return false, resp
		end
		
		if ( status and resp.error ) then
			return false, resp.error
		end
		return true
 	end,

	-- Requests a list of all interfaces
	-- @return table containing interfaces and addresses
	findAllInterfaces = function(self)
		local req = RPCAP.Request.FindAllInterfaces:new()
		local status, resp = self.comm:exch(req)
	
		if ( not(status) ) then
			return false, resp
		end
		
		local results = {}
		for _, iface in ipairs(resp.ifaces) do
			local entry = {}
			entry.name = iface.name
			table.insert(entry, iface.desc)
			table.insert(entry, { name = "Addresses", iface.addrs })
			table.insert(results, entry)
		end
		return true, results
	end,
	
	-- Closes the connection to the server
	close = function(self)
		return self.comm:close()
	end,
}

return _ENV;