ClearIP In-Line Proxy

The ClearIP In-Line Proxy enables easy integration between a SIP telecommunications network and ClearIP.

This software is not required in all ClearIP deployments. Some ClearIP customers prefer to use it because it can make deployment easier with their telecom network equipment and software.

The ClearIP In-Line Proxy performs the following functions:

• Receives SIP messages from network elements within a telecommunications network
• Maintains a secure encrypted connection with ClearIP
• Sends information over this secure connection to ClearIP
• Receives information back from ClearIP based upon services performed
• Sends the formatted information to network elements.

In summary, the ClearIP In-Line Proxy acts as secure message relay. It works with any SIP-based telecom system.

Network configuration

The ClearIP In-Line Proxy can be configured in several different ways according to the preferences and requirements of the service provider. The following figure shows an illustrative configuration:

ClearIP In-Line Proxy within a telecommunications network

In this arrangement, the ClearIP In-Line Proxy receives SIP INVITEs, sends them to ClearIP, receives the replies and sends the message to the appropriate network elements (e.g., switch, SBC).

Outbound

The following figure shows the call flow when ClearIP returns a SIP 302 Redirect response for routing and/or STIR/SHAKEN authentication of an outbound call:

SIP Ladder for routing and/or STIR/SHAKEN authentication with the ClearIP In-Line Proxy

1. A Subscriber sends a call to the Switch over SIP or TDM.
2. The Switch sends a SIP INVITE to the In-Line Proxy.
3. The In-Line Proxy sends the SIP INVITE to ClearIP for services (e.g., STIR/SHAKEN authentication, routing, toll fraud prevention, robocall mitigation, etc.).
4. ClearIP responds to the In-Line Proxy with a SIP 302 Redirect message with STIR/SHAKEN Identity header and Contact header, including the IP address(es) of the Provider(s).
5. The In-Line Proxy inserts the Identity header into the SIP INVITE and sends a redirected SIP INVITE with Identity header to the first Provider. If the first Provider is unable to complete the call, then the In-Line Proxy would route the call to the second Provider listed in the SIP 302 Contact header.

Inbound

The following figure shows the call flow when ClearIP returns a SIP 302 Redirect response for termination and STIR/SHAKEN verification of an inbound call:

SIP Ladder for termination and STIR/SHAKEN verification with the ClearIP In-Line Proxy

1. A Provider sends a call to the In-Line Proxy.
2. The In-Line Proxy sends the SIP INVITE to ClearIP for services (e.g., STIR/SHAKEN verification, routing, robocall prevention, TDoS prevention, etc.).
3. ClearIP responds to the In-Line Proxy with a SIP 302 Redirect message with P-Asserted Identity header (PAI) and Contact header, including the IP address(es) of the Switch(es).
4. The In-Line Proxy inserts the P-Asserted Identity header into the SIP INVITE and sends a redirected SIP INVITE with Identity header to the Switch(es).

Installation and setup

You can set up the ClearIP In-Line Proxy either on AWS (Amazon Web Services) or manually. Here are instructions for both choices. Expand the section to view the instructions for either choice.

After you complete either the AWS or manual portion of the setup, you will finish setup with the shared set of remaining steps.

Installation and setup on AWS

The ClearIP In-line Proxy can be setup on AWS using a CloudFormation template. The CloudFormation template creates two proxies for redundancy. The CloudFormation template also creates a CloudWatch Dashboard and multiple CloudWatch Alarms for monitoring the proxy’s status. The proxies are deployed in a dedicated VPC. Session Manager and/or SSH can be used to connect to the proxies if required for troubleshooting.

1. Save the CloudFormation template on your computer.
2. If you do not already have an AWS account, create one (instructions).
3. Sign into the AWS Management Console (instructions).
4. If you do not already have a key pair for SSH, create one (instructions).
   1. Navigate to the EC2 Key Pairs page.
   2. Click Create key pair.
   3. Fill out the form and click Create key pair.
      1. Enter a name for the key pair.
      2. If using Linux/Mac, select .pem for private key file format.
      3. If using Windows, select .ppk for private key file format.
5. Create the CloudFormation stack (instructions).
   1. Navigate to the CloudFormation page.
   2. Click Create stack.
   3. Select Upload a template file, upload the template file, and click Next.
   4. Fill out the Specify stack details form and click Next.
      1. We recommend setting the Stack name to ClearIP-Proxy.
      2. The AlarmEmail stack parameter is recommended.
      3. The KeyPair and SubnetsSIP stack parameters are required.
      4. If SSH access is needed, the SubnetSSH stack parameter is required.
      5. All other parameters should be left at their default values.
   5. Leave the Configure stack options form values at their defaults and click Next.
   6. Check the Capabilities acknowledge box and click Create stack.
   7. Wait until the stack status shows CREATE_COMPLETE (typically about 5 minutes).
6. If a value was supplied for the AlarmEmail stack parameter, confirm the subscription by clicking the Confirm subscription link in the email you received.
7. Locate each proxy’s public IP.
   1. Navigate to CloudWatch Dashboards page.
   2. Click on the dashboard name (e.g., ClearIP-Proxy-Dashboard).
   3. The public IPs are shown in the Public IPs section of the dashboard.

Continue with the final steps common to both AWS and manual setup.

Manual installation and setup

1. Create Virtual Machines

Create Virtual Machines (VMs) inside your private network with 4 GB of RAM and 2 cores running either CentOS 7.x, Redhat 7.x, Redhat 8.x, or Oracle Linux 8.x UEK.

• The VMs must have direct access to the internet (no NAT).
• No ports should be opened for external access.
• All connections to ClearIP are initiated by the proxies.
• The proxies accept SIP messages on all interfaces via UDP (5060), TCP (5060), and TLS v1.2 (5061).

2. Set up a firewall on the server

Only trusted devices should be able to send SIP messages to the proxies.

If firewald is not already installed, run these commands:

yum install -y firewalld
reboot

Run these commands to block inbound traffic to ports 5060 and 5061:

firewall-cmd --zone=public --remove-port=5060/udp --permanent
firewall-cmd --zone=public --remove-port=5060/tcp --permanent
firewall-cmd --zone=public --remove-port=5061/tcp --permanent

firewall-cmd --reload

Run these commands to allow specific source IPs to send inbound traffic to the proxy:

firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="x.x.x.x" port protocol="udp" port="5060" accept'
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="x.x.x.x" port protocol="tcp" port="5060" accept'
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="x.x.x.x" port protocol="tcp" port="5061" accept'

firewall-cmd --reload

These rules only apply to inbound (source) traffic. Outbound traffic is unrestricted by these rules.

3. Install the In-Line Proxy on each VM

To install the proxy on either CentOS 7.x or Redhat 7.x, run this command:

curl https://files.transnexus.com/clearip/installProxy7.sh | sh -s

To install the proxy on Redhat 8.x or Oracle Linux 8.x UEK, run this command:

curl https://files.transnexus.com/clearip/installProxy8.sh | sh -s

The proxy starts when installed and whenever its VM is rebooted. There is no starting/stopping or further configuration required.

4. Environments with 1:1 NAT

For some cloud environments such as AWS EC2, the VM instance hosting the ClearIP In-Line Proxy may have one private IP address binding with an internet gateway with one public IP address. In this case, the ClearIP In-Line Proxy must be configured to advertise the internet gateway public IP address in all outbound SIP messages. This allows the downstream devices that cannot access the private IP address to communicate with the ClearIP In-Line Proxy.

To do this, use any text editor as the root user to edit the config file located here:

/etc/opensips/opensips.cfg

Change the following lines from this:

socket = udp:*:5060
socket = tcp:*:5060
socket = tls:*:5061

to this:

socket = udp:<PRIVATE_IP>:5060 as <PUBLIC_IP>
socket = tcp:<PRIVATE_IP>:5060 as <PUBLIC_IP>
socket = tls:<PRIVATE_IP>:5061 as <PUBLIC_IP>

where <PRIVATE_IP> is the ClearIP In-Line Proxy private IP address and <PUBLIC_IP> is the internet gateway public IP address.

Then run this command to restart the ClearIP In-Line Proxy so the change takes effect:

sudo systemctl restart opensips

Continue with the final steps common to both AWS and manual setup.

Final steps

1. Configure the Switch to route calls to the In-Line Proxy

You should configure your switch to route calls directly to the In-Line Proxy for test calls that should be monitored by ClearIP. If the In-Line Proxy is not available, then the Switch should be configured to route advance the call directly to the Destination as a backup.

We recommend that you do not send outbound calls made to Public Safety Answering Points (PSAPs), for example, 911/933 calls, to ClearIP. If ClearIP configurations are not made carefully to account for emergency calls to PSAPs, then these critical calls could be inadvertently blocked. In your routing translations, you should split off emergency calls first so that emergency calls are not sent to ClearIP, but every other outbound call goes through ClearIP.

2. Notify carriers of In-Line Proxy IP address

To ensure call completion, you should contact your carriers to whitelist the proxy IP address to ensure they can accept receiving calls from or sending calls to the ClearIP In-line Proxy.

3. Add the In-Line Proxy as a ClearIP SBC

Add the proxy as an entry in the ClearIP SBCs page to whitelist the IP address in ClearIP.

4. Send a test call to the In-Line Proxy

When you send call traffic to ClearIP, the software will use the SIP INVITE and perform the services configured.

If the proxy IP address has not been whitelisted in the ClearIP SBCs page, then ClearIP returns a SIP 403 Forbidden response to the proxy. Once the proxy IP address has been whitelisted, then ClearIP can be configured to return the following response codes:

• If the ClearIP services don’t result in a block or diversion and neither routing nor STIR/SHAKEN services were requested, then ClearIP will return a SIP 503 Service Unavailable message. Your telecom network will then route-advance to the next destination in your routing table and send the call.
• If routing is enabled or a service initiates a diversion, ClearIP will return a SIP 302 Moved Temporarily to redirect the call to specific routes or divert it (e.g., to the CAPTCHA gateway, which prompts for human response).
• If a ClearIP service initated a block, ClearIP will return a SIP 603 Decline message. The proxy forwards this SIP 603 response to your switch, which will then block the call to prevent a route advance.

5. Send production calls to the In-Line Proxy

Once your ClearIP account has been configured with the desired services and integration testing is successful, you can configure your switch to send production calls to the proxy.

Adjust timeout

The default timeout is 5 seconds. If you used the AWS configuration, you can adjust the timeout parameter in the CloudFormation page, Specify stack details.

If you used the manual configuration, you can adjust timout by editing the configuration file located here:

/etc/opensips/opensips.cfg

Change the following line to the desired timeout:

modparam("tm", "fr_inv_timeout", 5)

Then run this command to restart the ClearIP In-Line Proxy so the change takes effect:

sudo systemctl restart opensips

Troubleshooting

Configure the Proxy to use TCP instead of TLS

If there are any connectivity issues to ClearIP using the default TLS transport, you can try to switch the transport to TCP and test the connection.

The AWS setup process does this by default. If you used the manual setup steps, then the In-Line Proxy can be configured to use either TLS or TCP when communicating with ClearIP. TLS encrypts the messages between the proxy and ClearIP. Switching transport to TCP also allows you to pull unencrypted call traces from the proxy for easier troubleshooting.

To do this, use any text editor as the root user to edit the config file located here:

/etc/opensips/opensips.cfg

The following line should be changed from this:

$du = "sip:sip.clearip.com:5061;transport=tls";

to this:

$du = "sip:sip.clearip.com:5060;transport=tcp";

Then run this command to restart the ClearIP In-Line Proxy so the change takes effect:

sudo systemctl restart opensips

Check TCP/TLS connection using nc (ncat)

It is important to ensure that the the in-line proxy can connect to ClearIP and provider devices. The Linux command nc can be used to test the TCP/TLS connection between the in-line proxy and ClearIP/provider devices.

To test the TLS connection to ClearIP:

nc -zv sip.clearip.com 5061

To test the TCP connection to provider devices:

nc -zv provider_device_fqdn/ip 5060

This command also can be used for troubleshooting connection issues.

Capture a call trace using tcpdump

You can capture a call trace in your network traffic by running the tcpdump command with different parameters.

The AWS setup process installs tcpdump by default. If you used the manual set steps, then you need to install tcpdump using this command:

sudo yum -y install tcpdump

Then you can run tcpdump to view SIP messages on the default SIP port 5060 with messages displayed on the console:

sudo tcpdump -A -s 0 -n -nn -i any port 5060

You can also choose to view all network traffic and save the messages to a pcap file:

sudo tcpdump -w trace.pcap -i any

Contact us today for more information on ClearIP and the ClearIP In-Line Proxy.