Understanding Authentication

Authentication is the process of establishing association between the new incoming call and some particular account in the system. There are two basic methods for performing it in the Softswitch: using secure SIP digest and using Authentication Rules. Those methods will be described in details below. Please note that both methods could be combined together to provide advanced features (see DID assigning example below).

Secure SIP Digest-based Authentication

For Authentication of this type the new call is mapped into particular Account by performing so-called secure SIP digest authentication. In practice that means that the device or software that originates the call has username and password configured in it and those parameters are matched against VoIP Login and VoIP Password parameters of all Accounts until the match is found.

Only this type of authentication allows SIP device to register itself with the Softswitch, providing facility necessary for receiving on-net calls.

Main application of this Authentication method is providing support for connecting various SIP phones and ATAs to the Softswitch.

Rules-based Authentication

For Authentication of this type the new call is mapped into particular Account by matching the following four parameters of the new incoming call against one or more Authentication Rules that can be associated with each Account:

• IP address of the device or server that originates the call;
• Calling Number / ANI (CLI);
• Called Number / Destination Number (CLD);
• Protocol (SIP, H.323, IAX2, Calling Card PIN)

Whereas the first three protocols are pretty straight for the use, and simply check the match of the incoming traffic to their type when used in the rule, the Calling Card PIN is used only when IVR application is used, and the card number (PIN) is requested.

The system first check the match of the entered number to the username/voip login of any account within the system, case no match is found, the authentication rules, configured in the system with Protocol Calling Card PIN are checked for the match.

In order for the call to match the rule each of the four parameters of the call should match with appropriate parameters of least one Authentication Rule. When one or more parameters or Rule is empty only remaining parameters are matched against incoming calls (Protocol can not be empty at any condition)

For example the first rule will match any call originated from the IP address of 1.2.3.4 and having CLI 567890 and any CLD, while the second rule will match calls with CLD of 123456789 and any CLI coming from any IP.

Regular Expressions usage:

• Match any sequence of symbols till the end of the number

Wildcard form could be used in the Incoming CLI and Incoming CLD fields by putting asterisk (‘*’) after the number, which will result in prefix matching. For example the following modification of the first rule above will match any call originated from the IP address of 1.2.3.4 and having CLI starting with 567890 (e.g. 567890123).

Note: wildcard can match the absence of symbols too, so 567890* rule will match 567890 CLI as well.

• Match any symbol at any place of the number (starting from 5.2 version)

Pattern could be used in the Incoming CLI and Incoming CLD fields by putting question mark ('?') within the number, which will result in number matching. It provides a match for any character in incoming number in the corresponding place.

For example the following modification of the first rule above will match any call originated from the IP address of 1.2.3.4 and having CLI starting with 567, followed by any symbol, followed by 90 and another random symbol (e.g. 5678901 or 5670903).

Note: question mark can NOT match the absence of symbol, so 567?90? rule will NOT match neither 567890 nor 567901 numbers.

Weight distribution for authentication rules

When performing the match against several concurrent Rules the Softswitch also calculates so-called weights for each matching Rule in order to determine the best match. The formula is as follows:

1. Matching IP address adds 1.0 to the resulting weight;
2. Matching non-wildcard CLD or CLI adds 1.5 to the resulting weight;
3. Matching wildcard CLD or CLI adds 1.0 to the resulting weight;
4. For any matching wildcard CLI or CLD resulting weight is increased by the length of the matching part divided by the 100.
5. For any question mark CLI or CLD resulting weight is decreased by 0.001. Case wildcard is present in matching CLI or CLD, question mark has to be considered as regular symbol to be added to weight according to

For the example if the call from IP address of 1.2.3.4, CLI of 567890 and CLD of 123456789 comes the weights would be calculated as follows:

As a result, the rule 1 will be selected as the best match.

Note that when there are multiple rules with the same weight that give the best match, the authentication using Authentication rule will be rejected due to ambiguity, with 401 Unauthorized message sent, thus for that call only Digest Authentication would be possible.

Typical Applications for Rules-based Authentication

The Rules-based Authentication can accommodate different real-world scenarios. Some of them are listed below:

• VoIP Peering. Put IP address of peer’s softswitch into the Remote IP Address field.
• PSTN origination. Put IP address of gateway into the Remote IP Address field. If there are multiple gateways several rules with different IP addresses could be added.
• Assigning DID numbers. The DID (Direct Inward Dialing) service could be implemented by combining secure SIP digest authentication with one or more Authentication Rule that contain DID number coming from the origination gateway as the Incoming CLD field. Optionally, Remote IP Address could be used to only allow calls coming from a specific gateway to be considered as DID calls. Also, it might be necessary to apply translation rule to ensure proper routing of the call to the registered account.

Accessing Authentication Rules

To access Authentication Rules for a particular account, navigate to the Accounts menu, click on the Actions for specific Account. Authentication Rules is an action relating to the Account.

Authentication rules to block Individual Numbers

It is possible to manipulate this yourself, as is done in other Softswitch solutions - the method is as follows:

Adding a few numbers and maintaining a fairly simple list can be done manually by changing the authentication rules for the specific account. This can be done PER NUMBER or by blocking an entire country/city (or carrier) code.

Example if you wished to block calls going to CLI = 92321234567

1. Create the account with any service plan and Routing Group
2. Add Authentication Rule for the account with Incoming CLI = 92321234567
   it's you need to block calls based on NPA/NXX - you can also add a rule such as: 9232*, whereby all calls to 9232 xxx xxxx will be blocked.

You can also manipulate the authentication rules using the XML APIs - the support team can provide you with details on the correct XML API syntax.

Please note that calls dropped using this method will have SIP error: "403 Auth Failed" and will not be written to the CDRs.

While this solution works in limited numbers we do offer a Do Not Call List module that is far more effective for managing blocked calls. 

In our Flysip 2020 release we have made some changes to added some attributes that are used to handle account authentication:

• To domain (hostname in To: header of incoming INVITE)
• From Domain (hostname in From: header of incoming INVITE)

In example below From domain would be 123abc.from.com

From: "Mr John Smith" <sip:[email protected]:1036;user=some-id>;tag=43165asdgw3001

XML

Lets introduce an order of preference for attributes:

1. CLD
2. CLI
3. remote_ip
4. To domain
5. From domain

Rules to match the attributes.

1. If there is a matching rule which contains a CLD then any other rules with empty CLD are skipped.
2. Among the rules which passed the CLD check a rule which contains matching CLI beats any rule with empty CLI.
3. And so on...

Phone number matching (CLI, CLD)

1. If there is a matching rule which contains exact value then all rules with '*' or '?' chars in the value are skipped. If the winner is not determined, next step applies.
2. If there is a matching rule which contains symbol '*' it is beaten by any rule that does not contain such symbol. Still remaining rules are passed to next step.
3. Among two rules wins the rule which pattern has more non question mark characters.

Domain matching

1. A domain can be either exact, e.g. 'domain.com' or can be a suffix match: '*.domain.com', there is no prefix matching for domains. 
2. If there is a matching rule with an exact domain then all rules with suffix match are skipped.
3. Among two rules with '*' symbol wins the longest rule

The suffix matching is literal (unlike DNS zone match). For example the rule '*.domain.com' matches the 'test.domain.com' but does not match 'domain.com'. The rule '*domain.com' matches both 'test.domain.com' and 'domain.com'. The domain part of a SIP URL is not analyzed and if it is in fact an IP address then it is used as is.

The new behavior added in our Flysip 2020 release also allows for legacy authentication attribute order to be respected.  There is a system configuration setting under "system/sip/authentication/attr_order" allowing for parameters:

• "default" - equivalent to "cld,cli,remote_ip,to_domain,from_domain"
• "old_style" - equivalent to "weight,to_domain,from_domain".

It is possible in Flysip 2020 versions and greater to be able to create custom order of these attributes.  If you are upgrading to 2020 your authentication methods will be set to "old_style".  At the present time this change must be handled by contacting our support team.