--- 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;
@KyuuKazami