ProSBC:SHAKEN

From TBwiki
(Difference between revisions)
Jump to: navigation, search
(First draft)
 
(→Disable Legacy Redirection Mode)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:FreeSBC Configuration for STIR/SHAKEN with Transnexus OSPrey server}}
+
{{DISPLAYTITLE:ProSBC Configuration for STIR/SHAKEN with Transnexus ClearIP service}}
−
FreeSBC Configuration for SHAKEN
+
−
Revision History
+
−
Revision Date of Issue Changes
+
−
1.0.0 July 18, 2018 Initial draft
+
−
 
+
−
Contents
+
−
Revision History 1
+
−
Contents 1
+
−
1 Introduction 2
+
−
2 Network Diagram and Call Scenarios 2
+
−
3 FreeSBC Configuration 3
+
−
3.1 Configure Routing Script 3
+
−
3.1.1 Txnx_routing.rb 3
+
−
3.1.2 Txnx_shaken.rb 4
+
−
3.2 Configure NAP (Network Access Point) 6
+
−
3.3 Configure NAP Column 7
+
−
3.4 Configure Static Route 7
+
−
3.5 Enable SIP Custom Header 7
+
−
3.6 Disable Legacy Redirection Mode 7
+
−
3.7 Configure Route Retry Action 7
+
−
 
+
 
 
 
 
−
1 Introduction
 
 
=Introduction=
 
=Introduction=
−
This document provides instructions on how to configure FreeSBC to interoperate with the TransNexus OSPrey server.  OSPrey is a SIP redirect server that provides advanced Least Cost Routing (LCR), fraud control and STIR (Secure Telephony Identity Revisited) / SHAKEN (Secure Handling of Asserted information using toKENs) features.  
+
This document provides instructions on how to configure ProSBC to operate with the TransNexus ClearIP server.  ClearIP is a SIP redirect server that provides advanced Least Cost Routing (LCR), fraud control and STIR (Secure Telephony Identity Revisited) / SHAKEN (Secure Handling of Asserted information using toKENs) features. <br/>
−
FreeSBC 3.0.90 or later version is needed to support secure caller ID using STIR/SHAKEN.
+
 
 +
ProSBC 3.0.90 or a later version is needed to support secure caller ID using STIR/SHAKEN.
 +
 
 +
'''Note''': STIR/SHAKEN is only supported on ProSBC.
  
−
==Network Diagram and Call Scenarios==
+
=Network Diagram and Call Scenarios=
 
This section provides the simplified network diagram containing two telephone service providers, and the call scenarios.
 
This section provides the simplified network diagram containing two telephone service providers, and the call scenarios.
 
  [[Image:FreeSBC OSPrey Diagram.png|800px]]
 
  [[Image:FreeSBC OSPrey Diagram.png|800px]]
−
# Source of ServiceProvider-A sends a call to FreeSBC-A.
+
# Source of ServiceProvider-A sends a call to ProSBC-A.
−
# FreeSBC-A forwards the call to OSPrey-A, which is a SIP redirect server providing LCR, fraud control, SHAKEN AS (Authentication Service) and other features.
+
# ProSBC-A forwards the call to ClearIP-A, which is a SIP redirect server providing LCR, fraud control, SHAKEN AS (Authentication Service) and other features.
−
# OSPrey-A performs LCR, fraud control and SHAKEN AS logic, then sends one of the following responses to FreeSBC-A
+
# ClearIP-A performs LCR, fraud control and SHAKEN AS logic, then sends one of the following responses to ProSBC-A
 
##SIP 404 Not Found: No fraud or SHAKEN AS error is detected, and routing information is unavailable.
 
##SIP 404 Not Found: No fraud or SHAKEN AS error is detected, and routing information is unavailable.
 
##SIP 603 Decline: Fraud is detected or SHAKEN AS request fails.
 
##SIP 603 Decline: Fraud is detected or SHAKEN AS request fails.
−
##SIP 3xx Redirect: Destination information (FreeSBC-B of ServiceProvider-B) and a SIP Identity header including a digitally signed token that includes the calling number (secure caller ID).
+
##SIP 3xx Redirect: Destination information (ProSBC-B of ServiceProvider-B) and a SIP Identity header including a digitally signed token that includes the calling number (secure caller ID).
−
#FreeSBC-A processes the response
+
#ProSBC-A processes the response
−
##SIP 404 Not Found: FreeSBC-A tries the next destination configured in its local routing policy.
+
##SIP 404 Not Found: ProSBC-A tries the next destination configured in its local routing policy.
 
##SIP 603 Decline: Proxies the response back to Source to block the call.
 
##SIP 603 Decline: Proxies the response back to Source to block the call.
−
##SIP 3xx Redirect: Forwards the call to FreeSBC-B with the Identity header.
+
##SIP 3xx Redirect: Forwards the call to ProSBC-B with the Identity header.
−
#FreeSBC-B forwards the call to OSPrey-B, which is a SIP redirect server providing fraud control, SHAKEN VS (Verification Service) and other features.
+
#ProSBC-B forwards the call to ClearIP-B, which is a SIP redirect server providing fraud control, SHAKEN VS (Verification Service) and other features.
−
#OSPrey-B performs fraud control and SHAKEN VS logic, and then sends one of the following SIP responses to FreeSBC-B.
+
#ClearIP-B performs fraud control and SHAKEN VS logic, and then sends one of the following SIP responses to ProSBC-B.
 
##SIP 404 Not Found: No fraud or SHAKEN VS error is detected, and routing information is unavailable.
 
##SIP 404 Not Found: No fraud or SHAKEN VS error is detected, and routing information is unavailable.
 
##SIP 603 Decline: Fraud is detected or SHAKEN VS request fails.
 
##SIP 603 Decline: Fraud is detected or SHAKEN VS request fails.
 
##SIP 3xx Redirect: Destination information (Destination of ServiceProvider-B) is attached.
 
##SIP 3xx Redirect: Destination information (Destination of ServiceProvider-B) is attached.
−
#FreeSBC-B processes the response
+
#ProSBC-B processes the response
−
##SIP 404 Not Found: FreeSBC-B tries the next destination configured in its local routing policy.
+
##SIP 404 Not Found: ProSBC-B tries the next destination configured in its local routing policy.
−
##SIP 603 Decline: Proxies the response back to FreeSBC-A to block the call.
+
##SIP 603 Decline: Proxies the response back to ProSBC-A to block the call.
 
##SIP 3xx Redirect: Forwards the call to Destination.
 
##SIP 3xx Redirect: Forwards the call to Destination.
−
Note: A variant scenario is that Destination of ServiceProvider-B is configured as the next destination in the local routing policy of ServiceProvider-B, OSPrey-B returns SIP 404 Not Found, then FreeSBC-B does failover to Destination.
+
Note: A variant scenario is that Destination of ServiceProvider-B is configured as the next destination in the local routing policy of ServiceProvider-B, ClearIP-B returns SIP 404 Not Found, then ProSBC-B does failover to Destination.
−
=FreeSBC Configuration=
+
=ProSBC Configuration=
−
This section provides FreeSBC configuration for the solution.
+
This section provides ProSBC configuration for the solution.
 
==Configure Routing Script==
 
==Configure Routing Script==
−
FreeSBC is configured to use routing script to handle SIP 3xx Redirect response.
+
ProSBC is configured to use routing script to handle SIP 3xx Redirect response.
−
#Enable routing script
+
:1. Enable routing script
 
  Gateway->Use script
 
  Gateway->Use script
−
#Load routing scripts
+
:2. Load routing scripts
 
  Gateway->Routes->Routing Script->Import Script File
 
  Gateway->Routes->Routing Script->Import Script File
 
     File->txnx_shaken.rb
 
     File->txnx_shaken.rb
Line 65: Line 46:
 
     ScriptType->Txnx
 
     ScriptType->Txnx
 
     Load on startup->checked
 
     Load on startup->checked
−
===Txnx_routing.rb===
+
 
−
#
+
[[:File:Txnx_scripts.zip|Click here to download txnx_shaken.rb and txnx_routing.rb Routing Scripts]]
−
# Script version 1.0
+
 
−
#
+
−
# Version history:
+
−
#  1.0  First version of this script
+
−
#
+
−
+
−
require 'base_routing'
+
−
require 'txnx_shaken'
+
−
+
−
# This script routes calls in the mostsimple fashion. The behavior is the same as routing without ruby scripts
+
−
# with the addition of nap availability.
+
−
#
+
−
# Routing is in the following order:
+
−
#
+
−
# * Matching: <tt>BaseRouting.route_match</tt>
+
−
#  * <tt>:call_field_name => :called</tt> - Match the called number of the call to a route.
+
−
#  * <tt>:call_field_name => :calling</tt> - Match the calling number of the call to a route.
+
−
#  * <tt>:call_field_name => :nap</tt> - Match the nap of the call to a route.
+
−
#  * <tt>:call_field_name => :called, :route_field_name => :remapped_called</tt> - Remap the called
+
−
#    number for the outgoing call.
+
−
#  * <tt>:call_field_name => :calling, :route_field_name => :remapped_calling</tt> - Remap the calling
+
−
#    number for the outgoing call.
+
−
#  * <tt>:call_field_name => :nap, :route_field_name => :remapped_nap</tt> - Remap the nap for the outgoing call.
+
−
#    This means setting the destination nap for the route.
+
−
#
+
−
+
−
+
−
class TxnxRouting < BaseRouting
+
−
  include TxnxShaken
+
−
+
−
  before_filter :method => :txnx_shaken
+
−
+
−
  route_match :call_field_name => :called
+
−
  route_match :call_field_name => :calling
+
−
  route_match :call_field_name => :nap
+
−
  route_remap :call_field_name => :called, :route_field_name => :remapped_called
+
−
  route_remap :call_field_name => :calling, :route_field_name => :remapped_calling
+
−
  route_remap :call_field_name => :nap, :route_field_name => :remapped_nap
+
−
  route_order :route_field_name => :priority
+
−
end
+
−
+
−
@@routing = TxnxRouting.new
+
−
+
−
def init_routes(routes)
+
−
  @@routing.init routes
+
−
end
+
−
+
−
def route(call, nap_list)
+
−
  @@routing.route call, nap_list
+
−
end
+
−
===Txnx_shaken.rb===
+
−
#
+
−
# Script version 1.0
+
−
#
+
−
# Version history:
+
−
#  1.0  First version of this script
+
−
#
+
−
# This before-matching filter is used to test some ideas.
+
−
#
+
−
#
+
−
# In order to use this module, follow the steps below:
+
−
# 1- Add the "require 'txnx_shaken'" statement at the top of the main
+
−
#    script.
+
−
# 2- Add the "include TxnxShaken" statement in the main routing class.
+
−
# 3- Add the filter "before_filter :method => :txnx_shaken" in the
+
−
#    main routing class.
+
−
#
+
−
+
−
module TxnxShaken
+
−
  def init_txnx_shaken(params)
+
−
    params
+
−
  end
+
−
+
−
  def txnx_shaken(params)
+
−
    call = params[:call]
+
−
    contacts = params[:contacts]
+
−
+
−
    # Added this to support request_uri 3xx routing
+
−
    call[:request_uri_forward_enabled] = 'true'
+
−
+
−
    # Verify if this routing query is for an incoming call
+
−
    # To find this, we look at the contact index (it should be zero)
+
−
    if (contacts[:index].to_i == 0)
+
−
      log_trace :always, "TxnxShaken: INVITE"
+
−
+
−
      # Add P-Source-Device header
+
−
      custom_header = "P-Source-Device:" + call[:sip_remote_addr]
+
−
     
+
−
      # Extract Identity header
+
−
      sip_header = call[:sip_header]
+
−
      if !sip_header.nil?
+
−
        headers = sip_header.split(/\n+/)
+
−
        headers.each do |header|
+
−
          if header.match(/^Identity:/)
+
−
            # Save Identity header to pass to redirect logic
+
−
            params[:user_context] = { "identity_header" => header }
+
−
            # Add Identity header to pass to OSPrey
+
−
            custom_header += "\n" + header
+
−
            break
+
−
          end
+
−
        end
+
−
      end
+
−
+
−
      # Pass custom headers to OSPrey
+
−
      call[:sip_header] = custom_header
+
−
+
−
      # Replace current routes with a list of redirect routes with priority
+
−
      newroutes = []
+
−
      nap_lists = params[:naps]
+
−
      nap_lists.each do |nap_list, nap_info|
+
−
        if nap_info[:server_type] == "REDIRECT"
+
−
          newroutes << { :name => nap_info[:name], :remapped_nap => nap_info[:name] , :priority => nap_info[:priority] }
+
−
        end
+
−
      end
+
−
      params[:routes] = newroutes
+
−
    else
+
−
      log_trace :always, "TxnxShaken: REDIRECT"
+
−
+
−
      # Get Identity header
+
−
      identity_header = nil
+
−
      context = params[:user_context]
+
−
      if !(context.nil? || context.empty?)
+
−
        identity_header = context[:identity_header]
+
−
      end
+
−
      if identity_header.nil? || identity_header.empty?
+
−
        # Extract X-Identity header
+
−
        sip_header = call[:sip_header]
+
−
        if !sip_header.nil?
+
−
          headers = sip_header.split(/\n+/)
+
−
          headers.each do |header|
+
−
            if header.match(/^X-Identity:/)
+
−
              identity_header = header
+
−
              break
+
−
            end
+
−
          end
+
−
        end
+
−
      end
+
−
+
−
      # Add Identity header to pass to destination
+
−
      if !(identity_header.nil? || identity_header.empty?)
+
−
        call[:sip_header] = identity_header
+
−
      else
+
−
        call[:sip_header] = nil
+
−
      end
+
−
    end
+
−
+
−
    params[:call] = call
+
−
+
−
    params
+
−
  end
+
−
end
+
 
==Configure NAP (Network Access Point)==
 
==Configure NAP (Network Access Point)==
−
OSPrey-A and OSPrey-B are configured as NAP on FreeSBC-A and FreeSBC-B respectively. A general SIP endpoint, NAP-ANY, is configured on both FreeSBC’s.
+
ClearIP-A and ClearIP-B are configured as NAP on ProSBC-A and ProSBC-B respectively. A general SIP endpoint, NAP-ANY, is configured on both ProSBC’s.
−
* On FreeSBC-A
+
* On ProSBC-A
 
  NAPs->Create New NAP
 
  NAPs->Create New NAP
−
     Name->NAP_OSPrey_A
+
     Name->NAP_ClearIP_A
−
     Proxy address->x.x.x.x (IP of OSPrey-A)
+
     Proxy address->x.x.x.x (IP of ClearIP-A)
 
  NAPs->Create New NAP
 
  NAPs->Create New NAP
 
     Name->NAP_ANY
 
     Name->NAP_ANY
 
  Use Proxy Address->Unchecked
 
  Use Proxy Address->Unchecked
−
* On FreeSBC-B
+
* On ProSBC-B
 
  NAPs->Create New NAP
 
  NAPs->Create New NAP
−
     Name->NAP_OSPrey_B
+
     Name->NAP_ClearIP_B
−
     Proxy address->x.x.x.x (IP of OSPrey-B)
+
     Proxy address->x.x.x.x (IP of ClearIP-B)
 
  NAPs->Create New NAP
 
  NAPs->Create New NAP
 
     Name->NAP_ANY
 
     Name->NAP_ANY
 
     Use Proxy Address->Unchecked
 
     Use Proxy Address->Unchecked
−
Note: To configure local routing policy with other destination NAPs, OSPrey NAPs should have the highest priority alone all destination NAPs.
+
Note: To configure local routing policy with other destination NAPs, ClearIP NAPs should have the highest priority alone all destination NAPs.
 
==Configure NAP Column==
 
==Configure NAP Column==
−
NAP column is used to mark OSPrey as redirect server.
+
NAP column is used to mark ClearIP as redirect server.
 
  Gateway->Routes->NAP Column->Create New NAP Column
 
  Gateway->Routes->NAP Column->Create New NAP Column
 
     Name: server_type  
 
     Name: server_type  
 
     Type Attributes: NORMAL|REDIRECT
 
     Type Attributes: NORMAL|REDIRECT
 
     Default: NORMAL
 
     Default: NORMAL
−
*Both NAP_OSPrey-A and NAP_OSPrey-B are configured with NAP column server_type REDIRECT.
+
*Both NAP_ClearIP-A and NAP_ClearIP-B are configured with NAP column server_type REDIRECT.
 
*NAP_ANY are configured with NAP column server_type NORMAL.
 
*NAP_ANY are configured with NAP column server_type NORMAL.
 
==Configure Static Route==
 
==Configure Static Route==
−
A static route to NAP_ANY should be configured on both FreeSBC’s to allow FreeSBC to try the destination in the SIP 3xx response.
+
A static route to NAP_ANY should be configured on both ProSBC’s to allow ProSBC to try the destination in the SIP 3xx response.
 
  Gateway->Routes->Create New Static Route
 
  Gateway->Routes->Create New Static Route
 
     Name->ToEndpoints
 
     Name->ToEndpoints
Line 253: Line 84:
 
  Profiles->SIP->Enable SIP Custom Headers
 
  Profiles->SIP->Enable SIP Custom Headers
 
==Disable Legacy Redirection Mode==
 
==Disable Legacy Redirection Mode==
−
Use legacy redirection mode must be unchecked to allow FreeSBC to use routing script to handle SIP 3xx response.
+
Use legacy redirection mode must be unchecked to allow ProSBC to use routing script to handle SIP 3xx response.
−
  SIP->Editing SIP Configuration->Header Parameters->Use legacy redirection mode
+
  SIP->Editing SIP Configuration->Header Parameters->Use legacy redirection mode [uncheck]
 +
 
 
==Configure Route Retry Action==
 
==Configure Route Retry Action==
−
Route retry action of 3xx, 404 and 603 must be configured to allow FreeSBC to perform failover, fraud control and SHAKEN AS/VS request.
+
Route retry action of 3xx, 404 and 603 must be configured to allow ProSBC to perform failover, fraud control and SHAKEN AS/VS request.
 
  Profiles->Edit Reason Cause Mapping
 
  Profiles->Edit Reason Cause Mapping
 
     300 Multiple Choices->Route retry action->Process call routing
 
     300 Multiple Choices->Route retry action->Process call routing

Latest revision as of 08:03, 24 March 2021

 

Contents

Introduction

This document provides instructions on how to configure ProSBC to operate with the TransNexus ClearIP server. ClearIP is a SIP redirect server that provides advanced Least Cost Routing (LCR), fraud control and STIR (Secure Telephony Identity Revisited) / SHAKEN (Secure Handling of Asserted information using toKENs) features.

ProSBC 3.0.90 or a later version is needed to support secure caller ID using STIR/SHAKEN.

Note: STIR/SHAKEN is only supported on ProSBC.

Network Diagram and Call Scenarios

This section provides the simplified network diagram containing two telephone service providers, and the call scenarios. 

FreeSBC OSPrey Diagram.png
  1. Source of ServiceProvider-A sends a call to ProSBC-A.
  2. ProSBC-A forwards the call to ClearIP-A, which is a SIP redirect server providing LCR, fraud control, SHAKEN AS (Authentication Service) and other features.
  3. ClearIP-A performs LCR, fraud control and SHAKEN AS logic, then sends one of the following responses to ProSBC-A
    1. SIP 404 Not Found: No fraud or SHAKEN AS error is detected, and routing information is unavailable.
    2. SIP 603 Decline: Fraud is detected or SHAKEN AS request fails.
    3. SIP 3xx Redirect: Destination information (ProSBC-B of ServiceProvider-B) and a SIP Identity header including a digitally signed token that includes the calling number (secure caller ID).
  4. ProSBC-A processes the response
    1. SIP 404 Not Found: ProSBC-A tries the next destination configured in its local routing policy.
    2. SIP 603 Decline: Proxies the response back to Source to block the call.
    3. SIP 3xx Redirect: Forwards the call to ProSBC-B with the Identity header.
  5. ProSBC-B forwards the call to ClearIP-B, which is a SIP redirect server providing fraud control, SHAKEN VS (Verification Service) and other features.
  6. ClearIP-B performs fraud control and SHAKEN VS logic, and then sends one of the following SIP responses to ProSBC-B.
    1. SIP 404 Not Found: No fraud or SHAKEN VS error is detected, and routing information is unavailable.
    2. SIP 603 Decline: Fraud is detected or SHAKEN VS request fails.
    3. SIP 3xx Redirect: Destination information (Destination of ServiceProvider-B) is attached.
  7. ProSBC-B processes the response
    1. SIP 404 Not Found: ProSBC-B tries the next destination configured in its local routing policy.
    2. SIP 603 Decline: Proxies the response back to ProSBC-A to block the call.
    3. SIP 3xx Redirect: Forwards the call to Destination.

Note: A variant scenario is that Destination of ServiceProvider-B is configured as the next destination in the local routing policy of ServiceProvider-B, ClearIP-B returns SIP 404 Not Found, then ProSBC-B does failover to Destination.

ProSBC Configuration

This section provides ProSBC configuration for the solution.

Configure Routing Script

ProSBC is configured to use routing script to handle SIP 3xx Redirect response.

1. Enable routing script 
Gateway->Use script
2. Load routing scripts 
Gateway->Routes->Routing Script->Import Script File
   File->txnx_shaken.rb
   ScriptType->TxNx
   Load on startup->unchecked
Gateway->Routes->Routing Script->Import Script File
   File->txnx_routing.rb
   ScriptType->Txnx
   Load on startup->checked

Click here to download txnx_shaken.rb and txnx_routing.rb Routing Scripts

Configure NAP (Network Access Point)

ClearIP-A and ClearIP-B are configured as NAP on ProSBC-A and ProSBC-B respectively. A general SIP endpoint, NAP-ANY, is configured on both ProSBC’s.

  • On ProSBC-A 
NAPs->Create New NAP
    Name->NAP_ClearIP_A
    Proxy address->x.x.x.x (IP of ClearIP-A)
NAPs->Create New NAP
    Name->NAP_ANY
Use Proxy Address->Unchecked
  • On ProSBC-B 
NAPs->Create New NAP
    Name->NAP_ClearIP_B
    Proxy address->x.x.x.x (IP of ClearIP-B)
NAPs->Create New NAP
    Name->NAP_ANY
    Use Proxy Address->Unchecked

Note: To configure local routing policy with other destination NAPs, ClearIP NAPs should have the highest priority alone all destination NAPs.

Configure NAP Column

NAP column is used to mark ClearIP as redirect server. 

Gateway->Routes->NAP Column->Create New NAP Column
    Name: server_type 
    Type Attributes: NORMAL|REDIRECT
    Default: NORMAL
  • Both NAP_ClearIP-A and NAP_ClearIP-B are configured with NAP column server_type REDIRECT.
  • NAP_ANY are configured with NAP column server_type NORMAL.

Configure Static Route

A static route to NAP_ANY should be configured on both ProSBC’s to allow ProSBC to try the destination in the SIP 3xx response. 

Gateway->Routes->Create New Static Route
    Name->ToEndpoints
    NAP->any
    Remapped_NAP->NAP_ANY

Enable SIP Custom Header

Enable SIP Custom Headers must be checked to pass SHAKEN Identity header and several other headers used by the solution. 

Profiles->SIP->Enable SIP Custom Headers

Disable Legacy Redirection Mode

Use legacy redirection mode must be unchecked to allow ProSBC to use routing script to handle SIP 3xx response. 

SIP->Editing SIP Configuration->Header Parameters->Use legacy redirection mode [uncheck]

Configure Route Retry Action

Route retry action of 3xx, 404 and 603 must be configured to allow ProSBC to perform failover, fraud control and SHAKEN AS/VS request. 

Profiles->Edit Reason Cause Mapping
    300 Multiple Choices->Route retry action->Process call routing
    302 Moved temporarily->Route retry action->Process call routing
    404 Not found->Route retry action->Continue call
    603 Decline->Route retry action->Stop call

Notes:

  • The default route retry action of 404 is Stop call.
  • The default route retry action of 603 is Continue call.
Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=ProSBC:SHAKEN&oldid=30115"
Personal tools