sipvicious sip utils templates test

Summary

Test the template for a specific SIP method

What it does

Try the template for a specific method or filename to test how its variables are populated

Tool functionality

This tool allows testing of SIP message templates without actually performing any network activity. A SIP message argument or template file needs to be passed which is then interpreted according to the default variables or flags passed to this command. This tool works by passing the template to the standard Golang text template engine, populating variables as described in the template documentation.

The following is an example of the logging from the tool:

INFO[2020-05-28 16:33:21] OPTIONS sip:127.0.0.1 SIP/2.0
Via: SIP/2.0/TCP 127.0.0.1:10011;rport;branch=z9hG4bK-PSofOELPKrhkFgPz
Max-Forwards: 70
From: <sip:YERB8csX@127.0.0.1>;tag=aFPMyXqXc2XeMfCn
To: <sip:05HgJF23@127.0.0.1>
Call-ID: 9IHDjUHiahwgrOhZ
CSeq: 1 OPTIONS
Accept: application/sdp
Content-Length: 0
 
INFO[2020-05-28 16:33:21] successfully returned

Command format

sipvicious sip utils templates test [method] [flags]

Flags

      --codec strings        Specify the codec that should be used for the SDP (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

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 templates test options
sipvicious sip utils templates test optionsrequest.tmpl
sipvicious sip utils templates test register invite

Advanced examples

# test the options template with authentication
sipvicious sip utils templates test options -u username:password
# test the register template, specifying the domain and SIP extension
sipvicious sip utils templates test register -D demo.sipvicious.pro -e 1200
# test the invite template, specifying opus as the only codec allowed in the SDP
sipvicious sip utils templates test --codec opus invite

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 alaw, ulaw, opus, gsm, g723, lpc, g722, g728, g729, h261 and h263. 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

If credentials are passed, the SIP message produced contains the authorization header with a random nonce, computing the MD5 digest hash based on the username and password passed. 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 a default domain.

Flag: extension

This flag sets the To address to a particular extension, overriding the default behaviour of setting 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 sets 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: 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: 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.