sipvicious sip utils call

Summary

Start a new call

What it does

Generate and handle a new call by sending an INVITE and handling the call traffic.

Tool functionality

The sip call tool is used to test making calls. It does this by making use of the INVITE SIP method and handling the normal traffic, including SIP Re-INVITE and other in-dialog traffic. By default, if the call is picked up by the other party, the tool will play an internal audio file music.raw, if the file does not exist in the current directory and hangup if the tool is terminated.

This behaviour is changed by making use of the invite-mode flag as described in the documentation.

The following is an example logging of the tool when run with the default settings:

INFO[0001] Sending INVITE to 192.168.99.2:5060 for sip:someone@example.org
INFO[0002] Call picked up by sip:else@example.org
INFO[0003] Playing music.raw
INFO[0004] BYE sent, terminating call

Command format

sipvicious sip utils call <target1 [target2 [target3 ...]]> [flags]

Flags

      --codec strings         Specify the codec that should be used for the RTP stream (ulaw|alaw|opus) (default [ulaw,alaw,opus])
  -u, --credentials string    set the username and password in the following format: username:password (e.g. 1000:test123)
  -D, --domain string         override domain name for the SIP address
  -e, --extension string      specify a target extension or SIP URI to call; if not specified, a random numeric extension is used
  -f, --from string           specify a from extension or SIP URI to call from; if not specified, a random numeric extension is used
      --invite-mode strings   specify how to behave during the call attempt; format: action or action:duration; (ignore|hangup-trying|hangup-ringing|hangup-call|never-hangup) (default [hangup-call:30s])
      --register              register before making a call; requires -u
      --rtp-payload string    specify the RTP payload for the audio (e.g. music.wav or 2600hz.raw) or DTMF tones when value starts with dtmf: see the rtp-payload documentation for further details on specifying DTMF tones. (default "music.wav")

Flags inherited from parent commands

      --ca-cert string       TLS CA Certificate
      --client-cert string   TLS client certificate
      --client-key string    TLS client private key
  -C, --config string        configuration file to use (may be JSON, TOML or YAML)
      --debug                set log level to debug
      --logfile string       specify a log filename
      --srtp string          specify if either none, dtls or sdes to enforce SRTP for calls; format: method or method:parameters; see full documentation for details (default "none")
      --templates string     Directory to search for template overrides (default ".")
      --tls-key-log string   TLS key log, - for stdout

Examples

sipvicious sip utils call udp://target:5060 -e 1234
sipvicious sip utils call tls://target:5060 -e 1234@example.com -f 2345@example.org \
	-u 2345:topsecret --rtp-payload ""
sipvicious sip utils call tcp://target:5060 -e hello -f test@example.org --register \
	--invite-mode hangup-ringing:30s --invite-mode hangup-call

Advanced examples

# simple call placing to an extension
sipvicious sip utils call udp://demo.sipvicious.pro:5060 -e 2000 

# register with the given credentials and using a custom from tag
sipvicious sip utils call udp://demo.sipvicious.pro:5060 -u 1000:1500 --register --from 0000@siteonsip.tld -e 2000

# send a dtmf payload via the call
sipvicious sip utils call udp://demo.sipvicious.pro:5060 -e 2000 --rtp-payload dtmf:6

# use a specific invite mode for the call
sipvicious sip utils call udp://demo.sipvicious.pro:5060 --invite-mode hangup-trying -e 2000 

# send a null rtp payload via the call
sipvicious sip utils call tls://demo.sipvicious.pro:5060 --rtp-payload "" --invite-mode never-hangup

# specify a codec for the call and an alternate rtp payload
sipvicious sip utils call udp://demo.sipvicious.pro:5060 -e 2000 --codec ulaw --rtp-payload 2600hz.raw

Exit codes

Standard exit codes for SIPVicious apply. This tool does not run a security test and so exit code 3 has no definition.

Flag: ca-cert

The CA cert can be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: client-cert

The client certificate must be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: client-key

The client key must be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: codec

Specify the codec to be supported for the SDP and also in the RTP stream. Currently supported are ulaw, alaw and opus. You may pass multiple codecs by delimiting using a comma, as follows: ulaw,alaw,opus.

When rates and channels need to be passed, they can be provided after the codec name, separated by a slash. For example: opus/48000/2.

Flag: config

Specify a configuration file which may be a JSON, TOML and YAML config format. To get the default settings and figure out which settings are available, one may run the sipvicious utils dump config command. This is typically used to create a template configuration that can then be edited as need be.

These settings may be overwritten when the corresponding flag is explicitly set, if one is present.

Flag: credentials

Specify valid credentials so that the call can be done authenticated. The following format is used username:password (e.g. 1000:test123).

Flag: debug

Tells the logger to print out debug messages.

Flag: domain

A domain name can be specified so that the SIP URI contains that particular domain rather than the one specified as the target. This is useful for targets that expect a particular domain name.

Flag: extension

This flag allows users to call a particular extension, overriding the default behaviour of calling a random extension. The value can be either just the SIP extension/username (e.g. 1234) or a SIP URI (e.g. sip:user@example.org).

Flag: from

This flag allows users to set the From address, overriding the default behaviour of setting a random extension or the username in the credentials when one is provided. The value can be either just the SIP extension/username (e.g. 1234) or a SIP URI (e.g. sip:user@example.org).

Flag: invite-mode

The flag invite-mode allows one to specify how to behave during a call. The value of this flag could be one of the following actions:

  • ignore which does not wait for SIP INVITE responses
  • hangup-trying which sends a CANCEL as soon as a 100 Trying message is received
  • hangup-ringing which sends a CANCEL as soon as a 180 Ringing is received
  • hangup-call which hangs up (by sending a BYE) when a call is picked up (i.e. when a 200 OK is received)
  • never-hangup which handles the call flow normally without hanging up

Additionally, the action value may be preceded by a colon and a duration value. This duration should be specified when the action should be taken after a specific time (e.g. 2s or 300ms). For example, hangup-ringing:300ms. To hangup a call after 30 seconds, the value of invite-mode should be hangup-call:30s.

NOTE: The following invite-mode values cannot be combined with other invite-mode values:

  • ignore
  • never-hangup

Flag: logfile

When the logfile flag is specified, a log file is created in the location specified and logs are generated in this file instead of being sent to standard output. If the filename ends with a .json file extension, then the output format is in JSON, otherwise it defaults to text format.

Flag: register

Register requires credentials to be passed so that a REGISTER message is sent to authenticate with a registrar server before starting the call. The registration is maintained as per SIP standards, so that authentication does not time out.

Flag: rtp-payload

The rtp-payload parameter allows the setting of a file or DTMF tones that are used for the RTP stream. The following file types are supported:

  • .raw, for raw audio to be passed to the RTP stream without any transcoding
  • .wav, for wave files to be transcoded for the RTP stream

The audio is looped unless a noloop parameter is passed after a comma, e.g. audio.wav,noloop.

If a blank filename, i.e. "", is passed, then no RTP is sent during the call and no SDP is set.

If the value of rtp-payload starts with dtmf:, then the RTP stream will consist of a sequence of DTMF tones instead of audio stream.

The supported alphabet in the DTMF string is 0-9, A-D, *, #, F (flash), and , (comma) for a pause equivalent to one digit in length. The other side may not support all of these.

Example: When Asterisk is configured to allow call forwarding with feature code #1, the following value to rtp-payload will forward the call to 123456: dtmf:#1,,,123456.

Flag: srtp

The srtp flag when specified, allows users to set the SRTP mode. By default, outgoing calls do not make use of SRTP, while incoming calls automatically handle SRTP depending on the SDP body of the incoming INVITE message. When the srtp flag is set to none, incoming calls do not make use of SRTP, regardless of the SDP body in an incoming INVITE. The srtp mode can also be either dtls or sdes. In both dtls and sdes modes, the parameters are not required and will be generated randomly as need be.

Options for both dtls and sdes mode may be passed after a colon. For example:

  • TODO: --srtp dtls:cert.crt:cert.key[:ca.crt] where the first argument after the mode (dtls) is the public certificate cert.crt, then the private key cert.key and finally, the optional certificate authority file ca.crt
  • --srtp sdes:d0RmdmcmVCspeEc3QGZiNWpVLFJhQX1cfHAwJSoj where the argument is the base64 encoded cryptographic master key appended with the master salt.

Note that in the case of sdes key, the master key needs to be a valid length, which is 30 octets, for the default crypto-suite AES_CM_128_HMAC_SHA1_80.

Flag: templates

Allows one to set the template directory which is used to load (or save) the SIP templates.

To get the default SIP templates, make use of the sipvicious sip utils dump templates command.

Flag: tls-key-log

The TLS key log creates a file with the TLS key that can then be used to decrypt the TLS stream in tools that support it, such as Wireshark.

Future enhancements

  • Support for RTP payload for DTMF RFC-4733
  • Codec support beyond the G711
  • SDES SRTP support
  • DTLS SRTP support, especially useful in WebRTC environments
  • STUN and TURN support, also especially useful in WebRTC environments