AuthenticationHelper.java revision 600c7a4bbc7348167293eac928192e695b4ad5ba 
1package gov.nist.javax.sip.clientauthutils;
2
3import java.text.ParseException;
4import java.util.Collection;
5
6import javax.sip.ClientTransaction;
7import javax.sip.InvalidArgumentException;
8import javax.sip.SipException;
9import javax.sip.SipProvider;
10import javax.sip.header.AuthorizationHeader;
11import javax.sip.message.Request;
12import 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 */
26public 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