Home | History | Annotate | Download | only in clientauthutils 
      1 package gov.nist.javax.sip.clientauthutils;
      2 
      3 import java.text.ParseException;
      4 import java.util.Collection;
      5 
      6 import javax.sip.ClientTransaction;
      7 import javax.sip.InvalidArgumentException;
      8 import javax.sip.SipException;
      9 import javax.sip.SipProvider;
     10 import javax.sip.header.AuthorizationHeader;
     11 import javax.sip.message.Request;
     12 import javax.sip.message.Response;
     13 
     14 /**
     15  * A helper interface that provides useful functionality for clients that need to authenticate
     16  * with servers.
     17  *
     18  * @author Emil Ivov
     19  * @author Jeroen van Bemmel
     20  * @author M. Ranganathan
     21  *
     22  * @since 2.0
     23  *
     24  *
     25  */
     26 public interface AuthenticationHelper {
     27 
     28     /**
     29      * Uses securityAuthority to determinie a set of valid user credentials for
     30      * the specified Response (Challenge) and appends it to the challenged
     31      * request so that it could be retransmitted.
     32      *
     33      *
     34      *
     35      * @param challenge
     36      *            the 401/407 challenge response
     37      * @param challengedTransaction
     38      *            the transaction established by the challenged request
     39      * @param transactionCreator
     40      *            the JAIN SipProvider that we should use to create the new
     41      *            transaction.
     42      * @param cacheTime The amount of time (seconds ) for which the authentication helper
     43      *      will keep a reference to the generated credentials in a cache.
     44      *      If you specify -1, then the authentication credentials are cached
     45      *      until you remove them from the cache. If you choose this option, make sure
     46      *      you remove the cached headers or you will have a memory leak.
     47      *
     48      * @return a transaction containing a re-originated request with the
     49      *         necessary authorization header.
     50      * @throws SipException
     51      *             if we get an exception white creating the new transaction
     52      * @throws NullPointerException
     53      *             if an argument or a header is null.
     54      */
     55     public abstract ClientTransaction handleChallenge(Response challenge,
     56             ClientTransaction challengedTransaction,
     57             SipProvider transactionCreator, int cacheTime ) throws SipException,
     58              NullPointerException;
     59 
     60     /**
     61      * Attach authentication headers to the given request. This looks up
     62      * the credential cache and picks up any stored authentication headers
     63      * for the given call ID and attaches it to the request.
     64      * @param request - the request for which we attach the authentication headers.
     65      */
     66     public abstract void setAuthenticationHeaders(Request request) ;
     67 
     68     /**
     69      * Remove cached entry.
     70      *
     71      * @param callId -- the call Id for which we want to remove the cached headers.
     72      *
     73      */
     74     public abstract void removeCachedAuthenticationHeaders(String callId);
     75 }
     76