Using this Guide

This reference guide is designed to help you learn, configure, and operate your Sansay NSS. If the Sansay NSS product is new to you, you should read all the chapters in this book sequentially to familiarize yourself with all of the product features and functions. Users with some experience and familiarity with NSS may go directly to the chapter(s) of interest.

This guide is organized in six chapters:

1. NSS Overview: Provides a technical overview and operational details of the product.

2. Management: Provides detailed information how to manage the system including GUI, API, and other management functions.

3. Configuration: Provides detailed information about how to configure NSS.

4. Special Interest Topics: Provides information about specific topics that may be of interest.

5. Monitoring. Provides information on day-to-day operations.

6. Troubleshooting. Provides detailed information on how to resolve possible problems.

NSS Overview

Number-lookup for STIR/SHAKEN (NSS) is a lookup server that provides all the essential elements to comply with the STIR/SHAKEN framework including: 

• Authentication Service (STI-AS) serves as a database of numbers to authenticate and generate an Identity header.

• Verification Service (STI-VS) validates the SHAKEN SIP Identity header.

• Secure Key Store (STI-SKS) stores certificate private keys.

NSS works in concert with Sansay STI-CA for STIR/SHAKEN certificate management. A separate guide is provided for Sansay STI-CA.

• Certificate Repository (STI-CR) provides the SBC with access to public key certificates for verifying identity headers.

• Certificate Authority (STI-CA) is able to issue SHAKEN certificates. Sansay is an authorized STI-CA by iconectiv.

Based on the principles of SHAKEN, when NSS receives an STI-AS query, it generates an Identity header that is returned to the SBC when applicable. This identity header is carried end-to-end to the PSTN and presented to terminating carriers that can validate the integrity of the call. Calls are signed using ES256 which is the adopted standard. 

NSS STI-VS function consists in processing an original INVITE's SHAKEN’s Identity and based on the validation result respond to the SBC with a success or error condition.

Supported Platforms

NSS is supported in the following platforms:

• 1M7 Appliance / Baremetal provided by Sansay.
• VMWare
• KVM
• AWS
• Google Cloud Compute

VM Sizing

When deploying NSS as a VM, it is important to note that NSS STI-AS and STI-VS query processing capabilities are mainly driven by your traffic volume measured in queries per second (QPS) and by the number of total entries in your attestation policy table directly related to your network's DIDs/TNs and trunk groups as applicable.

Here are the minimum general requirements:

• 4vCPU and 12G of RAM, 500GB storage. QPS 250 and up to 20,000 entries.
• 4vCPU and 24G of RAM, 500GB storage. QPS 250 and up to 2M entries.
• 6vCPU and 24G of RAM, 1TB storage. QPS 500 and up to 2M entries
• 8vCPU and 24G or RAM, 2TB storage. QPS 1000 and up to 2M entries.
• 12vCPU and 32G of RAM, 3TB storage. QPS 2000 and 2M+ entries.
• 16vCPU and 48G or RAM, 5TB storage. QPS 5000 and 2M+ entries.

System Management

NSS is managed via a web UI and through APIs. As of this writing the web UI supports frequent and infrequent changes while the API supports often tied to frequent changes (provisioning and repetitive tasks). Both web and API access is done through user / password authentication.

For detailed instruction on NSS management REST API please follow this link. 

The rest of this guide focuses on NSS management via its web UI.

The System tab defines system-wide settings including user access, networking information, security and management commands. In terms of management this is where most of the system's management tasks are done. Before presenting the different pages we will provide a system management overview.

General

The general page provides read/write access to the following configuration elements:

• System Alias: This will be shown on the top right corner and it is per-system. You can use this as a friendly indicator of the system you are on (e.g. NSS-LA-92, NSS-1).
• DNS Servers: DNS resolution servers are used by STI-VS.
• NTP Servers: NTP is used for time syncing.
• System Time Zone: GMT-based time zone used for system logs and QDR/transaction records.
• QDR File Interval: File rotation interval for QDR (query detail records) files.

Read-only access is provided for:

• System State
• System Mode
• Serial Number
• System Code Version
• System Time

ANI Input Order

The ANI Input Order table is used by NSS to determine what header will be used to gather the ANI. In SIP protocol the ANI could be carried by more than one header, this table gives you control of choosing the order you would like to read the ANI.

The table behaves in such a way that if a top order header exists, the system will pick that ANI and will not continue with the lower-ordered headers. For example if P-Charge-Info is the most trusted ANI header when present, and SIP INVITE contains P-Charge-Info NSS will use that ANI. If P-Charge-Info were to not exist NSS would keep going down through the list to pick an ANI. The SIP From header is mandatory in SIP whereas all other headers are optional.

The ANI is used by NSS STI-AS for attestation purposes.

Network

In this page you can view and edit the following attributes for each network associated with NSS

• LAN interface IP
• Default Gateway
• Subnet Mask

Note: On DHCP-based systems this page will be read-only. DHCP can be changed to static IP from your system's hypervisor console.

Virtual IPs

The Virtual IP page enables you do add network address that will be used by STI-AS and STI-VS.

When adding a Virtual IP you select an un-used index [1-99], its interface [eth0 or eth1] and finally its IPv4 address. The Virtual IP will use the interface's defined netmask (from the network page).

Trusted Hosts

Using the Trusted Hosts page, you can specify IP addresses or networks that are permitted to access the VSXi system through the following channels/protocols:

• GUI and API (REST / SOAP)
• SCP/SSH/SFTP/SNMP

There are two levels of trusted hosts: GUI which enables GUI/API access and ALL which enables GUI/API in addition to other management protoocls SCP/SSH/SFTP/SNMP.

By default you will see a 0.0.0.0 entry which means allow-all. After you have a clear understanding of the networks that need to access NSS and defined more specific rules you can proceed to delete the 0.0.0.0 entry.

Note: Sansay's authorized IPs are allowed by default and do not need to be added as trusted.

Static Routes

IP static routes can be added if you would like a different gateway to be the next hop instead of the interface's default gateway.

SNMP Trap Receivers

SNMP Trap Receivers are SNMP collectors where NSS will send SNMP traps when there's a defined event in NSS-MIB.

Users

This page define users' name and password associated with a User Group.

User Groups

User Groups provide granular permission definition.

All Pages Read/Write is equivalent to super user access.

All Pages Read Only is equivalent to a restricted operations role.

You can define your own user group to restrict page access and privileges (read-write vs read-only).

Configuring STIR/SHAKEN in NSS

NSS performs number authentication and verification. The following elements take part in NSS configuration: 

• Virtual IPs

• Service Ports

• Switches/SBCs

• Keystore

• Attestation Policies

This is quick rundown of the entire configuration.

You start by defining your Virtual IP (System > Virtual IPs) and Service Ports (Switches > Service Ports). Note: This is not needed when using Sansay S/SaaS. You will then define your switches/SBCs querying NSS. Under STI-AS you upload the STIR/SHAKEN keystore for your STIR/SHAKEN certificates and define policies for attestation rules.

Service Ports

Service Ports defines the software/logical interface NSS uses to receive STI-AS and STI-VS queries. NSS supports SIP and REST protocol for STI-AS and STI-VS query processing.

Switches

Switches are devices that query NSS. Examples of switches are Sansay's VSXi Session Border Controller or a third-party SBCs/switch. A switch can be a single device IP or many devices. If the SBCs are expected to receive the same STI-AS attestation policy it is recommended to define it as one switch with multiple IPs for management simplicity.

Likewise there will be times where it is convenient to split a source entity (SBC/switch) into more than one logical switch inside NSS.  You can use Service Ports to provide a logical split or grouping of SBCs. For example, one SBC with the same source IP could send NSS different types of traffic, this can be achieved by hosting the source IP on a different "switch" albeit it is the same far-end device.

When defining a switch, observe the following guidelines: 

STI-AS

Configuration

In this section, you will:

• Import your STIR/SHAKEN certificate's private keys. Associate the private keys with the STI-CR URL where your certificate is hosted. By default Sansay STI-CA will host your certificates for you as part of our bundled STI-CA and STI-CR service.

• Attach your certificate key's to originating SBCs/switches.

Automated certificate renewal

If you are interested in automated certificate issuance and renewal please follow this link.

Policies (formerly Authorized ANIs)

The Policies table contains rules pertaining attestation. Attestation is done considering all or any of the following parameters:

• SBC: Originating SBC
• OTG: Originating Trunk Group
• ANI: Originating Telephone Number

Video Demonstration

STI-VS

The STI-VS section at this moment does not need to be modified to sucessfully verify calls. NSS will periodically fetch new Root CA bundles from the STI-PA in addition to downloading the latest revoked certificate list.

The Service Providers tap is restricted to tests where a Service Providers is not using a CA-signed certificate.

Troubleshooting

Query Detail Records (QDR)

NSS QDRs contain essential information for troubleshooting and analytics. Each transaction record contains the following elements: 

• Date of the transaction

• Source device

• ANI

• DNIS

• Identity header

• Plaintext PASSPorT header and body

Example QDR

000000007;V1.2;R;1-6;2019-05-06 01:34:18;10;0;;STI_AS;10.10.2.18;1;1;;5643008766;;1323456780;;6-8458@10.10.2.18;Moved Temporarily;0302;;1557106458;;[eyJhbGciOiJSUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI 6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9TYW5zYXlUVy5jb20vU2Fuc2F5VFcuY3J0In0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMzIzNDU2NzgwIl19LCJpYXQiOjE1NTcxMDY0NTgsIm9yaWciOnsidG4iOiI1NjQzMDA4NzY2In0sIm9yaWd pZCI6IjgxMDY2YmY0LTUxYjUtZTMxMS1hMWI4LTAwMWU2N2E1MmVjYyJ9.dtQoaLZeHf9K2YhE5Vm7tmYlM7o5-fUNmn8nJZFIL-2CTt31eyFz0hKa2ejV-V9xUtpcM1ThHpwJlL9WzQ78BquQ_LDDA8SFphUyJCZduZ6dCkgozqwVLFNgzG6QCuqnVRzR_xYXZV LkgmvJ6-fnkUgMu8Fd8R-sZQU0KuAqQyvpyXcDB3PMKTkXn1hYoTKksaJDyWRBMmd0MXi4bm-Wd2j96XIjJX4osRfRF5KqH6yPd96u8jItReZSPuNVDomYMq4ijxxE2MJVy5dvg3a4jLi9vvSH9i3lW1h9mSg_fJedcRtIdBq6J0_Gd2SlvNWdCdX7yT-nmqPZRP 

Automated Certificate Renewal via ACME protocol

Sansay NSS natively supports Automated Certificate Management Environemt in the NSS product in compliance with ATIS-1000080v3 standards. Customers have the choice of manually generated certificates or automatically generated certificates. Automated certificates are recommended when the customer prefers shorter lifetime certificate renewals. While there's no specific requirement of when to use ACME we normally recommend enabling ACME for certificate renewals under 60 days to bypass the burden of manually doing this work every few weeks.

The recommended version for ACME certificate renewals is NSS-5.3.592.47.

General Requirements

1. Service Provider account with valid SPC(s) that is approved by STI-PA.

2. NSS(s) IP address(es) whitelisted by STI-PA.

3. API user for accessing STI-PA API (need Staging & Production).

Configuration

Once the ACME feature has been enabled by Sansay TAC, the ACME configuration is currently controlled by two configuration files:

/rome/ACME/csr.conf (Replace all $ with real values)

[req]
default_bits = 2048
distinguished_name = dn
prompt             = no[dn]
C="US"
ST="$YOURSTATE"
L="$YOURCITY"
O="$NAMEOFYOURORGANIZATION"
OU="$YOURDEPARTMENT"
emailAddress="$YOUREMAIL@COMPANY.com"
CN="$COMPANYNAME, $SPCCODE"

/rome/ACME/acme_config.json

{
  "mode":"PRODUCTION",
  "no_pa_mode":false,
  "caName":"Sansay",
  "caRootCertLocation":"https://cr.sansay.com/CA.crt",
  "orgName":"$Example company",
  "spAuthUser":"$sti-pa-user-for-your-company",
  "spAuthPass":"$averysecurepasswordyouhavepicked",
  "SpcList":["$OCNJ-replace"],
  "spEmail":"$you@yourcompany.com",
  "spTN":"$optional",
  "certificate_renewal_rate":720,
  "sti_ca_directory_url":"https://sti-ca.sansay.com:4443/acme"
}

720 is in hours, in this case the equivalent of 30 days.

Note: At this moment ACME configuration is done by Sansay Support, not the end user. In the near future, the config files will be available on the UI and then replaced with standard UI elements.