Library sip

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:

  • SessionData - Holds session data for the SIP session
  • Session - Contains application functionality related to the implemented SIP methods.
  • Connection - A class containing code related to socket communication.
  • Response - A class containing code for handling SIP responses
  • Request - A class containing code for handling SIP requests
  • SIPAuth - A class containing code related to SIP Authentication
  • Helper - A class containing code used as a primary interface by scripts

Author:

  • Patrik Karlsson <patrik@cqure.net>

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/sip.lua

Script Arguments

sip.timeout

- specifies the session (socket) timeout in seconds

Functions

Connection.close (self)

Closes the communication channel (socket)

Connection.connect (self)

Connects to the server

Connection.getClient (self)

Retrieves the client ip and port

Connection.getServer (self)

Retrieves the server ip and port

Connection.new (self, host, port)

Creates a new SIP Connection

Connection.recv (self)

Receives data from the socket

Connection.send (self, data)

Sends the data over the socket

Helper.close (self)

Disconnects and closes the helper instance

Helper.connect (self)

Connects the helper instance

Helper.invite (self, uri)

Attempts to INVITE the user at uri to a call

Helper.new (self, host, port, options)

Creates a new instance of the Helper class

Helper.register (self)

Sends an option request to the server and handles the response

Helper.register (self)

Sends an option request to the server and handles the response

Helper.setCredentials (self, username, password)

Sets the credentials used when performing authentication

Helper.setDomain (self, domain)

Sets the SIP domain

Request.__tostring (self)

Converts the request to a String suitable to be sent over the socket Called automatically by Lua's tostring function.

Request.addHeader (self, name, value)

Adds a custom header to the request

Request.new (self, method, proto)

Creates a new Request instance

Request.setAllow (self, allow)

Sets the allow header

Request.setCallId (self, cid)

Sets the caller ID information of the SIP request

Request.setContent (self, content, string)

Sets the request content data

Request.setContentLength (self, len)

Sets the content-length of the SIP request

Request.setContentType (self, t)

Sets the requests' content type

Request.setCseq (self, seq)

Sets the sequence number

Request.setError (self, code, msg)

Sets an error

Request.setExpires (self, expires)

Sets the expires header of the SIP request

Request.setForwards (self, maxfwd)

Sets the maximum forwards allowed of this request

Request.setMethod (self, method)

Sets the request method

Request.setProtocol (self, proto)

Specifies the network protocol being used

Request.setProxyAuth (self, auth)

Sets the proxy authentication data

Request.setSessionData (self, data)

Sets the sessiondata so that session information may be fetched

Request.setSupported (self, supported)

Sets the supported SIP methods

Request.setUA (self, ua)

Sets the User Agent being used to connect to the SIP server

Request.setUri (self, uri)

Sets the SIP uri

Request.setWWWAuth (self, auth)

Sets the www authentication data

Response.getAuthData (self)

Returns the authentication data from the SIP response

Response.getCSeq (self)

Retrieves the current sequence number

Response.getErrorCode (self)

Returns the error code from the SIP response

Response.getErrorMessage (self)

Returns the error message returned by the server

Response.getHeader (self, name)

Retrieves a given header value from the response

Response.getMethod (self)

Returns the message method

Response.new (self, str)

Creates a new Response instance

Session.authenticate (self, request, response, authdata)

Prepares and sends the challenge response authentication to the server

Session.close (self)

Closes the session TODO: We should probably send some "closing" packets here

Session.connect (self)

Connect the session

Session.exch (self, request)

Sends a SIP Request and receives the Response

Session.invite (self, uri)

Sends a SIP invite

Session.new (self, host, port, sessdata, options)

Creates a new session instance

Session.options (self)

Sends an option request to the server and handles the response

Session.register (self)

Sends a register request to the server

SessionData.getClient (self)

Retrieves the client IP and port

SessionData.getDomain (self)

Retrieves the SIP domain

SessionData.getName (self)

Retrieves the SIP users full name

SessionData.getPassword (self)

Retrieves the session password

SessionData.getServer (self)

Retrieves the server IP and port

SessionData.getUsername (self)

Retrieves the username

SessionData.new (self, o)

Creates a new instance of SessionData

SessionData.setClient (self, host, port)

Sets the ip and port of the client

SessionData.setDomain (self, domain)

Sets the SIP domain

SessionData.setName (self, name)

Sets the SIP users Full Name

SessionData.setPassword (self, pass)

Sets the session password

SessionData.setServer (self, host, port)

Sets the ip and port of the remote server

SessionData.setUsername (self, user)

Sets the session username

SipAuth.calculateResponse (self)

Calculates the authentication response

SipAuth.createResponse (self)

Creates the complete authentication response

SipAuth.new (self, auth)

Creates a new SipAuth instance

SipAuth.parseChallenge (self)

Processes and parses a challenge as received from the server

SipAuth.setMethod (self, method)

Sets the method used for authentication

SipAuth.setPassword (self, password)

Sets the password used for authentication

SipAuth.setUri (self, uri)

Sets the uri used for authentication

SipAuth.setUsername (self, username)

Sets the username used for authentication

Functions

Connection.close (self)

Closes the communication channel (socket)

Parameters

self
 

Return values:

  1. true on success false on failure
  2. error message if status is false
Connection.connect (self)

Connects to the server

Parameters

self
 

Return values:

  1. status containing true on success and false on failure
  2. err containing the error message (if status is false)
Connection.getClient (self)

Retrieves the client ip and port

Parameters

self
 

Return values:

  1. lhost string containing the local ip
  2. lport number containing the local port
Connection.getServer (self)

Retrieves the server ip and port

Parameters

self
 

Return values:

  1. rhost string containing the server ip
  2. rport number containing the server port
Connection.new (self, host, port)

Creates a new SIP Connection

Parameters

self
 
host
table containing the host to connect to
port
table containing the port to connect to

Return value:

a new Connection instance
Connection.recv (self)

Receives data from the socket

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. error message if status is false
Connection.send (self, data)

Sends the data over the socket

Parameters

self
 
data
 

Return values:

  1. status true on success, false on failure
  2. error message if status is false
Helper.close (self)

Disconnects and closes the helper instance

Parameters

self
 

Return values:

  1. true on success, false on failure
  2. err string containing error message
Helper.connect (self)

Connects the helper instance

Parameters

self
 

Return values:

  1. true on success, false on failure
  2. err string containing error message
Helper.invite (self, uri)

Attempts to INVITE the user at uri to a call

Parameters

self
 
uri
string containing the sip uri

Return value:

status true on success, false on failure
Helper.new (self, host, port, options)

Creates a new instance of the Helper class

Parameters

self
 
host
table containing the remote host
port
table containing the remote port
options
table containing any options to pass along to the session

Return value:

a new instance of the Helper class

See also:

Helper.register (self)

Sends an option request to the server and handles the response

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. Response if status is true, nil else.

See also:

Helper.register (self)

Sends an option request to the server and handles the response

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. Response if status is true, nil else.

See also:

Helper.setCredentials (self, username, password)

Sets the credentials used when performing authentication

Parameters

self
 
username
string containing the username to use for authentication
password
string containing the password to use for authentication
Helper.setDomain (self, domain)

Sets the SIP domain

Parameters

self
 
domain
string containing the domain name
Request.__tostring (self)

Converts the request to a String suitable to be sent over the socket Called automatically by Lua's tostring function.

Parameters

self
 

Return value:

ret string containing the complete request for sending over the socket
Request.addHeader (self, name, value)

Adds a custom header to the request

Parameters

self
 
name
string containing the header name
value
string containing the header value
Request.new (self, method, proto)

Creates a new Request instance

Parameters

self
 
method
string containing the request method to use
proto
Used protocol, could be "UDP" or "TCP"

Return value:

a new Request instance
Request.setAllow (self, allow)

Sets the allow header

Parameters

self
 
allow
table containing all of the allowed SIP methods
Request.setCallId (self, cid)

Sets the caller ID information of the SIP request

Parameters

self
 
cid
string containing the callers id
Request.setContent (self, content, string)

Sets the request content data

Parameters

self
 
content
 
string
containing the content data
Request.setContentLength (self, len)

Sets the content-length of the SIP request

Parameters

self
 
len
number containing the length of the actual request
Request.setContentType (self, t)

Sets the requests' content type

Parameters

self
 
t
string containing the content type
Request.setCseq (self, seq)

Sets the sequence number

Parameters

self
 
seq
number containing the sequence number to set
Request.setError (self, code, msg)

Sets an error

Parameters

self
 
code
number containing the error code
msg
string containing the error message
Request.setExpires (self, expires)

Sets the expires header of the SIP request

Parameters

self
 
expires
number containing the expire value
Request.setForwards (self, maxfwd)

Sets the maximum forwards allowed of this request

Parameters

self
 
maxfwd
number containing the maximum allowed forwards
Request.setMethod (self, method)

Sets the request method

Parameters

self
 
method
string containing a valid SIP method
Request.setProtocol (self, proto)

Specifies the network protocol being used

Parameters

self
 
proto
should be either "UDP" or "TCP"
Request.setProxyAuth (self, auth)

Sets the proxy authentication data

Parameters

self
 
auth
string containing properly formatted proxy authentication data
Request.setSessionData (self, data)

Sets the sessiondata so that session information may be fetched

Parameters

self
 
data
instance of SessionData
Request.setSupported (self, supported)

Sets the supported SIP methods

Parameters

self
 
supported
string containing the supported methods
Request.setUA (self, ua)

Sets the User Agent being used to connect to the SIP server

Parameters

self
 
ua
string containing the User-Agent name (defaults to Nmap NSE)
Request.setUri (self, uri)

Sets the SIP uri

Parameters

self
 
uri
string containing the SIP uri
Request.setWWWAuth (self, auth)

Sets the www authentication data

Parameters

self
 
auth
string containing properly formatted proxy authentication data
Response.getAuthData (self)

Returns the authentication data from the SIP response

Parameters

self
 

Return value:

auth string containing the raw authentication data
Response.getCSeq (self)

Retrieves the current sequence number

Parameters

self
 

Return value:

cseq number containing the current sequence number
Response.getErrorCode (self)

Returns the error code from the SIP response

Parameters

self
 

Return value:

err number containing the error code
Response.getErrorMessage (self)

Returns the error message returned by the server

Parameters

self
 

Return value:

errmsg string containing the error message
Response.getHeader (self, name)

Retrieves a given header value from the response

Parameters

self
 
name
string containing the name of the header

Return value:

value string containing the header value
Response.getMethod (self)

Returns the message method

Parameters

self
 

Return value:

method string containing the method
Response.new (self, str)

Creates a new Response instance

Parameters

self
 
str
containing the data as received over the socket

Return value:

a new Response instance
Session.authenticate (self, request, response, authdata)

Prepares and sends the challenge response authentication to the server

Parameters

self
 
request
instance of the request object requiring authentication
response
 
authdata
string containing authentication data

Return values:

  1. status true on success false on failure
  2. err string containing an error message if status is false
Session.close (self)

Closes the session TODO: We should probably send some "closing" packets here

Parameters

self
 

Return value:

true on success, false on failure
Session.connect (self)

Connect the session

Parameters

self
 

Return values:

  1. true on success, false on failure
  2. err string containing error message
Session.exch (self, request)

Sends a SIP Request and receives the Response

Parameters

self
 
request
instance of Request

Return values:

  1. status true on success, false on failure
  2. a new Response instance or error message if status is false
Session.invite (self, uri)

Sends a SIP invite

Parameters

self
 
uri
The address to invite

Return values:

  1. status true on success false on failure
  2. err string containing an error message if status is false
Session.new (self, host, port, sessdata, options)

Creates a new session instance

Parameters

self
 
host
table containing the remote host to connect to
port
table containing the remote port to connect to
sessdata
instance of SessionData
options
table containing zero or more of the following options expires - the expire value in seconds timeout - the socket timeout in seconds

Return value:

a new instance of the Session class
Session.options (self)

Sends an option request to the server and handles the response

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. Response if status is true, nil else.

See also:

Session.register (self)

Sends a register request to the server

Parameters

self
 

Return values:

  1. status true on success, false on failure
  2. msg string containing the error message (if status is false)
SessionData.getClient (self)

Retrieves the client IP and port

Parameters

self
 

Return values:

  1. host string containing the client IP
  2. port number containing the client port
SessionData.getDomain (self)

Retrieves the SIP domain

Parameters

self
 

Return value:

domain string containing the SIP domain
SessionData.getName (self)

Retrieves the SIP users full name

Parameters

self
 

Return value:

name string containing the users full name
SessionData.getPassword (self)

Retrieves the session password

Parameters

self
 

Return value:

pass string containing the session password
SessionData.getServer (self)

Retrieves the server IP and port

Parameters

self
 

Return values:

  1. host string containing the server IP
  2. port number containing the server port
SessionData.getUsername (self)

Retrieves the username

Parameters

self
 

Return value:

user string containing the sessions username
SessionData.new (self, o)

Creates a new instance of SessionData

Parameters

self
 
o
 

Return value:

o an instance of SessionData
SessionData.setClient (self, host, port)

Sets the ip and port of the client

Parameters

self
 
host
string containing the ip of the client
port
number containing the port of the client
SessionData.setDomain (self, domain)

Sets the SIP domain

Parameters

self
 
domain
string containing the SIP domain
SessionData.setName (self, name)

Sets the SIP users Full Name

Parameters

self
 
name
string containing the full name of the user
SessionData.setPassword (self, pass)

Sets the session password

Parameters

self
 
pass
string containing the password
SessionData.setServer (self, host, port)

Sets the ip and port of the remote server

Parameters

self
 
host
string containing the ip of the remote server
port
number containing the port of the remote server
SessionData.setUsername (self, user)

Sets the session username

Parameters

self
 
user
string containing the username
SipAuth.calculateResponse (self)

Calculates the authentication response

Parameters

self
 

Return value:

response string containing the authentication response
SipAuth.createResponse (self)

Creates the complete authentication response

Parameters

self
 

Return value:

auth string containing the complete authentication digest
SipAuth.new (self, auth)

Creates a new SipAuth instance

Parameters

self
 
auth
string containing the auth data as received from the server

Return value:

a SipAuth instance
SipAuth.parseChallenge (self)

Processes and parses a challenge as received from the server

Parameters

self
 
SipAuth.setMethod (self, method)

Sets the method used for authentication

Parameters

self
 
method
string containing the method (Usually REGISTER)
SipAuth.setPassword (self, password)

Sets the password used for authentication

Parameters

self
 
password
string containing the password of the user
SipAuth.setUri (self, uri)

Sets the uri used for authentication

Parameters

self
 
uri
string containing the uri (Usually sip:<ip>)
SipAuth.setUsername (self, username)

Sets the username used for authentication

Parameters

self
 
username
string containing the name of the user