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): 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): 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:

true on success false on failure
error message if status is false

Connection.connect (self)

Connects to the server

Parameters

self

Return values:

status containing true on success and false on failure
err containing the error message (if status is false)

Connection.getClient (self)

Retrieves the client ip and port

Parameters

self

Return values:

lhost string containing the local ip
lport number containing the local port

Connection.getServer (self)

Retrieves the server ip and port

Parameters

self

Return values:

rhost string containing the server ip
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:

status true on success, false on failure
error message if status is false

Connection.send (self, data)

Sends the data over the socket

Parameters

self
data

Return values:

status true on success, false on failure
error message if status is false

Helper.close (self)

Disconnects and closes the helper instance

Parameters

self

Return values:

true on success, false on failure
err string containing error message

Helper.connect (self)

Connects the helper instance

Parameters

self

Return values:

true on success, false on failure
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

Parameters

self

Return values:

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

Parameters

self

Return values:

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

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)

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)

Prepares and sends the challenge response authentication to the server

Parameters

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

Return values:

status true on success false on failure
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:

true on success, false on failure
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:

status true on success, false on failure
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:

status true on success false on failure
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:

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

Parameters

self

Return values:

status true on success, false on failure
msg string containing the error message (if status is false)

SessionData.getClient (self)

Retrieves the client IP and port

Parameters

self

Return values:

host string containing the client IP
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:

host string containing the server IP
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

Library sip

Script Arguments

Functions

Functions

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

See also:

Parameters

Return values:

See also:

Parameters

Return values:

See also:

Parameters

Parameters

Parameters

Return value:

Parameters

Parameters

Return value:

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Library `sip`