Module OverSIP::Modules::UserAssertion

The module OverSIP::Modules::UserAssertion provides methods for associating an authenticated SIP user to its associated connection (TCP/TLS/WS/WSS) so after the first authentication takes places the client does not need to authenticate again against the proxy/registrar behind OverSIP (assuming that such a proxy/registrar implements the P-Asserted-Identity header as per RFC 3325).

Overview

A common scenario is the following:

  [ SIP registrar ]
          |
     [ OverSIP ]
        /   \
     Alice  Bob

• Alice sends a REGISTER via TCP.
• OverSIP forwards the REGISTER to the registrar.
• The registrar replies 401 “Unauthorized”.
• Alice re-sends the REGISTER with credentials.
• The registrar replies 200 “OK”.
• OverSIP reacts on the received 200 response and associates the From URI (i.e. sip:alice@atlanta.com) of the REGISTER request to the TCP connection from Alice.
• Later Alice sends an INVITE.
• OverSIP inspects the From URI of the INVITE. It is sip:alice@atlanta.com so it matches the SIP URI associated to the TCP connection.
• Then OverSIP adds a header P-Asserted-Identity: <sip:alice@atlanta.com> and routes the INVITE to the registrar.
• The registrar considers OverSIP a “trusted node” (as described in RFC 3325) so it trusts the value of the P-Asserted-Identity header and does not ask Alice for authentication.

Module class methods

assert_connection(message)

Associates the From URI of the received SIP request to its connection. It can also be applied when processing a SIP response (which means that the From URI is associated to the connection from which the request was received).

It returns false if the request was received via UDP or from a TCP/TLS connection initiated by OverSIP.

It returns false if the received request contains a P-Preferred-Identity.

Otherwise the method returns true and sets an :asserted_user entry in the cvars attribute (a Hash) of the received SIP request with the asserted From URI as value.

Parameters

message

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

Example

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

  proxy.on_success_response do |response|
    # The registrar replies 200, so assert the From URI to the connection.
    OverSIP::Modules::UserAssertion.assert_connection response
  end

  proxy.route request
end

revoke_assertion(message)

Revokes the association between the received SIP request and its connection. It can also be applied when processing a SIP response. This method removes the :asserted_user entry from the cvars attribute of the received SIP request.

Parameters

message

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

Example

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

  proxy.on_failure_response do |response|
    # The registrar does not reply 200, so revoke the assertion (the SIP password
    # could have been changed).
    OverSIP::Modules::UserAssertion.revoke_assertion response
  end

  proxy.route request
end

add_pai(request)

Adds a P-Asserted-Identity to the given SIP request with the asserted From URI as value.

If the From URI of the request does not match the previously asserted URI for the request connection, then this method removes all the existing P-Asserted-Identity headers in the request and returns false.

If the request contains a P-Preferred-Identity header then this method removes all the existing P-Asserted-Identity headers in the request, does not include a P-Asserted-Identity header and returns nil.

In other cases (no P-Preferred-Identity header and the From URI matches the asserted URI for the request connection) this methods adds a P-Asserted-Identity with the asserted URI (by also replacing any other P-Asserted-Identity header(s) in the request).

Parameters

request

An OverSIP::SIP::Request instance.

Example

if request.sip_method == :INVITE
  OverSIP::Modules::UserAssertion.add_pai request
end