com.ibm.websphere.security.tai.extension

Interface SIPTrustAssociationInterceptor



  • public interface SIPTrustAssociationInterceptor
    The SIPTrustAssociationInterceptor is an interface for developing a SIP custom trust association interceptor (TAI). A custom TAI that implements this interface should also extend com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor class.

    The custom TAI must implement the following methods:

    initialize to allocate any resources needed for the TAI

    negotiateValidateandEstablishProtocolTrust that returns TAIResult to indicate the status of the message being processed

    isTargetProtocolInterceptor that returns false/true to indicate whether a SIP message will be handled by the TAI.

    The idea is during processing a SIP request, the Liberty server will pass the SipServletRequest and SipServletResponse to the SIP trust association interceptor. The trust association interceptor can inspect the SIP message to see if it contains security attributes (authentication or authorization attributes) from the third party security service.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void cleanup()
      Invoked when the TAI should free any resources it holds.
      java.lang.String getType()
      Returns a type value of the TAI.
      java.lang.String getVersion()
      Returns the version number of the current TAI implementation.
      int initialize(java.util.Properties properties)
      Initializes the SIP trust association interceptor.
      boolean isTargetProtocolInterceptor(javax.servlet.sip.SipServletMessage sipMsg)
      The custom TAI should use this method to inspect if it can process the SipServletMessage.
      com.ibm.wsspi.security.tai.TAIResult negotiateValidateandEstablishProtocolTrust(javax.servlet.sip.SipServletRequest req, javax.servlet.sip.SipServletResponse resp)
      This method is used to determine whether trust association can be established between the Liberty server and the third party security service.
    • Method Detail

      • isTargetProtocolInterceptor

        boolean isTargetProtocolInterceptor(javax.servlet.sip.SipServletMessage sipMsg)
                                            throws com.ibm.websphere.security.WebTrustAssociationFailedException
        The custom TAI should use this method to inspect if it can process the SipServletMessage. The implementation should return true if the TAI can handle the sipMsg, else false should be returned.
        Parameters:
        sipMsg - SipServletMessage to be handled by the TAI
        Returns:
        boolean true indicates that the message will be handled by the TAI, otherwise false
        Throws:
        com.ibm.websphere.security.WebTrustAssociationFailedException - exception
      • negotiateValidateandEstablishProtocolTrust

        com.ibm.wsspi.security.tai.TAIResult negotiateValidateandEstablishProtocolTrust(javax.servlet.sip.SipServletRequest req,
                                                                                      javax.servlet.sip.SipServletResponse resp)
                                                                                        throws com.ibm.websphere.security.WebTrustAssociationFailedException
        This method is used to determine whether trust association can be established between the Liberty server and the third party security service. This method returns TAIResult that indicates the status of the message being processed.

        If authentication succeeds, the TAIResult should contain the status HttpServletResponse.SC_OK and a principal.

        If the interceptor finds that the request does not contains the expected authentication data, it can write the challenge information in the SIP response and return TAIResult with status code HttpServletResponse.SC_UNAUTHORIZED (401), or SC_FORBIDDEN (403), or SC_PROXY_AUTHENTICATION_REQUIRED (407).

        Parameters:
        req - incoming SipServletRequest to be handled by the TAI
        resp - incoming SipServletResponse to be handled by the TAI
        Returns:
        TAIResult result of trust association interceptor negotiation
        Throws:
        com.ibm.websphere.security.WebTrustAssociationFailedException - exception
      • initialize

        int initialize(java.util.Properties properties)
                       throws com.ibm.websphere.security.WebTrustAssociationFailedException
        Initializes the SIP trust association interceptor. Invoked before the first message is processed so that the implementation can allocate any resources it needs. For example, it could establish a connection to a database or LDAP.
        Parameters:
        properties - Properties defined in the TAI properties
        Returns:
        int - 0 indicates success and anything else a failure
        Throws:
        com.ibm.websphere.security.WebTrustAssociationFailedException - exception
      • getVersion

        java.lang.String getVersion()
        Returns the version number of the current TAI implementation.
        Returns:
        String the version of the TAI
      • getType

        java.lang.String getType()
        Returns a type value of the TAI.
        Returns:
        String the type of the TAI
      • cleanup

        void cleanup()
        Invoked when the TAI should free any resources it holds. For example, it could close a connection to a database.