The MMTelICB feature implements incoming communication barring and anonymous communication rejection . (The MMTelOCB feature implements outgoing communication barring.)
What is ICB?
3GPP defines Communication Barring in TS 24.611, including Incoming Communication Barring (ICB), Anonymous Communication Rejection as a special case of ICB, and Outgoing Communication Barring (OCB):
The incoming communication barring (ICB) is a service that rejects incoming communications that fulfil certain provisioned or configured conditions on behalf of the terminating user. The anonymous communication rejection (ACR) is a particular case of the ICB service, that allows barring of incoming communications from an anonymous originator on behalf of the terminating user. The incoming communication barring (ICB) service makes it possible for a user to have barring of certain categories of incoming communications according to a provisioned or user configured barring program and is valid for all incoming communications. A barring program is expressed as a set of rules in which the rules have a conditional part and an action part. Examples of conditions are whether the asserted originating public user identity matches a specific public user identity or whether the originating public user identity is restricted (anonymous). The action part could specify for a rule that contains a matching condition that the specific incoming communication is barred. The inhibition of incoming forwarded calls is a special case of the ICB and allows the served user to reject incoming communications from users or subscribers who have diverted the communication towards the served user. The communication history information will be used to trigger the service. The anonymous communication rejection (ACR) service allows the served user to reject incoming communications on which the asserted public user identity of the originating user is restricted. In case the asserted public user identity of the originating user is not provided then the communication is allowed by the ACR service. It is highlighted here because it is a regulatory service in many countries. |
Feature Cheat Sheet
B2BUA Instance | SAS Support | Originating / Terminating | Point(s) in Session Plan | Network Operator Data | Subscriber Data | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|---|---|---|
MMTEL |
Yes |
Terminating |
SipAccess_SubscriberPreCreditCheck |
Yes |
Yes, comes from the HSS |
Stateless |
POJO |
Prerequisite Features
-
DetermineCallType
-
SubscriberDetermination
-
Determine International and Roaming Status (used for Roaming, International and International-exHC detection)
For announcements, SIPPlayAnnouncement is a dependent feature; but it is not a prerequisite. |
Source Code
This feature’s source code is available in the Sentinel VoLTE SDK in the mmtel-communication-barring
module pack.
It can be viewed by using the create-module
command in the SDK with that module pack, for example:
> create-module new-cb-module opencloud#mmtel-communication-barring#volte/4.0.0;4.0.0.0
This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.
The module-pack includes the following modules relevant to this feature:
Module Name | Description |
---|---|
mmtel-communication-barring |
Group module for the feature that includes all of the modules listed below. |
mmtel-communication-barring-library |
Contains code shared by both communication barring features. |
mmtel-icb-profile |
Contains the profile specification for the feature configuration profile table. |
mmtel-icb |
Contains the feature itself. |
Network Operator Data
This data is stored in a JSLEE Configuration Profile Table, called MMTelICBConfigProfileTable
.
Operator data is scoped according to a Sentinel selection key.
Attribute Name |
Type |
Default Value |
Description |
PlayAnnouncement |
Boolean |
false |
If true, ICB will request an announcement is played in the case that it bars the session setup. |
ACRAnnouncementID |
int |
0 |
The ID for the announcement to be played in the case of Anonymous Call Rejection. If set to zero there is no announcement. |
AnnouncementID |
int |
0 |
The ID for the announcement to be played in all other ICB cases. If set to zero there is no announcement. |
InternationalRulesActive |
Boolean |
false |
If false, ICB will ignore International and International-exHC rules. |
Session Input Variables
Variable name |
Type |
Comments |
bxref:mmtel-subscriber-data-representation#mmtelicbservicedata[MMTelICBServiceData] |
Complex |
Read from the HSS or HLR in SubscriberDataLookupFromHSS or SubscriberDataLookupFromHLR |
RoamingIndicator |
Boolean |
Set by the Determine International and Roaming Status feature. |
International |
Boolean |
Set by the Determine International and Roaming Status feature. |
InternationalExHC |
Boolean |
Set by the Determine International and Roaming Status feature. |
BarIncomingCall |
Boolean |
Set by other preceding features to trigger General Feature Barring. |
Session Output Variables
Variable name | Type | Comments |
---|---|---|
ICBBarred |
Boolean |
Set to true if the ICB feature bars the call. It exists so that feature execution scripts can read the variable and take action |
ICBBarredWithAnnouncement |
Boolean |
Set to true if the ICB feature bars the call, and the feature is configured to request an announcement as part of barring |
AnnouncementID |
int |
The announcement ID to be used if an announcement is configured as part of barring |
EndSessionAfterAnnouncement |
int |
The status code used when ending the session — if barring has occurred and announcements are used. |
RanIcb |
Boolean |
Signals to other features that ICB ran on this session. |
Supported Barring Rule Conditions
Barring rule conditions that are evaluated include:
Anonymous
To comply with the requirements as set for simulation of the ACR service, the anonymous element only evaluates to true when the conditions as set out in subclause 4.5.2.6.2 for asserted originating public user identity apply.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for anonymous calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="anonymous">
<cp:conditions>
<anonymous/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Roaming
This condition evaluates to true if the session state variable RoamingIndicator
is true.
This is set by the Determine International and Roaming Status feature.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for roaming calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="roaming">
<cp:conditions>
<roaming/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Media
This condition evaluates to true when the value of this condition matches the media field in one of the "m=" lines in the SDP message body offered in an INVITE request.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for calls offering specific media:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="no_video">
<cp:conditions>
<media>video</media>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Combinations of media types may be expressed as multiple conditions within the same rule. For example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="no_video_and_text">
<cp:conditions>
<media>video</media>
<media>text</media>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Identity
This condition evaluates to true if the identity of the other party in the communication matches that which is expressed in the condition. Identities within the condition can be expressed in different ways:
-
a single, fully expressed identity (e.g. sip:alice@example.com)
-
a whole domain (e.g. example.com)
-
a whole domain, but with exceptional identities or domains (e.g. example.com except for alice@example.com)
-
all identities (may also have exceptions)
-
any combination of the above
In case of a single identity (i.e. a 'one' condition), or in case of an exception (i.e. an 'except' condition), the URI in the condition and the URI to match against are both normalized before they are compared. Normalization is done using the Normalization Component.
The following XML snippets show how to configure the user’s Subscriber data for each of the above cases.
This example, without any other rule, blocks any session from 'sip:alice@example.com'.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="bar-alice">
<cp:conditions>
<cp:identity>
<one id="sip:alice@example.com"/>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
This example, without any other rule, blocks any session from domain 'example.com'.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="bar-domain">
<cp:conditions>
<cp:identity>
<many domain="example.com"></many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
This example, without any other rule, blocks any session from domain 'example.com' except if originated from 'sip:alice@example.com'.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="barr-domain-with-exception">
<cp:conditions>
<cp:identity>
<many domain="example.com">
<except id="sip:alice@example.com"/>
</many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
This example, without any other rule, blocks any session from domain 'example.com' except if originated from the subdomain 'callcentre.example.com'.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="barr-domain-except-callcentre">
<cp:conditions>
<cp:identity>
<many domain="example.com">
<except domain="callcentre.example.com"/>
</many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Note the attribute of the 'except' element is now 'domain'. |
This example, without any other rule, blocks all sessions from any user.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="barr-all">
<cp:conditions>
<cp:identity>
<many />
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
This example, without any other rule, blocks any session from all users registered in the domain 'example2.com', from the user 'sip:alice@example1.com' and from the user sip:bob@example1.com, except from 'sip:charlie@example2.com.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="barr-some">
<cp:conditions>
<cp:identity>
<one id="sip:alice@example1.com"/>
<one id="sip:bob@example1.com"/>
<many domain="example2.com">
<except id="sip:charlie@example2.com"/>
</many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
This example, always blocks some domains, always allow other domains and a set of sip URIs.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="always-allow-these-domains">
<cp:conditions>
<cp:identity>
<many domain="emergency.org"></many>
<many domain="police.org"></many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>true</allow>
</cp:actions>
</cp:rule>
<cp:rule id="always-barr-these-domains">
<cp:conditions>
<cp:identity>
<many domain="fakelotery.org"></many>
<many domain="dhueb!.org"></many>
<many domain="fakeprize.com"></many>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
<cp:rule id="always-barr-these-identities">
<cp:conditions>
<cp:identity>
<one id="sip:john@example.com"/>
<one id="sip:marc@example.com"/>
</cp:identity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Depending on the value of the 'allow' element of the rule, the rule can essentially become an 'allowlist' or a 'blocklist'. |
International
This condition evaluates to true if the session state variable International
is true and 'InternationalRulesActive' is true.
'International' is set by the Determine International and Roaming Status feature.
'InternationalRulesActive' is configured in the ICB feature profile and defaults to false. This is because it is not possible to accurately determine whether the calling party is international in all circumstances.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for international calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="international">
<cp:conditions>
<international/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
International-exHC
This condition evaluates to true if the session state variable InternationalExHC
is true and 'InternationalRulesActive' is true.
'International' is set by the Determine International and Roaming Status feature.
'InternationalRulesActive' is configured in the ICB feature profile and defaults to false. This is because it is not possible to accurately determine whether the calling party is international in all circumstances.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for international-exHC calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="international-exHC">
<cp:conditions>
<international-exHC/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Unconditional
An empty conditions element is used to represent unconditional.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for all calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="anonymous">
<cp:conditions/>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Communication Diverted
This condition evaluates to true when the incoming communication has been previously diverted.
Diverted communication can be recognised by the presence of the History
header field, as specified in 3GPP TS 24.604
Use this XML in the REM HSS Subscriber Data Page to configure ICB for diverted calls:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="diverted">
<cp:conditions>
<communication-diverted/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Validity
This condition evaluates to true if the current time is within the times specified by the validity period Time is based on the Home Network time; that is, the time of the MMTel Server.
Use this XML in the REM HSS Subscriber Data Page to configure ICB for a validity period:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="validity">
<cp:conditions>
<cp:validity>
<cp:from>2000-01-01T00:00:00</cp:from>
<cp:until>2099-12-31T23:59:59</cp:until>
</cp:validity>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Rule Deactivated
This condition always evaluates to false. Generally used to disable a rule that has other conditions without removing the rule entirely.
The rule is re-enabled by removing this condition.
Use this XML in the REM HSS Subscriber Data Page to configure a deactivated rule:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:cp="urn:ietf:params:xml:ns:common-policy" xmlns:ocp="urn:oma:xml:xdm:common-policy">
<cp:rule id="deactivated">
<cp:conditions>
<rule-deactivated/>
</cp:conditions>
<cp:actions>
<allow>false</allow>
</cp:actions>
</cp:rule>
</cp:ruleset>
Barring Rule Actions
Barring rule actions are a string. There could be many actions defined, but the only one that makes any sense is the allow
action.
The allow
action has a Boolean attribute, with meaning as follows:
-
true
— allow session setup to proceed -
false
— deny session setup from proceeding.
Any other rule action (in other words, an action that is not set to allow
) will result in us treating the action as the following:
-
allow rule action with value of true.
Statistics
MMTelICB statistics are tracked by the sentinel.volte.sip SBB
and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.volte.sip service → sentinel.volte.sip SBB → feature → MMTelICB
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.volte.sip,vendor=OpenCloud,version=4.0.0].SbbID[name=sentinel.volte.sip,vendor=OpenCloud,version=4.0.0].feature.MMTelICB"
Statistic | Type | Incremented when… |
---|---|---|
Started |
Counter |
the feature runs |
FailedToStart |
Counter |
Sentinel VoLTE encounters an error while attempting to start the feature |
IssuedWarning |
Counter |
a non-fatal problem is encountered and the feature issues a warning |
FailedDuringExecution |
Counter |
a fatal problem is encountered and the feature cannot execute correctly |
TimedOut |
Counter |
the feature takes too long to complete and Sentinel VoLTE aborts execution |
CallBarred |
Counter |
the feature bars a call (including when barring due to ACR) |
CallBarredByOdb |
Counter |
the feature bars a call by Operator Determined Barring rule |
PlayAnnouncementTriggered |
Counter |
the feature requests that an announcement be played to the calling party |
ACRTriggered |
Counter |
a call is barred by ACR |
OdbRulesEvaluatedTrue |
Counter |
a rule was evaluated to be True |
RulesEvaluatedTrue |
Counter |
incremented by the number of rules which evaluated true |
FallbackToNetworkDefaultServiceConfig |
Counter |
incremented when the feature uses the network default service configuration as the session state does not contain the feature specific subscriber service data. |
Behaviour
Determination
If operator data is not present, the ICB feature:
-
Increments an error statistic.
-
Logs a message at the
Fine
level. -
Informs the Sentinel core that the feature is not configured appropriately (
Invalid Configuration
). -
Exits.
If General Feature Barring determines that a call should be barred - Barring Action below proceeds.
If MMTelICBServiceData.OperatorAuthorized
or MMTelICBServiceData.Active
is false
, the feature finishes execution without modifying any state.
If the rules do not parse, then the feature:
-
instructs Sentinel core that the feature has failed due to configuration problems
-
finishes execution without modifying any state.
Incoming ODB Rule Processing occurs as below.
If no ODB rules match, ICB Rule Processing occurs as below.
If either rule set determines allow=false
, the Barring Action is performed as below.
If either set determines allow=true
or no rules are matched, the ICB feature sets the session output variable ICBBarred
to false
and finishes without modifying any further state.
Rule Processing
When the feature processes a set of rules (either ODB or ICB):
For each rule, if | then |
---|---|
|
the rule matches. |
The actions from all matching rules are combined.
If… | then the combined result for the rule set is: |
---|---|
any matching rules had the action |
|
all matching rules had the action |
|
When a rule contains multiple conditions, they all must match for the whole rule to match. This is essentially a logical 'AND' between the conditions. To express a logical 'OR' of conditions, the conditions must be placed in different rules. |
Barring Action
If a ruleset determines allow=false
or GFB bars the call then…
The ICB feature sets the session output variable ICBBarred
to true
.
If network configuration has PlayAnnouncement
set to true
(MmtelICBConfig.PlayAnnouncement == true
), and ICB has decided to bar the communication, then the ICB feature sets session output variable AnnouncementID
to MmtelICBConfig.AnnouncementID
.
Finally, if the communication is to be barred, ICB rejects the call with the appropriate SIP error response code:
If any matching rule contains the “anonymous” condition, use 433 Anonymity Disallowed. This is to provide ACR functionality. (See section 4.5.2.6.1.)
Otherwise use 603 Decline.
Roaming Determination
The ICB feature does not compute whether or not the served user is roaming; rather it relies on a session input variable (isRoaming
).
This is set by Sentinel’s DetermineIfRoaming
feature.
Example feature execution script fragment:
run DetermineInternationalAndRoamingStatus run MMTelICB
Playing Announcements
The MMTelICB feature does not play announcements itself; rather it relies on setting of session output variables (AnnouncementID
, ICBBarredWithAnnouncement
, EndSessionAfterAnnouncement
).
These are set by the MMTelICB feature if an announcement is to be played. They are used by the out-of-the-box feature execution scripts such that if announcements are desired to be played
prior to the barred call being terminated, it is played using the SIPPlayAnnouncement feature.
This is an example feature execution script, taken from a fragment of the out-of-the-box execution scripts.
run MMTelICB if (session.ICBBarredWithAnnouncement) { run SIPPlayAnnouncement }
The SIPPlayAnnouncement feature checks session state for the AnnouncementID
field, and if the value is non-zero will play an announcement.
When the announcement is played using the SIPPlayAnnouncement
feature, it is played to the calling party.
Finally, when the announcement is complete the SIPPlayAnnouncement
feature ends the session with the appropriate SIP error response (provided by MMTelICB during its execution).
The SIP error response code is set in the EndSessionAfterAnnouncement
session output variable.
Background Information on Format of Barring Rules
Each rule is expressed as an XCAP cp-rule.
That is, it is an XML fragment:
<cp:rule id="rule66"> <cp:conditions> condition1 condition2 </cp:conditions> <cp:actions> <allow>false</allow> </cp:actions> </cp:rule>
In case that the allow element is not found, the feature assumes allow = false.