Figure 1. Connection between HSS and other network entities
Published on dev2dev (http://dev2dev.bea.com/)
http://dev2dev.bea.com/pub/a/2006/10/home-subscriber-server.html
See this if you're having trouble printing code examples
by Stefano Gioia
10/09/2006
The Home Subscriber Server (HSS) is the master user database that supports IMS network entities that handle calls and sessions. This article explains the way in which a Home Subscriber Server can communicate with a WebLogic SIP Server (WLSS). It also discusses the different data that a WebLogic SIP Server can retrieve from the HSS and how this data can be updated. This article provides a general and technical introduction to the DIAMETER protocol and the Sh Interface, and shows the different types of requests that can be used by WLSS to retrieve user data for executing a service.
The second part of this article will focus on BEA's interoperability test (IOT) with Bridgewater Systems' HSS as an example of the communication between WLSS and the HSS. See the WebLogic Communications Platform developer center on Dev2Dev for additional articles that provide basic information about the SIP protocol and DIAMETER.
The Home Subscriber Server is the master user database that supports the IMS network entities that handle the calls/sessions. It contains user profiles, performs authentication and authorization of the user, and can provide information about the physical location of user. It's similar to the GSM Home Location Register. The entities that communicate with the HSS are the application server (AS) that hosts and execute services in the IMS environment, and the Call State Control Function servers (CSCF). The User Profile contains information about the current user—usually the S-CSCF downloads it uses when a user is registering on the network. The S-CSCF will receive the profile in a User-data Attribute Value Pair (AVP) format.
The 3GPP specs allow three types of ASes to function in the IMS network. Note that two out of the three are legacy (OSA and IM)
Figure 1. Connection between HSS and other network entities
Each AS can optionally talk with an HSS using the DIAMETER Protocol over the Sh Interface (IM-SSF usually communicate using the Si interface). CSCF are used to process SIP signaling packets in the IMS network. There are two types of CSCF, connected to the HSS using DIAMETER Protocol over Cx Interface:
Let's now dive into the DIAMETER protocol before investigating the Sh interface and WebLogic SIP Server.
The DIAMETER base protocol is a protocol that performs authentication, authorization, and accounting (AAA) in the IP Multimedia Subsystem and in the Next Generation Networks. The DIAMETER protocol is specified in RFC3588 and is the evolution of the well-known RADIUS protocol. The DIAMETER base protocol provides the capability negotiations between the network entities involved in the communication, the error notification, the delivery of the Attribute-Value-Pair, and the extensibility so you can add specific commands and new AVPs. DIAMETER can also operate in both local and roaming situations. Unlike SIP, DIAMETER uses binary encoding, but tools such as Ethereal allow easy decoding of the protocol messages, and it has been used in this interoperability test.
DIAMETER is designed in terms of a base protocol and an extensible set of applications, which means that the protocol is split in two parts: the base protocol, used for delivering the messages and error notifications, and negotiating the capabilities; and the DIAMETER application that defines new commands and data units. These new applications are, in our context, the Cx and Sh applications. The Cx application is primarily used to connect the CSCF to the HSS, while the Sh application is used by the application server, with the exception of the IM-SSF, which uses the Si application.
The application server, WebLogic SIP Server in this case, uses a command, that is, User-Data-Request (UDR), to request data. The HSS answers with a User-Data-Answer (UDA) that contains the requested data and a result code. This result code indicates if the request was successful or not. As an example, a successful operation will have the Result Code 2001 DIAMETER_SUCCESS.
Here is a list of terminology taken from RFC 3588 that may be involved in a DIAMETER communication (WLSS usually performs all the roles except the DIAMETER Server functions):
Now it's time to introduce our main actor: the Sh application. This interface allows an application server to communicate with the HSS so that it can extract the necessary data to dispatch the logic of the service. Imagine a Call Screening service, where the user can configure the schedule of activation of the service. This data will be stored in the HSS and will be recovered by the WLSS for the activation of the service. Such data comes in two forms: transparent or not transparent, which means that the HSS understood syntactically but not semantically (transparent) while non-transparent means that the HSS can understand both syntactically and semantically. These kinds of data are unique to the user. This is what we call User Profile. Basically, a User Profile contains from one to many Service Profiles; each of them defines how the service must be executed.
The Sh interface protocol is defined as an IETF vendor-specific DIAMETER application, where the vendor is 3GPP. The vendor identifier assigned by IANA to 3GPP is 10415, and the DIAMETER application identifier assigned to the Sh interface application is 16777217.
The list below summarizes the type of data that can be requested using an Sh application:
Figure 2. Sh data UML diagram
The implementations of Sh interface in an application server can operate in two modes: Data Handling and Subscriptions/Notification.
The commands specified by an Sh Interface are summarized in the following table:
Every time an AS makes a request for information related to a specific user, the HSS must verify if the AS has the necessary rights to issue the request. The HSS manages a Permission List, a list of rights granted to each AS. These rights are related to the aforementioned Sh-Pull, Sh-Update, and Sh-SubNotif and can be assigned one by one or in any combination. For example, an AS can be granted the Sh-Pull right but not the Sh-Update right. These rights are associated to all the users configured in the HSS.
The Sh application specifies two kinds of failures: the permanent failure and the transient failure. The transient failures are used to inform a peer that the request could not be satisfied at the time that it was received. The request may be able to be satisfied in the future. These failures are used to inform one peer about a failed request (in a permanent or transient way). We will deal with these failures in greater detail in the section about the basic Interoperability Test (IOT) with a real HSS. You can find a list of permanent failures specified in the Sh application in 3GPP TS.29.329 specifications. Here you can find two examples from it (in brackets the Result-Code):
|
This section examines how easy is to use the API included in the current release of WLSS to communicate with an HSS server.
The DIAMETER Sh interface is exposed as a Provider, and the container will take care of all DIAMETER behaviors. For a developer, WebLogic SIP Server provides an interface com.bea.wcp.profile.ProfileService whose implementation is registered in the servlet context, and can be used for easily retrieving the profile. The helper class returns the user data as an XML document, and the developer can use standard DOM techniques to work on it. In the case of the Sh Pull Update command, the ProfileService will always return the user data as read-only documents, so you have to explicitly clone it before modifying it. Regarding the Sh Profile Update request, the application can specify a ProfileListener class to be notified of incoming messages from the HSS. Thanks to the converged container you can query the HSS no matter which channel is currently being used, HTTP or SIP.
Building an Sh request is pretty simple. An Sh request always follow this schema:
protocol://uri/reference_type/access_key
Where:
These are some examples of Document Selector Elements for Sh Data Request:
sh://sip:username@domain.com/RepositoryData/IM2SMSsh://sip:username@domain.com/IMSPublicIdentity/sh://sip:username@domain.com/MSISDN/In an HTTP or SIP servlet, the very first thing to do is to import com.bea.wcp.profile.ProfileService. In the init() method a reference to the ProfileService is stored for retrieving data from the HSS. This code snippet shows how to do this:
public void init() throws ServletException
{
ServletContext sc = getServletContext();
// Get the ProfileService from the ServletContext
ps = (ProfileService)
sc.getAttribute(ProfileService.PROFILE_SERVICE);
if (ps == null)
{
throw new ServletException("Profile service not found");
}
System.out.println(getClass().getName() + " initialized");
}
It's easy to execute an Sh Pull request in WLSS. The example below shows how to build an Sh Request String, based on the request type using a switch statement:
public static String buildShRequest( int requestType,
String userName, String ServiceName, int domainType,
String serverName )
{
String docSelector = "sh://sip:";
// Get username
docSelector += userName;
// Matching RequestType with Data reference
switch(requestType)
{
case Constants.SH_REPOSITORY_DATA:
docSelector += "/RepositoryData/" + ServiceName;
break;
case Constants.SH_MSISDN:
docSelector += "/MSISDN/";
break;
case Constants.SH_IMS_PUBLIC_IDENTITY:
docSelector += "/IMSPublicIdentity/";
break;
case Constants.SH_CHARGING_INFO:
docSelector += "/ChargingInformation/";
break;
case Constants.SH_USER_STATE:
docSelector += "/UserState/";
docSelector += (domainType==Constants.SH_PS_DOMAIN)?"PS-Domain/":"CS-Domain/";
break;
case Constants.SH_IMS_USER_STATE:
docSelector += "/IMSUserState/";
break;
case Constants.SH_S_CSCF_NAME:
docSelector += "/S-CSCFName/";
break;
case Constants.SH_INITIAL_FILTER_CRITERIA:
docSelector += "/InitialFilterCriteria/" + serverName;
break;
case Constants.SH_LOCATION_INFO:
docSelector += "/LocationInformation/";
docSelector += (domainType == Constants.SH_PS_DOMAIN)? "PS-Domain/":"CS-Domain/";
break;
}
}
Now we're going to execute an Sh Pull request in WebLogic SIP Server. In this example we're requesting a RepositoryData, so we need to get extra information beyond the user. You need the service name. After building the Sh request we pass it to the ProfileService previously instantiated:
private String executeTest(String theShRequest)
{
String response = null;
try {
logger.debug("Sh Request: " + theShRequest );
// Get the document from the HSS
Document genericDoc = ps.getDocument(theShRequest);
response = DIAMETERHelper.toString(genericDoc.getDocumentElement());
logger.debug("HSS Response: \n" + response);
} catch (ProfileException e) {
// Get the Message Exception
MessageException me = (MessageException)e.getCause();
// Get the DIAMETER ResultCode
ResultCode rc = me.getResultCode();
session.setAttribute(Constants.DIAMETER_RESULT_CODE, rc.toString());
session.setAttribute("Exception", e.getMessage());
logger.debug("Exception - DIAMETER Result Code is: " + rc.toString() );
} catch (Exception e) {
response = e.getMessage();
session.setAttribute("Exception", e.getMessage());
logger.debug("Exception: " + response);
}
return response;
}
After receiving the data from the HSS using Sh Pull, it's now possible to modify it using the standard DOM techniques. Saving the new data is simple: All you have to do is clone the document received previously (because ProfileServer returns a read-only document) and then call the method put() exposed by the ProfileServer, as shown here:
private String executeTest(String theShRequest, String newData,
String newValue)
{
String response = null;
try {
logger.debug("Sh Request: " + theShRequest );
Document originalDoc = ps.getDocument(theShRequest);
// Preparing to modify the document
logger.debug("Going to prepare document");
// Modifying original document
Document modifiedDocument = this.saveDoc(
(Document)originalDoc.cloneNode(true),newData, newValue);
// Storing using Profile
ps.putDocument(theShRequest, modifiedDocument);
logger.debug("Saving data into HSS");
// Store in session the SIP SH Output Request
session.setAttribute(Constants.SIPAS_OUTPUT,
DIAMETERHelper.toString(modifiedDocument));
response = DIAMETERHelper.toString(
originalDoc.getDocumentElement());
logger.debug("HSS Response: \n " + response);
} catch (ProfileException e) {
MessageException me = (MessageException)e.getCause();
ResultCode rc = me.getResultCode();
session.setAttribute(Constants.DIAMETER_RESULT_CODE,
rc.toString());
session.setAttribute("Exception", e.getMessage());
logger.debug("Exception - DIAMETER Result Code is: " +
rc.toString() );
} catch (Exception e) {
response = e.getMessage();
session.setAttribute("Exception", e.getMessage());
logger.debug("Exception: " + response);
}
return response;
}
|
This section examines how we set up the test environment and how we drive the test with Bridgewater Systems. We start by presenting how we configure the environment, then we briefly discuss the Web application used in the test and a description of the messages exchanged between WebLogic SIP Server and the HSS. The system under test consists of two servers running the WLSS 2.2 instances, acting as a DIAMETER node, connected with the Bridgewater HSS. On one server two instances of WLSS will be running, one acting as an Admin Server, one as a DIAMETER node. The other DIAMETER node is running on the other server, as showed in Figure 3:
Figure 3. The test environment
If you don't have a real HSS, you can download WLSS and use our HSS Simulator. Just follow these simple steps:
The Configuration Wizard includes a DIAMETER domain template that creates a domain with four WebLogic SIP Server instances:
Refer to the documentation on how to configure a diameter domain.
The sample application presented in this article is a simple example built for testing in an easy way the message flow described in this article. The application lets you query and update the data stored in the HSS. It's possible to send out Sh-Pull, Sh-Update, and Sh-Subs-Notify requests using a simple Web interface. You can choose the user name, the type of request, the service name, in case of Sh-Pull, and the service data and service value in case of Sh-Update. This application shows that WLSS can successfully communicate with an HSS and conforms to 3GPP Technical Specification documents for the Sh interface.
Figure 4. Show the home page of the Web application used to test Sh
There are three simple JSP pages: The Sh-Pull.jsp is used to test Sh-Pull request, the Sh-Update.jsp is used to test Sh-Update, and the Sh-Subs-Notif is used to test Sh-Subs-Notif. There is another special page, the profileViewer.jsp, which is used to query the HSS and get the full user profile. All you have to do is to insert the username in the field, and submit the form. In the web.xml you can find two parameters:
These parameters are read at startup and you can change them to meet your requirements. Once the connection with the HSS is established you can use those pages to query the HSS. In addition, the Web application prints out the ResultCode, the XML response generated by the HSS, and eventually the exception, as showed in Figure 5:
Figure 5. Show a simple PUR response (click the image for a full-size screen shot)
Just before the real connection, WLSS should be able to connect to an HSS server. In this case, WLSS should send a Capability-Exchange-Request (CER) to the configured HSS server: The HSS must return with a Capability-Exchange-Answer (CEA). The CEA is used to determine what diameter applications are supported by each peer.
After it has established the connection WLSS could send a User-Data-Request (UDR) request to the HSS Server: The HSS should correctly read the request and send a response User-Data-Answer (UDA). Going the other way, the application should be able to read the response: Each of them should match. The following diagram shows the behavior of the UDR:
Figure 6. Show UDR behavior (click the image for a full-size screen shot)
The preconditions for a positive test result are summarized below:
This command type can be used to update user data contained in the HSS. The same command can be also used to remove user information from the HSS. WLSS sends a Profile-Update-Request (PUR) toward the HSS that executes the update and replies with a Profile-Update-Answer (PUA) containing the result of the operation.
It is important to emphasize that a SIP Application Server can update/remove data about the services it is owning.
Figure 7. Show PUR behavior
The preconditions for a positive test result are summarized below:
The message is used by the WLSS to subscribe to a user that exists in the HSS. The WLSS sends a Subscribe-Notifications-Request (SNR) to receive notifications of user data changes specified in the SNR. The HSS acknowledges the SNR with a Subscribe-Notification-Answer (SNA). The same command is used to remove the subscription.
Figure 8. Show SNR behavior
The preconditions for a positive test result are summarized below:
After a successful Sh Update request the HSS sends PNR messages to all previously subscribed entities. So, all WLSS entities being subscribed to receive change notifications will now receive PNR messages from the HSS. The PNR message contains details about the changed data. The WLSS answers the PNR with a Push-Notification-Answer (PNA).
Figure 9. PNR diagram
Introduced a few years ago, DIAMETER is proving to be the next-generation authentication, authorization, and accounting protocol for applications such as network access and IP mobility. It provides an extensible base protocol to deliver AAA services to new access technologies or applications. DIAMETER was originally designed to overcome issues in RADIUS such as security, reliability, lack of a peer-to-peer relationship between the client and the server, lack of real-time accounting, and standardization of usage in certain environments (some of these issues have been addressed by RADIUS extensions). The key drivers for DIAMETER deployments are focused around security, standardization to reduce costs and accelerate time to market, and the ability to roll out IMS.
This article explains the communication between the WebLogic SIP Server 2.2 and the Bridgewater HSS utilizing the Sh DIAMETER application. It describes the role of the HSS and how it stores data. Furthermore, the article explains how the WebLogic SIP Server retrieves and modifies this information. The sample Web application described in the article proves BEA's interoperability with Bridgewater's HSS, a leading industry provider of subscriber-centric policy management software for IP-based services.
The author would like to thank Pascal Henry, Director of Market Development, Bridgewater Systems for his support, his contribution and for proof reading the article.
AAA: Authentication, Authorization, and Accounting
API: Application Programming Interface
AS: Application Server
CAMEL: Customized Application for Mobile network Enhanced Logic
CAP: Camel Application Part
CEA: Capability-Exchange-Answer
CER: Capability-Exchange-Response
CSCF: Call State Control Function
DOM: Document Object Model
EAP: Extensible Authentication Protocol
GSM: Global System for Mobile Communications
HSS: Home Subscriber Server
I-CSCF: Interrogating CSCF
ISC: IMS Service Control
IM-SSF: IP Multimedia Serving Switching Function
IMS: IP Multimedia Subsystem
IOT: Inter Operability Testing
NASREQ: Network Access Server Requirements
MSISDN: Mobile Subscriber International Services Digital Network
OSA: Open Service Architecture
OSA-SCS: OSA Service Capability Server
PNA: Push-Notification-Answer
PNR: Push-Notification-Response
PUA: Profile-Update-Answer
PUR: Profile-Update-Response
RADIUS: Remote Authentication Dial In User
S-CSCF: Serving CSCF
SIP: Session Initiation Protocol
SIP-AS: Sip Application Server
SNA: Subscribe-Notifications-Answer
SNR: Subscribe-Notifications-Response
UDA: User-Data-Answer
UDR: User-Data-Request
WLSS: WebLogic Sip Server
XML: Extensible Markup Language
Stefano Gioia is the WebLogic Sip Server Technology Specialist for BEA in EMEA. Focused on IMS opportunities with both operators and partners across Europe, the Middle East,and Africa
Return to dev2dev.