Module OverSIP::Modules::OutboundMangling

The module OverSIP::Modules::OutboundMangling provides a “hack” for the scenario in which OverSIP behaves as an Outbound Edge Proxy but the SIP registrar behind it does not support the Path mechanism (i.e. Asterisk PBX).

Overview

A common scenario is the following:

     [ Asterisk ]
          |
     [ OverSIP ]
        /   \
     Alice  Bob

• Alice sends a REGISTER.
• OverSIP applies Outbound for the request (maybe because Alice indicates supports for it in the REGISTER or because fix_nat() method was called to force it).
• OverSIP inspects the Contact header of the REGISTER. If it contains a single SIP URI value then it adds a custom ;ov-ob parameter to the Contact URI whose value is the Outbound flow token identifier of the connection.
• After proper authentication Asterisk replies 200 “OK”.
• OverSIP reacts on the received 200 and removes the custom ;ov-ob parameter from the list of SIP URIs in the Contact header.
• Alice receives the 200 response and can find her own binding (untouched) in the Contact header (the mechanism provided by this feature is transparent for peers).
• Later Asterisk sends an INVITE to the registration binding of Alice and arrives to OverSIP. Such an INVITE does not contain a top Route header(s) with the mirrored value of the Path header(s) added by OverSIP (since Asterisk does not support “Path”) so it would be difficult to route such an Outbound incoming request to Alice. But fortunately, the INVITE Request-URI contains the ;ov-ob parameter so OverSIP removes such a parameter and extracts the Outbound token identifier from its value.
• Then OverSIP routes the INVITE to Alice through the Outbound connection associated to the retrieved Outbound token identifier.

Module class methods

add_outbound_to_contact(request)

If Outbound is being used for the connection from which the REGISTER has been received and it contains a single Contact header with a single SIP URI value, then this methods adds a custom ;ov-ob parameter to the Contact URI and returns true. Otherwise returns false.

Parameters

request

An OverSIP::SIP::Request instance.

Example

if request.sip_method == :REGISTER
  proxy = OverSIP::SIP::Proxy.new :asterisk

  # Contact mangling for the case in which the registrar does not support Path.
  OverSIP::Modules::OutboundMangling.add_outbound_to_contact request

  proxy.route request
end

extract_outbound_from_ruri(request)

Inspect the Request-URI of the given request and retrieve the ;ov-ob parameter value.

If the Route headers of the request indicate Outbound support (so the registrar does support Path) then this method does nothing (but just removing the ;ov-ob parameter from the Request-URI) and returns false.

Otherwise the method returns true if the parameter is found in the Request-URI (and thus also removed), false otherwise.

Parameters

request

An OverSIP::SIP::Request instance.

Example

# Requests comming from the registrar.
if request.source_ip == ASTERISK_IP
  # Extract the Outbound flow token from the RURI (if present) to enforce incoming
  # Outbound usage.
  OverSIP::Modules::OutboundMangling.extract_outbound_from_ruri request

  OverSIP::SIP::Proxy.new.route request
end

remove_outbound_from_contact(message)

Inspect the Contact headers of the given SIP request or response and removes the custom ;ov-ob parameter from the SIP URI in which the method add_outbound_to_contact() inserted it previously. It returns false if no Contact header is found.

This method is useful for reverting the “hack” performed in the Contact URI before the 200 “OK” response for a REGISTER is forwarded to the client.

Parameters

message

An OverSIP::SIP::Request or OverSIP::SIP::Response instance.

Example

# Requests comming from the registrar.
if request.source_ip == ASTERISK_IP
  # Extract the Outbound flow token from the RURI (if present) to enforce incoming
  # Outbound usage.
  OverSIP::Modules::OutboundMangling.extract_outbound_from_ruri request

  proxy = OverSIP::SIP::Proxy.new :asterisk

  proxy.on_success_response do |response|
    OverSIP::Modules::OutboundMangling.remove_outbound_from_contact response
  end

  proxy.route request
end