sip NSE Library — Nmap Scripting Engine documentation (original) (raw)

Script Arguments Functions

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:

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:

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:

• Session.new

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:

• Response

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:

• Response

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

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

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:

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 optionsexpires - the expire value in secondstimeout - 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:

• Response

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

SipAuth.setUsername (self, username)

Sets the username used for authentication

Parameters

self

username

string containing the name of the user