/nselib/sip.lua

--- A SIP library supporting a limited subset of SIP commands and methods
--
-- The library currently supports the following methods:
--	* REGISTER, INVITE & OPTIONS
--
-- Overview
-- --------
-- The library consists of the following classes:
-- 
-- o SessionData
--		- Holds session data for the SIP session
--
-- o Session
--		- Contains application functionality related to the implemented
-- 		  SIP methods.
--
-- o Connection
--		- A class containing code related to socket communication.
--
-- o Response
--		- A class containing code for handling SIP responses
--
-- o Request
--		- A class containing code for handling SIP requests
--
-- o Util
--		- A class containing static utility functions
--
-- o SIPAuth
--		- A class containing code related to SIP Authentication
--
-- o Helper
--		- A class containing code used as a primary interface by scripts
-- 
--
-- @author "Patrik Karlsson <patrik@cqure.net>"
-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
--
-- @args sip.timeout - specifies the session (socket) timeout in seconds

-- Version 0.1
-- Created 2011/03/30 - v0.1 - created by Patrik Karlsson <patrik@cqure.net>

local bin = require "bin"
local math = require "math"
local nmap = require "nmap"
local os = require "os"
local stdnse = require "stdnse"
local openssl = stdnse.silent_require "openssl"
local string = require "string"
local table = require "table"
_ENV = stdnse.module("sip", stdnse.seeall)

-- Method constants
Method = {
	ACK = "ACK",
	INVITE = "INVITE",
	OPTIONS = "OPTIONS",
	REGISTER = "REGISTER",
}

-- Error constants
Error = {
	TRYING = 100,
	RING = 180,
	TIMEOUT = 408,
	BUSY = 486,
	DECLINE = 603,
	OK = 200,
	UNAUTHORIZED = 401,
	FORBIDDEN = 403,
	NOTFOUND = 404,
	PROXY_AUTH_REQUIRED = 407,
}

-- The SessionData class
SessionData = {
	
	--- Creates a new instance of sessiondata
	-- @return o an instance of SessionData
	new = function(self, o)
		local o = o or {}
		setmetatable(o, self)
        self.__index = self
		o.user = "user"
		return o
	end,
	
	--- Sets the session username
	-- @param user string containing the username
	setUsername = function(self, user) self.user = user end,

	--- Sets the session password
	-- @param pass string containing the password
	setPassword = function(self, pass) self.pass = pass end,

	--- Sets the SIP domain
	-- @param domain string containing the SIP domain
	setDomain = function(self, domain) self.domain = domain end,

	--- Sets the ip and port of the remote server
	-- @param host string containing the ip of the remote server
	-- @param port number containing the port of the remote server
	setServer = function(self, host, port) self.server = { host = host, port = port } end,

	--- Sets the ip and port of the client
	-- @param host string containing the ip of the client
	-- @param port number containing the port of the client
	setClient = function(self, host, port) self.client = { host = host, port = port } end,

	--- Sets the SIP users Full Name
	-- @param name string containing the full name of the user
	setName = function(self, name) self.name = name end,
	
	--- Retrieves the username
	-- @return user string containing the sessions username
	getUsername = function(self) return self.user end,
	
	--- Retrieves the session password
	-- @return pass string containing the session password
	getPassword = function(self) return self.pass end,
	
	--- Retrieves the SIP domain
	-- @return domain string containing the SIP domain
	getDomain = function(self) return self.domain end,
	
	--- Retrieves the client IP and port
	-- @return host string containing the client IP
	-- @return port number containing the client port
	getClient = function(self) return self.client.host, self.client.port end,

	--- Retrieves the server IP and port
	-- @return host string containing the server IP
	-- @return port number containing the server port
	getServer = function(self) return self.server.host, self.server.port end,

	--- Retrieves the SIP users full name
	-- @return name string containing the users full name
	getName = function(self) return self.name or "Nmap NSE" end,
}

-- The session class holds the code necessary to register a SIP session
Session = {

	--- Creates a new session instance
	-- @param host table containing the remote host to connect to
	-- @param port table containing the remote port to connect to
	-- @param sessdata instance of SessionData
	-- @param options table containing zero or more of the following options
	--		<code>expires</code> - the expire value in seconds
	--		<code>timeout</code> - the socket timeout in seconds
	-- @return o containing a new instance of the Session class
	new = function(self, host, port, sessdata, options)
		local o = {}
		setmetatable(o, self)
        self.__index = self
		o.protocol = port.protocol:upper()
		o.expires = (options and options.expires) or 300
		o.conn = Connection:new(host,port)
		o.cseq = (options and options.cseq) or 1234
		local timeout = ( ( options and options.timeout ) and 
							options.timeout * 1000 ) or 5000
		o.conn.socket:set_timeout( timeout )
		o.sessdata = sessdata or SessionData:new()
		return o
	end,
			
	--- Connect the session
	-- @return true on success, false on failure
	-- @return err string containing error message
	connect = function(self)
		local status, err = self.conn:connect()
		if (not(status)) then
			return false, "ERROR: Failed to connect to server"
		end
		local status, lhost, lport, rhost, rport = self.conn.socket:get_info()
		if ( not(status) ) then
			return false, "Failed to retreive socket information"
		end
		self.sessdata:setClient(lhost, lport)
		self.sessdata:setServer(rhost, rport)
		return true
	end,
	
	--- Closes the session
	-- TODO: We should probably send some "closing" packets here
	-- @return true on success, false on failure
	close = function(self) return self.conn:close()	end,
	
	--- Sends and SIP invite
	-- @param uri
	invite = function(self, uri)
		local request = Request:new(Method.INVITE, self.protocol)

		local lhost, _ = self.sessdata:getClient()
		local tm = os.time()
		
		local uri = (uri and uri:match("^sip:.*@.*")) or 
					("sip:%s@%s"):format(uri, self.sessdata:getDomain())
		
		request:setUri(uri)
		request:setSessionData(self.sessdata)

		local data = {}
		table.insert(data, "v=0")
		table.insert(data, ("o=- %s %s IN IP4 %s"):format(tm, tm, lhost))
		table.insert(data, "s=-")
		table.insert(data, ("c=IN IP4 %s"):format(lhost))
		table.insert(data, "t=0 0")
		table.insert(data, "m=audio 49174 RTP/AVP 0")
		table.insert(data, "a=rtpmap:0 PCMU/8000")

		request:setContent(stdnse.strjoin("\r\n", data))
		request:setContentType("application/sdp")
		
		local status, response = self:exch(request)
		if ( not(status) ) then return false, response end

		local errcode = response:getErrorCode()

		if ( Error.PROXY_AUTH_REQUIRED == errcode or 
					Error.UNAUTHORIZED == errcode ) then

			-- Send an ACK to the server
			request:setMethod(Method.ACK)
			local status, err = self.conn:send( tostring(request) )
			if ( not(status) ) then	return status, "ERROR: Failed to send request" end

			-- Send an authenticated INVITE to the server
			request:setMethod(Method.INVITE)
			self.cseq = self.cseq + 1
			status, data = self:authenticate(request, response)
			if ( not(status) ) then	return false, "SIP Authentication failed" end
			response = Response:new(data)
	
			-- read a bunch of 180 Ringing and 100 Trying requests, until we get a 200 OK
			while ( response:getErrorCode() ~= Error.OK ) do
				status, data = self.conn:recv()
				if ( not(status) ) then return status, "ERROR: Failed to receive response" end
				response = Response:new(data)
			end
				
		end
		
		return true
	end,
	
	--- Prepares and sends the challenge response authentication to the server
	-- @param request instance of the request object requiring authentication
	-- @param authdata string containing authentication data
	-- @return status true on success false on failure
	-- @return err string containing an error message if status is false
	authenticate = function(self, request, response)
		local rhost, _ = self.sessdata:getServer()
		local auth_header, auth_data = response:getAuthData() 
		local auth = SipAuth:new(auth_data)
		auth:setUsername(self.sessdata:getUsername())
		auth:setPassword(self.sessdata:getPassword())
		auth:setMethod(request.method)
		auth:setUri(("sip:%s"):format(rhost))

		if ( auth_header == "WWW-Authenticate" ) then
			request:setWWWAuth(auth:createResponse())
		else
			request:setProxyAuth(auth:createResponse())
		end
		request:setCseq(self.cseq)

		local status, err = self.conn:send( tostring(request) )
		if ( not(status) ) then	return status, "ERROR: Failed to send request" end

		local data
		status, data = self.conn:recv()
		if ( not(status) and data ~= "TIMEOUT" ) then
			return status, "ERROR: Failed to receive response"
		end
		return status, data
	end,
	
	--- Sends a SIP Request and receives the Response
	-- @param request instance of Request
	-- @return status true on success, false on failure
	-- @return resp containing a new Response instance
	--			err containing error message if status is false
	exch = function(self, request)
		request:setCseq(self.cseq)
		
		local status, err = self.conn:send( tostring(request) )
		if ( not(status) ) then	return status, "ERROR: Failed to send request" end

		local status, data = self.conn:recv()
		if ( not(status) ) then return status, "ERROR: Failed to receive response" end
		
		return true, Response:new(data)
	end,
	
	--- Sends a register request to the server
	-- @return status true on success, false on failure
	-- @return msg string containing the error message (if status is false)
	register = function(self)
		local request = Request:new(Method.REGISTER, self.protocol)
		
		request:setUri("sip:" .. self.sessdata:getServer())
		request:setSessionData(self.sessdata)
		request:setExpires(self.expires)
				
		local status, response = self:exch(request)
		if (not(status)) then return false, response end

		local errcode = response:getErrorCode()
		
		if ( status and errcode == Error.OK ) then
			return true, response
		elseif ( Error.PROXY_AUTH_REQUIRED == errcode or Error.UNAUTHORIZED == errcode ) then
			local data
			self.cseq = self.cseq + 1
			status, data = self:authenticate(request, response)
			response = Response:new(data)
			errcode = response:getErrorCode() 
			if ( not(status) or ( errcode and errcode ~= Error.OK ) ) then
				return false, "ERROR: Failed to authenticate"
			end
		elseif ( Error.FORBIDDEN == errcode ) then
			return false, "Authentication forbidden"
		else
			return false, ("Unhandled error: %d"):format(errcode)
		end
		return true
	end,
	
	--- Sends an option request to the server and handles the response
	-- @return status true on success, false on failure
	-- @return response if status is true, nil else.
	options = function(self)
		local req = Request:new(Method.OPTIONS, self.protocol)
		req:setUri("sip:" .. self.sessdata:getServer())
		req:setSessionData(self.sessdata)
		req:setExpires(self.expires)
		req:addHeader("Accept", "application/sdp")

		local status, response = self:exch(req)
		if status then return true, response end

		return false, nil
	end,

}

-- The connection class contains basic communication code
Connection = {
	
	--- Creates a new SIP Connection
	-- @param host table containing the host to connect to
	-- @param port table containing the port to connect to
	-- @return o containing a new Connection instance
	new = function(self, host, port)
		local o = {}
		setmetatable(o, self)
        self.__index = self
		o.host = host
		o.port = port
		o.socket = nmap.new_socket()
		return o
	end,
	
	--- Connects to the server
	-- @return status containing true on success and false on failure
	-- @return err containing the error message (if status is false)
	connect = function(self)
		local status, err = self.socket:connect(self.host, self.port)
		if ( status ) then
			local status, lhost, lport, _, _ = self.socket:get_info()
			if ( status ) then
				self.lhost = lhost
				self.lport = lport
			end
		end
		return status, err
	end,
	
	--- Sends the data over the socket
	-- @return status true on success, false on failure
	send = function(self, data)
		return self.socket:send(data)
	end,

	--- Receives data from the socket
	-- @return status true on success, false on failure
	recv = function(self)
		return self.socket:receive()
	end,

	--- Closes the communication channel (socket)
	-- @return true on success false on failure
	close = function(self)
		return self.socket:close()
	end,
	
	--- Retrieves the client ip and port
	-- @return lhost string containing the local ip
	-- @return lport number containing the local port
	getClient = function(self) return self.lhost, self.lport end,

	--- Retrieves the server ip and port
	-- @return rhost string containing the server ip
	-- @return rport number containing the server port
	getServer = function(self) return ( self.host.ip or self.host ), ( self.port.number or self.port ) end,
	
	
}

-- The response class holds the necessary methods and parameters to parse a response
Response = {
	
	--- Creates a new Response instance
	-- @param str containing the data as received over the socket
	-- @return o table containing a new Response instance
	new = function(self, str)
		local o = {}
		setmetatable(o, self)
        self.__index = self
		o.tbl = stdnse.strsplit("\r\n", str)
		return o
	end,
	
	--- Retrieves a given header value from the response
	-- @param name string containing the name of the header
	-- @return value string containing the header value
	getHeader = function(self,name)
		for _, line in ipairs(self.tbl) do
			local header, value = line:match("^(.-): (.*)$")
			if ( header and header:lower() == name:lower() ) then
			    return value 
			end
		end
	end,
	
	--- Returns the error code from the SIP response
	-- @return err number containing the error code
	getErrorCode = function(self)
		return tonumber(self.tbl[1]:match("SIP/%d%.%d (%d+)"))
	end,
	
	--- Returns the error message returned by the server
	-- @return errmsg string containing the error message
	getErrorMessage = function(self)
		return self.tbl[1]:match("^SIP/%d%.%d %d+ (.+)$")
	end,
	
	--- Returns the message method
	-- @return method string containing the method
	getMethod = function(self)
		return self.tbl[1]:match("^(.-)%s.*SIP/2%.0$")
	end,
	
	--- Returns the authentication data from the SIP response
	-- @return auth string containing the raw authentication data
	getAuthData = function(self)
		local auth = self:getHeader("WWW-Authenticate") or self:getHeader("Proxy-Authenticate")
		if ( auth ) then
			return ( self:getHeader("WWW-Authenticate") and 
					"WWW-Authenticate" or 
					"Proxy-Authenticate"), auth
		end
	end,
	
	--- Retrieves the current sequence number
	-- @return cseq number containing the current sequence number
	getCSeq = function(self)
		local cseq = self:getHeader("CSeq")
		cseq = (cseq and cseq:match("^(%d+)"))
		return (cseq and tonumber(cseq))
	end,
	
}

-- The request class holds the necessary functions and parameters for a basic SIP request
Request = {
	
	--- Creates a new Request instance
	-- @param method string containing the request method to use
	-- @param proto Used protocol, could be "UDP" or "TCP"
	-- @return o containing a new Request instance
	new = function(self, method, proto)
		local o = {}
		setmetatable(o, self)
        self.__index = self
      	
		o.ua = "Nmap NSE"
		o.protocol = proto or "UDP"
		o.expires = 0
		o.allow = "PRACK, INVITE ,ACK, BYE, CANCEL, UPDATE, SUBSCRIBE"
			  .. ",NOTIFY, REFER, MESSAGE, OPTIONS"

		o.maxfwd = 70
		o.method = method
		o.length = 0
		o.cid = Util.get_random_string(60)
		return o
	end,
	
	--- Sets the sessiondata so that session information may be fetched
	-- @param data instance of SessionData
	setSessionData = function(self, data) self.sessdata = data end,
	
	--- Adds a custom header to the request
	-- @param name string containing the header name
	-- @param value string containing the header value
	addHeader = function(self, name, value)
		self.headers = self.headers or {}
		table.insert(self.headers, ("%s: %s"):format(name, value))
	end,
		
	--- Sets the SIP uri
	-- @param uri string containing the SIP uri
	setUri = function(self, uri) self.uri = uri end,
	
	--- Sets an error
	-- @param code number containing the error code
	-- @param msg string containing the error message
	setError = function(self, code, msg) self.error = { code = code, msg = msg } end,
	
	--- Sets the request method
	-- @param method string containing a valid SIP method (@see Method constant)
	setMethod = function(self, method) self.method = method end,
	
	--- Sets the sequence number
	-- @param seq number containing the sequence number to set
	setCseq = function(self, seq) self.cseq = seq end,
	
	--- Sets the allow header
	-- @param allow table containing all of the allowed SIP methods
	setAllow = function(self, allow) self.allow = stdnse.strjoin(", ", allow) end,
	
	--- Sets the request content data
	-- @param string containing the content data
	setContent = function(self, content) self.content = content end,

	--- Sets the requests' content type
	-- @param t string containing the content type
	setContentType = function(self, t) self.content_type = t end,

	--- Sets the supported SIP methods
	-- @param supported string containing the supported methods
	setSupported = function(self, supported) self.supported = supported end,
	
	--- Sets the content-length of the SIP request
	-- @param len number containing the length of the actual request
	setContentLength = function(self, len) self.length = len end,
	
	--- Sets the expires header of the SIP request
	-- @param expires number containing the expire value
	setExpires = function(self, expires) self.expires = expires end,
	
	--- Sets the User Agent being used to connect to the SIP server
	-- @param ua string containing the User-Agent name (defaults to Nmap NSE)
	setUA = function(self, ua) self.ua = ua end,

	--- Sets the caller ID information of the SIP request
	-- @param cid string containing the callers id
	setCallId = function(self, cid) self.cid = cid end,
	
	--- Sets the maximum forwards allowed of this request
	-- @param maxfwd number containing the maximum allowed forwards
	setForwards = function(self, maxfwd) self.maxfwd = maxfwd end,
	
	--- Sets the proxy authentication data
	-- @param auth string containing properly formatted proxy authentication data
	setProxyAuth = function(self, auth) self.proxyauth = auth end,
	
	--- Sets the www authentication data
	-- @param auth string containing properly formatted proxy authentication data
	setWWWAuth = function(self, auth) self.wwwauth = auth end,
			
	--- Specifies the network protocol being used
	-- @param proto should be either "UDP" or "TCP"
	setProtocol = function(self, proto)
		assert( proto == "UDP" or proto == "TCP", ("Unsupported protocol %s"):format(proto))
		self.protocol = proto
	end,

			
	--- Converts the request to a String suitable to be sent over the socket
	-- @return ret string containing the complete request for sending over the socket
	__tostring = function(self)
		local data = {}
		local branch = "z9hG4bK" .. Util.get_random_string(25)
		-- must be at least 32-bit unique
		self.from_tag = self.from_tag or Util.get_random_string(20)
		local sessdata = self.sessdata
		local lhost, lport = sessdata:getClient()
		local rhost, rport = sessdata:getServer()
		
		local name, user, domain = sessdata:getName(), sessdata:getUsername(), sessdata:getDomain()
		
		assert(self.method, "No method specified")
		assert(self.maxfwd, "Max forward not set")
		
		-- if no domain was specified use the remote host instead
		domain = domain or rhost
		
		if ( self.error ) then
			table.insert(data, ("SIP/2.0 %s %d"):format(self.error.msg, self.error.code))
		else
			if ( self.method == Method.ACK ) then
				table.insert(data, ("%s %s:%d SIP/2.0"):format(self.method, self.uri, rport))
			else
				table.insert(data, ("%s %s SIP/2.0"):format(self.method, self.uri))
			end
		end
		table.insert(data, ("Via: SIP/2.0/%s %s:%d;rport;branch=%s"):format(self.protocol, lhost, lport, branch))
		table.insert(data, ("Max-Forwards: %d"):format(self.maxfwd))
		table.insert(data, ("From: \"%s\" <sip:%s@%s>;tag=%s"):format(name, user, domain, self.from_tag))
		
		if ( self.method == Method.INVITE ) then
			table.insert(data, ("To: <sip:%s@%s>"):format(user, domain))
		else
			table.insert(data, ("To: \"%s\" <sip:%s@%s>"):format(name, user, domain))
		end
		
		table.insert(data, ("Call-ID: %s"):format(self.cid))
		
		if ( self.error and self.error.code == Error.OK ) then
			table.insert(data, ("CSeq: %d OPTIONS"):format(self.cseq))
		else
			table.insert(data, ("CSeq: %d %s"):format(self.cseq, self.method))
		end

		if ( self.method ~= Method.ACK ) then
			table.insert(data, ("User-Agent: %s"):format(self.ua))
			table.insert(data, ("Contact: \"%s\" <sip:%s@%s:%d>"):format(name, user, lhost, lport))
			if ( self.expires ) then
				table.insert(data, ("Expires: %d"):format(self.expires))
			end
			if ( self.allow ) then
				table.insert(data, ("Allow: %s"):format(self.allow))
			end
			if ( self.supported ) then
				table.insert(data, ("Supported: %s"):format(self.supported))
			end
			
			if ( not(self.error) ) then
				if ( self.proxyauth ) then 
					table.insert(data, ("Proxy-Authorization: %s"):format(self.proxyauth))
				end
				if ( self.wwwauth ) then
					table.insert(data, ("Authorization: %s"):format(self.wwwauth))
				end
			end

			self.length = (self.content and #self.content +2 or 0)
			if ( self.headers ) then
				for _, val in ipairs(self.headers) do
					table.insert(data, val)
				end
			end
			if ( self.content_type ) then
				table.insert(data, ("Content-Type: %s"):format(self.content_type))
			end
			table.insert(data, ("Content-Length:  %d"):format(self.length))
			table.insert(data, "")

			if ( self.content ) then table.insert(data, self.content) end
			table.insert(data, "")
		else
			self.length = (self.content and #self.content +2 or 0)
			
			table.insert(data, ("Content-Length:  %d"):format(self.length))
			table.insert(data, "")
		end
		return stdnse.strjoin("\r\n", data)
	end,
	
}

-- A minimal Util class with supporting functions
Util = {
	
	--- Generates a random string of the requested length. 
	-- @param length (optional) The length of the string to return. Default: 8. 
	-- @param set    (optional) The set of letters to choose from. Default: upper, lower, numbers, and underscore. 
	-- @return The random string. 
	get_random_string = function(length, set)
		if(length == nil) then
			length = 8
		end

		if(set == nil) then
			set = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_"
		end

		local str = ""

		for i = 1, length, 1 do
			local random = math.random(#set)
			str = str .. string.sub(set, random, random)
		end

		return str
	end
	
}

-- The SIP authentication class, supporting MD5 digest authentication
SipAuth = {
	
	--- Creates a new SipAuth instance
	-- @param auth string containing the auth data as received from the server
	new = function(self, auth)
		local o = {}
		setmetatable(o, self)
        self.__index = self
		o.auth = auth
		return o
	end,
	
	--- Sets the username used for authentication
	-- @param username string containing the name of the user
	setUsername = function(self, username) self.username = username end,
	
	--- Sets the password used for authentication
	-- @param password string containing the password of the user
	setPassword = function(self, password) self.password = password end,
	
	--- Sets the method used for authentication
	-- @param method string containing the method (Usually REGISTER)
	setMethod = function(self, method) self.method = method end,
	
	--- Sets the uri used for authentication
	-- @param uri string containing the uri (Usually sip:<ip>)
	setUri = function(self, uri) self.uri = uri end,
	
	--- Processes and parses a challenge as received from the server
	parseChallenge = function(self)
		if ( not(self.auth) ) then return end
		self.nonce = self.auth:match("nonce=[\"]([^,]-)[\"]")
		self.algorithm = self.auth:match("algorithm=[\"]*(.-)[\"]*,")
		self.realm = self.auth:match("realm=[\"]([^,]-)[\"]")
		assert(self.algorithm:upper() == "MD5", 
			("Unsupported algorithm detected in authentication challenge (%s)"):format(self.algorithm:upper()))
	end,
	
	--- Calculates the authentication response
	-- @return reponse string containing the authentication response
	calculateResponse = function(self)
	
		if ( not(self.nonce) or not(self.algorithm) or not(self.realm) ) then
			self:parseChallenge()
		end
		
		assert(self.username, "SipAuth: No username specified")
		assert(self.password, "SipAuth: No password specified")
		assert(self.method, "SipAuth: No method specified")
		assert(self.uri, "SipAuth: No uri specified")
	
		local result
		if ( self.algorithm == "MD5" ) then
			local HA1 = select(2, bin.unpack("H16", openssl.md5(self.username .. ":" .. self.realm .. ":" .. self.password)))
			local HA2 = select(2, bin.unpack("H16", openssl.md5(self.method .. ":" .. self.uri)))
			result = openssl.md5(HA1:lower() .. ":" .. self.nonce ..":" .. HA2:lower())
		end
		return select(2, bin.unpack("H16", result)):lower()
	end,
	
	--- Creates the complete authentication response
	-- @return auth string containing the complete authentication digest
	createResponse = function(self)
		local response = self:calculateResponse()
		return ("Digest username=\"%s\", realm=\"%s\", nonce=\"%s\"," ..
				" uri=\"%s\", response=\"%s\", algorithm=%s"):format(self.username, self.realm,
					self.nonce, self.uri, response, self.algorithm)
	end,
	
}

-- The Helper class used as main script interface
Helper = {
	
	--- Creates a new instance of the Helper class
	-- @param host table containing the remote host
	-- @param port table containing the remote port
	-- @param options table containing any options to pass along to the
	-- 		session	(@see Session:new for more details)
	-- @return o containing a new instance of the Helper class
	new = function(self, host, port, options)
		local o = {}
		setmetatable(o, self)
        self.__index = self
		local timeout = stdnse.get_script_args("sip.timeout")
		if ( timeout ) then	options.timeout = timeout end
		o.sessdata = SessionData:new()
		o.session = Session:new(host, port, o.sessdata, options)		
		return o
	end,

	--- Connects the helper instance
	connect = function(self) return self.session:connect() end,

	--- Disconnects and closes the helper instance
	close = function(self) return self.session:close() end,	

	--- Sets the credentials used when performing authentication
	-- @param username string containing the username to use for authentication
	-- @param password string containing the password to use for authentication
	setCredentials = function(self, username, password)
		self.sessdata:setUsername(username)
		self.sessdata:setPassword(password)
	end,

	--- Sets the SIP domain
	-- @param domain string containing the domain name
	setDomain = function(self, domain) self.sessdata:setDomain(domain) end,

	--- Register the UAC with the server
	-- @param options table containing zero or more options 
	-- 		(@see Session:register for more details)
	-- @return status true on success, false on failure
	-- @return msg containing the error message if status is false
	register = function(self, options)
		local status, response = self.session:register(options)
		if ( not(status) ) then	return false, response end
		return true
	end,

	options = function(self) return self.session:options() end,
	
	--- Attempts to INVITE the user at uri to a call
	-- @param uri string containing the sip uri
	-- @return status true on success, false on failure
	invite = function(self, uri)
		return self.session:invite(uri)
	end,
	
}

return _ENV;