Developing a custom trust association interceptor for Session Initiation Protocol applications

When you develop Session Initiation Protocol (SIP) applications, you can create a custom trust association interceptor (TAI).

1. Write a Java class that extends the com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor class and implements the com.ibm.websphere.security.tai.extension.SIPTrustAssociationInterceptor interface.
   Those classes are defined in the wasHome/plugins/com.ibm.ws.sip.container_1.0.0.jar file, where wasHome is the fully qualified path name of the directory in which WebSphere Application Server is installed.
2. Declare the following Java methods, which are required by the SIPTrustAssociationInterceptor interface:

   public int initialize(Properties properties) throws WebTrustAssociationFailedException;

   This method is invoked before the first message is processed so that the implementation can allocate any resources that it needs. For example, it might establish a connection to a database. The value of the properties argument comes from the Custom Properties set in this step.

   public String getVersion();

   This method returns the version number of the current TAI implementation.

   public String getType();

   This method's return value is implementation-dependent.

   public void cleanup();

   This method is invoked when the TAI must free any resources that it holds. For example, it might close a connection to a database.

   public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws WebTrustAssociationFailedException;

   Your custom TAI uses this method to handle the sipMsg message. If the method returns false, WebSphere ignores your TAI for sipMsg.

   public TAIResult negotiateValidateandEstablishProtocolTrust (SipServletRequest req, SipServletResponse resp) throws WebTrustAssociationFailedException;

   This method returns a TAIResult that indicates the status of the message that is being processed and a user ID or the unique ID for the user who is trying to authenticate. If authentication succeeds, the TAIResult contains the status HttpServletResponse.SC_OK and a principal. If authentication fails, the TAIResult contains a return code of HttpServletResponse.SC_UNAUTHORIZED (401), SC_FORBIDDEN (403), or SC_PROXY_AUTHENTICATION_REQUIRED (407). This code indicates only whether the container accepts a message for further processing. To challenge an incoming request, the TAI implementation must generate and send s own SipServletResponse that contained a challenge. The exception should be thrown for internal TAI errors. Table 1 describes the argument values and resultant actions for the negotiateValidateandEstablishProtocolTrust method.

   Table 1. Description of negotiateValidateandEstablishProtocolTrust arguments and actions .

   This table provides a description of negotiateValidateandEstablishProtocolTrust arguments and actions

   Argument or action	For a SIP request	For a SIP response
   Value of req argument	The incoming request	Null
   Value of resp argument	Null	The incoming response
   Action for valid response credentials	Return TAIResult.status that contains SC_OK and a user ID or unique ID.	Return TAIResult.status containing SC_OK and a user ID or unique ID.
   Action for incorrect response credentials	Return the TAIResult with the 4xx status.	Return the TAIResult with the 4xx status.

   The sequence of events is as follows:

   1. The SIP container maps initial requests to applications by using the rules in each applications deployment descriptor; subsequent messages are mapped based on JSR 116 mechanisms.
   2. If any of the applications require security, the SIP container invokes any defined TAI implementations for the message.
   3. If the message passes security, the container invokes the corresponding applications.

   Your TAI implementation can modify a SIP message, but the modified message will not be usable within the request mapping process, because it finishes before the container invokes the TAI.

   For more information about how to create a TAIResult object to return from the negotiateValidateandEstablishProtocolTrust method, see Trust association interceptor support for subject creation.

   The following example shows a bare custom SIP interceptor. You can add your custom implementation to this code.

   import java.util.Properties;
   
   import javax.servlet.sip.SipServletMessage;
   import javax.servlet.sip.SipServletRequest;
   import javax.servlet.sip.SipServletResponse;
   
   import com.ibm.websphere.security.WebTrustAssociationFailedException;
   import com.ibm.websphere.security.tai.extension.SIPTrustAssociationInterceptor;
   import com.ibm.wsspi.security.tai.TAIResult;
   import com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor;
   
   
   public class mySIPTai extends BaseTrustAssociationInterceptor implements SIPTrustAssociationInterceptor {
   
       public mySIPTai () {}
   
       public int initialize(Properties properties) throws WebTrustAssociationFailedException {
           //initialize the implementation. If successful return 0, else return 1.
           return 1;
       }
   
       public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws WebTrustAssociationFailedException {
           // use information from sipMsg to determine if your custom TAI should
           // intercept the request
           // return true if this is the target interceptor, else return false.
           return false;
       }
   
       public TAIResult negotiateValidateandEstablishProtocolTrust(SipServletRequest req, SipServletResponse resp)
       throws WebTrustAssociationFailedException {
   
           //validate the request and establish trust
   
           TAIResult taiResult = null; 
   
           //create and return a TAIResult object, example:
           //taiResult = TAIResult.create(HttpServletResponse.SC_OK, userid);
   
           return taiResult;
       }
       public String getVersion() {
           //Return a version specific to your implementation
           return "1.0";
       }
       public String getType() {
           //Return a type specific to your implementation
           return "my custom SIP TAI";
       }
       public void cleanup() {
           //Cleanup code specific to your implementation
       }    
   }

3. Compile the implementation after you have implemented it.
   For example:

   /opt/WebSphere/AppServer/java/bin/javac -classpath /opt/WebSphere/AppServer/dev/was_public.jar;/opt/WebSphere/AppServer/dev/JavaEE/j2ee.jar;/opt/WebSphere/AppServer/plugins/com.ibm.ws.sip.container.jar;/opt/WebSphere/AppServer/plugins/com.ibm.ws.sip.interface.jar
   
   

   1. For each server within a cluster, copy the class file to a location in the WebSphere class path, preferably the wasHome/plugins/ directory.
   2. Restart all the servers.
4. Enable trust association.
   1. In the administrative console, click Security > Global security.
   2. Under Authentication, click Web and SIP security > Trust association.
   3. Make sure that the Enable trust association box is checked.
   4. Click Apply.
5. Optional: Delete the deprecated interceptor.
   1. Under Additional properties, click Interceptors.
   2. If the com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus interceptor is listed, select it by checking the box.
   3. Click Delete.
6. Add your custom interceptor.
   1. Click New.
   2. Enter your interceptor class name.
      Verify that the class name is dot-separated and appears in the class path.
7. Optional: Add properties that are required to initialize the custom interceptor.
   These properties are passed to the initialize(Properties) method of your interceptor when it extends the com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor class, as previously described.
8. Save the configuration and synchronize it, if applicable.
9. Restart the servers for the custom interceptor to take effect.