Security

Understanding the Security-Related APIs Defined by the SIP Servlet API

The following shows the security-related APIs in the SIP Servlet API.

• SipServletMessage.getUserPrincipal()
• SipServletMessage.isSecure()
• SipServletMessage.isUserInRole(java.lang.String role)
• SipServletMessage.getRemoteUser()

Each API behaves in SIP Servlet Engine as follows:

SipServletMessage.getUserPrincipal()

The principal of the user who was authenticated when receiving this SIP message is set. For an unauthenticated message, it returns null. And for an authenticated message, Principal.getName() returns the user name used to authenticate.

SipServletMessage.isSecure()

Returns whether the communication is secure or not. Because SIP Servlet Engine 3.0 supports only TCP and UDP for communication with clients, it always returns false.

SipServletMessage.isUserInRole(java.lang.String role)

Returns true if the role name mapped to the user, who was authenticated when receiving this SIP message, is specified as an argument. Otherwise, it returns false. And for an unauthenticated message, it always returns false.

SipServletMessage.getRemoteUser()

Returns the user name of the user who was authenticated when receiving this SIP message. It returns the same value as the SipServletMessage.getUserPrincipal().getName() returns. And for an unauthenticated message, it always returns null.

For an overview of the authentication and authorization processes, see Security Management.

How to specify the security-related tags in the sip.xml

The following shows the security-related tags:

• run-as which is the child of servlet
• security-constraint
• login-config
• security-role
• security-role-ref

For more information about each tag, see sip-app_1_0.dtd.

This section describes the examples of these tags and their behavior.

run-as

<servlet>
  <servlet-name>chat</servlet-name>
  <servlet-class>com.oki.sip.apps.demo.servlet.ChatRoomServlet</servlet-class>
  ....
  <run-as>
    <role-name>sipuser</role-name>
  </run-as>
</servlet>
....
<security-role>
  <description>Default SIP User</description>
  <role-name>sipuser</role-name>
</security-role>

In this case, if the servlet "chat" is called, the role name "sipuser" is used, for example, when called the EJB. When you define the role name which is not defined in the <security-role> tag, an exception will occur during startup.

security-constraint

 ....
 <security-constraint>
   <display-name>Default constraint for demo-application</display-name>
   <resource-collection>
     <resource-name>Default Constraint</resource-name>
     <description>Default Constraint</description>
     <servlet-name>registrar</servlet-name>
     <sip-method>SUBSCRIBE</sip-method>
   </resource-collection>
   <auth-constraint>
     <role-name>sipuser</role-name>
   </auth-constraint>
 </security-constraint>
 <login-config>
   <auth-method>DIGEST</auth-method>
   <realm-name>oki.com</realm-name>
 </login-config>
 <security-role>
   <description>Default SIP User</description>
   <role-name>sipuser</role-name>
 </security-role>

In this case, the digest authentication is performed for the request to the SipServlet defined as "registrar" and for the request whose SIP method name is "SUBSCRIBE". And the realm used in the digest authentication is "oki.com". If the "sipuser" role is not assigned to the user, the 403 response code will be returned even when the authentication succeeds.

To assign the role to the user, use the SIP Servlet Engine Management tool.((See sip-admin Users Manual.)

Limitations

You must consider the following limitations when using these security-related tags.

• You can specify only "DIGEST" in the <auth-method> of the <login-config> tag;. When you specify a different value, an exception will occur during startup. And it is not allowed to use Basic as an authentication scheme in RFC3261. (See http://www.ietf.org/rfc/rfc3261.txt).
• You should not specify "ACK" or "CANCEL" in the <sip-method> of the <resource-collection>. It is prohibited to return a response to these requests. (See http://www.ietf.org/rfc/rfc3261.txt).
• You should specify the role name defined by the SIP Servlet Engine Management tool in the <role-name>. You can not use the user names, group names, and role names registered on WebLogic Server 8.1SP3.

Last Modified:Tue Mar 23 13:46:42 JST 2004