ClearIP Documentation

Basic Integration Testing

Test 1: Route Advance, Phone Number Format

ClearIP returns a default response code (SIP 503 or SIP 404) for the switch or SBC to route advance the call if ClearIP has not been configured to block the call, return a routing destination, perform STIR/SHAKEN, or return specified data fields in the SIP response.

To test receiving a SIP 503 or SIP 404 from ClearIP:

  1. Send a test call to ClearIP. If testing outbound calls to ClearIP, generally, a test call can be made to any long distance number.
  2. Open the Analytics dropdown menu and go to the SIP Messages page.
  3. The test call should appear on the page very quickly, usually within a second of the call reaching ClearIP. Refresh the page if needed. Check the following:
    • The Code field displays a 503 or 404 for the test call.
    • The switch or SBC is able to successfully route advance the call to the configured alternate or backup route.
    • The Translated Calling Number and Translated Called Number fields display the phone numbers in E164 format without the leading +. In the screenshot below, a test call was made to +1-404-526-6060 which is correctly displayed as 14045266060.
    • A single call record appears in the SIP Messages page for each test call placed.
  4. Click on the Show button to view the raw SIP INVITE Request received from the SBC and SIP Response returned by ClearIP.

Troubleshooting:

  1. If no records appear in the SIP Messages page after placing a test call, verify whether the correct SBC public IP address was whitelisted and check the call trace from the switch or SBC to see whether the test call was sent to ClearIP.
  2. If multiple SIP Message records appear per call attempt reaching ClearIP, attempt to change the ClearIP response code to SIP 404 or SIP 302 to enable route advance. See the SBCs page for additional information.
  3. If the Translated Calling Number or Translated Called Number does not have E164 format, configure number translation rules to normalize the number format or configure the switch or SBC to send the correct number format. See the Number Translation page for additional information.
  4. If either the Translated Calling Number or Translated Called Number field is blank, ClearIP does not recognize the number format as valid. Check the format of the SIP INVITE headers by clicking the Show button.

The headers must have a general format of a SIP URI with a user@host with optional ports, tags, and parameters all enclosed in angle brackets. ClearIP does not support Tel URI.

  • Called telephone number is defined by the Request URI user.

  • Calling telephone number is defined by one of the following (ordered from highest priority)

    • Diversion header user
    • P-Asserted-Identity header user
    • Remote-Party-ID header user
    • P-Charge-Info header user
    • From header user

In a SIP INVITE for a forwarded call, the called number is defined by the Request URI user. The calling number is defined by the Diversion header. If the Diversion header is not present, then the calling number is defined by the P-Asserted-Identity header.

Examples of invalid headers:

  1. Header is missing user
P-Asserted-Identity: <sip:@transnexus.com>
  1. Header contains Tel URI
P-Asserted-Identity: <tel:14045266060>
  1. Header is missing host
P-Asserted-Identity: <sip:+14045266060>

Test 2: Block on SIP 603 Decline

If ClearIP is configured to block a call due to a blacklist rule, toll fraud prevention, robocall prevention, etc., ClearIP can return a SIP 603 Decline to block the call. The switch or SBC must be configured to block a call when receiving a SIP 603 Decline and not route advance.

To test receiving a SIP 603 Decline from ClearIP:

  1. Open the Whitelist/Blacklist dropdown menu and go to the Called Numbers page.
  2. Click the Add button, and in the Called Number field, enter the called number that will be blacklisted using E164 format without the leading +. Set the Action to Blacklist and submit the changes. The rule takes effect immediately. Any calls to the blacklisted number will be blocked.
  3. Make a test call to the blacklisted number.
  4. Check whether the call is blocked by the switch or SBC.
  5. Go to the SIP Messages page.
  6. Check that the Code is 603 and the Reason is listed as Blacklisted.
  7. Delete the blacklist rule once this test is finished.

Test 3: Route Advance on SIP 403 Forbidden

In case ClearIP returns a SIP 403 Forbidden response, it is reccommended the switch or SBC be configured to route advance the call upon receiving a SIP 403 Forbidden.

Possible reasons for seeing a SIP 403 Forbidden response:

  • SBC IP address is misconfigured
  • SBC IP address changes from initial value
  • Account Rate Limit is exceeded
  • SBC Status is set to Inactive
  • No matching User is found

NOTE: This test should not be performed if the SBC is sending production traffic to ClearIP. Any changes made on the SBCs page may require up to 60 seconds to take effect.

To test receiving a SIP 403 Forbidden from ClearIP:

  1. Open the Organization dropdown menu and go to the SBCs page.
  2. Select the SBC used for testing and click Update.
  3. Set Status to Inactive and submit changes. ClearIP now returns a SIP 403 Forbidden for all calls from this SBC.
  4. Send a test call.
  5. Go to the SIP Messages page.
  6. Check that the Code is 403.
  7. Check whether the switch or SBC was able to route advance the call.
  8. Set the SBC Status back to Active once this test is finished.

Test 4: Routing on SIP 302 Moved Temporarily

ClearIP can return a list of routes in the Contact header of the SIP 302 response which the SBC can follow to redirect the call.

To test receiving routing on a SIP 302 from ClearIP:

  1. Go to the SBCs page.
  2. Select the SBC and click Update. Set Routing to Yes and submit.
  3. Open the Routing dropdown menu and go to the Inbound Routes page. The rules configured in the Inbound Routes page can apply to both inbound and outbound calls.
  4. Click on Add to create a new Inbound Route.
  5. Set the Primary Route Destinations field to the IP address or FQDN of the desired destination or termination carrier. This destination should not be set to the first backup termination carrier. For example, if the switch routing is configured to send outbound calls first to ClearIP, then failover to Carrier 1, and then failover to Carrier 2, use the IP address of Carrier 2 here to test that ClearIP routing is followed instead of the switch routing.
  6. Set the Prefix field to the calling number intended to be used for the test.
  7. For netsapiens users running v41 or higher, “lcr” must be entered in the Primary Route Prefix. This is required to route the call correctly. If a Secondary Route Destination is configured, “lcr” must also be entered in the Secondary Route Prefix field and so on for each Route Destination level.
  8. Send a test call to the phone number configured for the test routing rule.
  9. Verify in a call trace on the switch or SBC that the call was routed to the expected destination.
  10. Verify in the SIP Messages page that ClearIP returned a SIP 302 message.
  11. Click on the Show button for the test call. Scroll down to the SIP Response and verify that the Contact header of the SIP 302 returns the configured IP address or FQDN as the host. Netsapiens users should confirm that “lcr” is prepended to each phone number in the Contact header:
  12. Delete the Inbound Route when finished with the test.

Test 5: STIR/SHAKEN Authentication

ClearIP can be used to test STIR/SHAKEN Authentication on outbound call to generate an Identity header and return it in the SIP 302 response.

Testing STIR/SHAKEN can only be done after approval from the STI-PA. Once approved, ClearIP can be configured to generate STI certificates. See the Certificates section.

To test generating an identity header and retuning it in a SIP 302 in ClearIP:

  1. Go to the SBCs page.

  2. Update the SBC to select the appropriate format for the Identity header if necessary. See the SBCs section for additional information about Identity header format options.

    If ClearIP is integrated directly with a netsapiens to implement STIR/SHAKEN authentication, the SBC must be updated to set the Routing field to Yes.

  3. Open the STI dropdown menu and go to the Authentication Policies page.

  4. Click Add to create an STI Authentication policy. Set Action to Attest C, Method to In-Band, and the Certificate field to the configured certificate Name. Restrict the policy to apply to outbound calls by selecting the appropriate Operator or Service Provider field. Submit the changes.

  5. Send an outbound test call.

  6. Go to the SIP Messages page.

  7. Click on the Columns button to select STI Authentication. This displays all columns related to STI Authentication.

  8. Verify the STI Authentication Status field for the call shows Successful.

  9. Click on the Show button and verify the following:

    • ClearIP returned a SIP 302 Redirect with an Identity header.
    • The STI Authentication Token tab shows the correct orig tn, dest tn, and attest values.
    • The STI Authentication Certificate tab shows the STI Certificate used to authenticate the call.

  10. View the call trace to verify:

    • The SBC inserts the Identity header into the SIP INVITE.
    • The SBC routes the SIP INVITE with Identity header to the correct route destination.

The SBC must be configured to copy the Identity header from the SIP 302 response and insert it into the SIP INVITE sent to the termination carrier. In the call trace, confirm whether the SBC is inserting the Identity header into the outgoing SIP INVITE.

Here is an example SIP INVITE containing the Identity header which is sent to a termination carrier.

INVITE sip:+18554742536@sip.clearip.com:5060 SIP/2.0
Via: SIP/2.0/TCP sip.clearip.com:5060
From: <sip:+14045266060@transnexus.com:5060>
To: <sip:+18554742536@sip.clearip.com:5060>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuY2xlYXJpcC5jb20vOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5LzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwLnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODU1NDc0MjUzNiJdfSwiaWF0IjoxNTc3ODM2ODAwLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiOTk5OTk5OTktOTk5OS00OTk5LTk5OTktOTk5OTk5OTk5OTk5In0.abcdefghijklmnopqrstuvwzyzABCDEFGHIJKLMNOPQRSTUVWZYZ0123456789012345678901234567890123;info=<https://certificates.clearip.com/99999999-9999-4999-9999-999999999999/00000000000000000000000000000000.pem>;alg=ES256;ppt=shaken
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0
Basic Integration Testing