From f5be40278f87ffb6ad7c43362f66aaaf8acf3110 Mon Sep 17 00:00:00 2001 From: dmiller Date: Tue, 4 Mar 2014 17:05:00 +0000 Subject: [PATCH] Update sip.lua NSEdoc https://secwiki.org/w/Nmap/Code_Standards#NSEdoc_best-practices --- nselib/sip.lua | 142 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 112 insertions(+), 30 deletions(-) diff --git a/nselib/sip.lua b/nselib/sip.lua index c153df824..22c0afd63 100644 --- a/nselib/sip.lua +++ b/nselib/sip.lua @@ -1,35 +1,30 @@ --- A SIP library supporting a limited subset of SIP commands and methods -- -- The library currently supports the following methods: --- * REGISTER, INVITE & OPTIONS +-- * REGISTER +-- * INVITE +-- * OPTIONS -- -- Overview -- -------- -- The library consists of the following classes: -- --- o SessionData +-- * SessionData -- - Holds session data for the SIP session --- --- o Session +-- * Session -- - Contains application functionality related to the implemented -- SIP methods. --- --- o Connection +-- * Connection -- - A class containing code related to socket communication. --- --- o Response +-- * Response -- - A class containing code for handling SIP responses --- --- o Request +-- * Request -- - A class containing code for handling SIP requests --- --- o Util +-- * Util -- - A class containing static utility functions --- --- o SIPAuth +-- * SIPAuth -- - A class containing code related to SIP Authentication --- --- o Helper +-- * Helper -- - A class containing code used as a primary interface by scripts -- -- @@ -76,7 +71,8 @@ Error = { -- The SessionData class SessionData = { - --- Creates a new instance of sessiondata + --- Creates a new instance of SessionData + -- @name SessionData.new -- @return o an instance of SessionData new = function(self, o) local o = o or {} @@ -87,54 +83,66 @@ SessionData = { end, --- Sets the session username + -- @name SessionData.setUsername -- @param user string containing the username setUsername = function(self, user) self.user = user end, --- Sets the session password + -- @name SessionData.setPassword -- @param pass string containing the password setPassword = function(self, pass) self.pass = pass end, --- Sets the SIP domain + -- @name SessionData.setDomain -- @param domain string containing the SIP domain setDomain = function(self, domain) self.domain = domain end, --- Sets the ip and port of the remote server + -- @name SessionData.setServer -- @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 + -- @name SessionData.setClient -- @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 + -- @name SessionData.setName -- @param name string containing the full name of the user setName = function(self, name) self.name = name end, --- Retrieves the username + -- @name SessionData.getUsername -- @return user string containing the sessions username getUsername = function(self) return self.user end, --- Retrieves the session password + -- @name SessionData.getPassword -- @return pass string containing the session password getPassword = function(self) return self.pass end, --- Retrieves the SIP domain + -- @name SessionData.getDomain -- @return domain string containing the SIP domain getDomain = function(self) return self.domain end, --- Retrieves the client IP and port + -- @name SessionData.getClient -- @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 + -- @name SessionData.getServer -- @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 + -- @name SessionData.getName -- @return name string containing the users full name getName = function(self) return self.name or "Nmap NSE" end, } @@ -143,13 +151,14 @@ SessionData = { Session = { --- Creates a new session instance + -- @name Session.new -- @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 -- expires - the expire value in seconds -- timeout - the socket timeout in seconds - -- @return o containing a new instance of the Session class + -- @return a new instance of the Session class new = function(self, host, port, sessdata, options) local o = {} setmetatable(o, self) @@ -166,6 +175,7 @@ Session = { end, --- Connect the session + -- @name Session.connect -- @return true on success, false on failure -- @return err string containing error message connect = function(self) @@ -184,11 +194,15 @@ Session = { --- Closes the session -- TODO: We should probably send some "closing" packets here + -- @name Session.close -- @return true on success, false on failure close = function(self) return self.conn:close() end, - --- Sends and SIP invite - -- @param uri + --- Sends a SIP invite + -- @name Session.invite + -- @param uri The address to invite + -- @return status true on success false on failure + -- @return err string containing an error message if status is false invite = function(self, uri) local request = Request:new(Method.INVITE, self.protocol) @@ -246,6 +260,7 @@ Session = { end, --- Prepares and sends the challenge response authentication to the server + -- @name Session.authenticate -- @param request instance of the request object requiring authentication -- @param authdata string containing authentication data -- @return status true on success false on failure @@ -278,10 +293,10 @@ Session = { end, --- Sends a SIP Request and receives the Response + -- @name Session.exch -- @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 + -- @return a new Response instance or error message if status is false exch = function(self, request) request:setCseq(self.cseq) @@ -295,6 +310,7 @@ Session = { end, --- Sends a register request to the server + -- @name Session.register -- @return status true on success, false on failure -- @return msg string containing the error message (if status is false) register = function(self) @@ -329,8 +345,10 @@ Session = { end, --- Sends an option request to the server and handles the response + -- @name Session.options -- @return status true on success, false on failure - -- @return response if status is true, nil else. + -- @return Response if status is true, nil else. + -- @see Response options = function(self) local req = Request:new(Method.OPTIONS, self.protocol) req:setUri("sip:" .. self.sessdata:getServer()) @@ -350,9 +368,10 @@ Session = { Connection = { --- Creates a new SIP Connection + -- @name Connection.new -- @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 + -- @return a new Connection instance new = function(self, host, port) local o = {} setmetatable(o, self) @@ -364,6 +383,7 @@ Connection = { end, --- Connects to the server + -- @name Connection.connect -- @return status containing true on success and false on failure -- @return err containing the error message (if status is false) connect = function(self) @@ -379,29 +399,37 @@ Connection = { end, --- Sends the data over the socket + -- @name Connection.send -- @return status true on success, false on failure + -- @return error message if status is false send = function(self, data) return self.socket:send(data) end, --- Receives data from the socket + -- @name Connection.recv -- @return status true on success, false on failure + -- @return error message if status is false recv = function(self) return self.socket:receive() end, --- Closes the communication channel (socket) + -- @name Connection.close -- @return true on success false on failure + -- @return error message if status is false close = function(self) return self.socket:close() end, --- Retrieves the client ip and port + -- @name Connection.getClient -- @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 + -- @name Connection.getServer -- @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, @@ -413,8 +441,9 @@ Connection = { Response = { --- Creates a new Response instance + -- @name Response.new -- @param str containing the data as received over the socket - -- @return o table containing a new Response instance + -- @return a new Response instance new = function(self, str) local o = {} setmetatable(o, self) @@ -424,6 +453,7 @@ Response = { end, --- Retrieves a given header value from the response + -- @name Response.getHeader -- @param name string containing the name of the header -- @return value string containing the header value getHeader = function(self,name) @@ -436,24 +466,28 @@ Response = { end, --- Returns the error code from the SIP response + -- @name Response.getErrorCode -- @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 + -- @name Response.getErrorMessage -- @return errmsg string containing the error message getErrorMessage = function(self) return self.tbl[1]:match("^SIP/%d%.%d %d+ (.+)$") end, --- Returns the message method + -- @name Response.getMethod -- @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 + -- @name Response.getAuthData -- @return auth string containing the raw authentication data getAuthData = function(self) local auth = self:getHeader("WWW-Authenticate") or self:getHeader("Proxy-Authenticate") @@ -465,6 +499,7 @@ Response = { end, --- Retrieves the current sequence number + -- @name Response.getCSeq -- @return cseq number containing the current sequence number getCSeq = function(self) local cseq = self:getHeader("CSeq") @@ -478,9 +513,10 @@ Response = { Request = { --- Creates a new Request instance + -- @name Request.new -- @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 + -- @return a new Request instance new = function(self, method, proto) local o = {} setmetatable(o, self) @@ -500,10 +536,12 @@ Request = { end, --- Sets the sessiondata so that session information may be fetched + -- @name Request.setSessionData -- @param data instance of SessionData setSessionData = function(self, data) self.sessdata = data end, --- Adds a custom header to the request + -- @name Request.addHeader -- @param name string containing the header name -- @param value string containing the header value addHeader = function(self, name, value) @@ -512,67 +550,83 @@ Request = { end, --- Sets the SIP uri + -- @name Request.setUri -- @param uri string containing the SIP uri setUri = function(self, uri) self.uri = uri end, --- Sets an error + -- @name Request.setError -- @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) + -- @name Request.setMethod + -- @param method string containing a valid SIP method setMethod = function(self, method) self.method = method end, --- Sets the sequence number + -- @name Request.setCseq -- @param seq number containing the sequence number to set setCseq = function(self, seq) self.cseq = seq end, --- Sets the allow header + -- @name Request.setAllow -- @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 + -- @name Request.setContent -- @param string containing the content data setContent = function(self, content) self.content = content end, --- Sets the requests' content type + -- @name Request.setContentType -- @param t string containing the content type setContentType = function(self, t) self.content_type = t end, --- Sets the supported SIP methods + -- @name Request.setSupported -- @param supported string containing the supported methods setSupported = function(self, supported) self.supported = supported end, --- Sets the content-length of the SIP request + -- @name Request.setContentLength -- @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 + -- @name Request.setExpires -- @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 + -- @name Request.setUA -- @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 + -- @name Request.setCallId -- @param cid string containing the callers id setCallId = function(self, cid) self.cid = cid end, --- Sets the maximum forwards allowed of this request + -- @name Request.setForwards -- @param maxfwd number containing the maximum allowed forwards setForwards = function(self, maxfwd) self.maxfwd = maxfwd end, --- Sets the proxy authentication data + -- @name Request.setProxyAuth -- @param auth string containing properly formatted proxy authentication data setProxyAuth = function(self, auth) self.proxyauth = auth end, --- Sets the www authentication data + -- @name Request.setWWWAuth -- @param auth string containing properly formatted proxy authentication data setWWWAuth = function(self, auth) self.wwwauth = auth end, --- Specifies the network protocol being used + -- @name Request.setProtocol -- @param proto should be either "UDP" or "TCP" setProtocol = function(self, proto) assert( proto == "UDP" or proto == "TCP", ("Unsupported protocol %s"):format(proto)) @@ -581,6 +635,8 @@ Request = { --- Converts the request to a String suitable to be sent over the socket + -- Called automatically by Lua's tostring function. + -- @name Request.__tostring -- @return ret string containing the complete request for sending over the socket __tostring = function(self) local data = {} @@ -677,6 +733,7 @@ Request = { Util = { --- Generates a random string of the requested length. + -- @name Util.get_random_string -- @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. @@ -705,7 +762,9 @@ Util = { SipAuth = { --- Creates a new SipAuth instance + -- @name SipAuth.new -- @param auth string containing the auth data as received from the server + -- @return a SipAuth instance new = function(self, auth) local o = {} setmetatable(o, self) @@ -715,22 +774,27 @@ SipAuth = { end, --- Sets the username used for authentication + -- @name SipAuth.setUsername -- @param username string containing the name of the user setUsername = function(self, username) self.username = username end, --- Sets the password used for authentication + -- @name SipAuth.setPassword -- @param password string containing the password of the user setPassword = function(self, password) self.password = password end, --- Sets the method used for authentication + -- @name SipAuth.setMethod -- @param method string containing the method (Usually REGISTER) setMethod = function(self, method) self.method = method end, --- Sets the uri used for authentication + -- @name SipAuth.setUri -- @param uri string containing the uri (Usually sip:) setUri = function(self, uri) self.uri = uri end, --- Processes and parses a challenge as received from the server + -- @name SipAuth.parseChallenge parseChallenge = function(self) if ( not(self.auth) ) then return end self.nonce = self.auth:match("nonce=[\"]([^,]-)[\"]") @@ -741,6 +805,7 @@ SipAuth = { end, --- Calculates the authentication response + -- @name SipAuth.calculateResponse -- @return response string containing the authentication response calculateResponse = function(self) @@ -763,6 +828,7 @@ SipAuth = { end, --- Creates the complete authentication response + -- @name SipAuth.createResponse -- @return auth string containing the complete authentication digest createResponse = function(self) local response = self:calculateResponse() @@ -777,11 +843,12 @@ SipAuth = { Helper = { --- Creates a new instance of the Helper class + -- @name Helper.new -- @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 + -- @param options table containing any options to pass along to the session + -- @see Session.new + -- @return a new instance of the Helper class new = function(self, host, port, options) local o = {} setmetatable(o, self) @@ -794,12 +861,19 @@ Helper = { end, --- Connects the helper instance + -- @name Helper.connect + -- @return true on success, false on failure + -- @return err string containing error message connect = function(self) return self.session:connect() end, --- Disconnects and closes the helper instance + -- @name Helper.close + -- @return true on success, false on failure + -- @return err string containing error message close = function(self) return self.session:close() end, --- Sets the credentials used when performing authentication + -- @name Helper.setCredentials -- @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) @@ -808,10 +882,12 @@ Helper = { end, --- Sets the SIP domain + -- @name Helper.setDomain -- @param domain string containing the domain name setDomain = function(self, domain) self.sessdata:setDomain(domain) end, --- Register the UAC with the server + -- @name Helper.register -- @param options table containing zero or more options -- (@see Session:register for more details) -- @return status true on success, false on failure @@ -822,9 +898,15 @@ Helper = { return true end, + --- Sends an option request to the server and handles the response + -- @name Helper.register + -- @return status true on success, false on failure + -- @return Response if status is true, nil else. + -- @see Response options = function(self) return self.session:options() end, --- Attempts to INVITE the user at uri to a call + -- @name Helper.invite -- @param uri string containing the sip uri -- @return status true on success, false on failure invite = function(self, uri)