1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31 package org.apache.commons.httpclient.auth;
32
33 import org.apache.commons.httpclient.Credentials;
34 import org.apache.commons.httpclient.HttpMethod;
35
36 /***
37 * <p>
38 * This interface represents an abstract challenge-response oriented
39 * authentication scheme.
40 * </p>
41 * <p>
42 * An authentication scheme should be able to support the following
43 * functions:
44 * <ul>
45 * <li>Parse and process the challenge sent by the targer server
46 * in response to request for a protected resource
47 * <li>Provide its textual designation
48 * <li>Provide its parameters, if available
49 * <li>Provide the realm this authentication scheme is applicable to,
50 * if available
51 * <li>Generate authorization string for the given set of credentials,
52 * request method and URI as specificed in the HTTP request line
53 * in response to the actual authorization challenge
54 * </ul>
55 * </p>
56 * <p>
57 * Authentication schemes may ignore method name and URI parameters
58 * if they are not relevant for the given authentication mechanism
59 * </p>
60 * <p>
61 * Authentication schemes may be stateful involving a series of
62 * challenge-response exchanges
63 * </p>
64 *
65 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
66 * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
67 *
68 * @since 2.0beta1
69 */
70
71 public interface AuthScheme {
72
73 /***
74 * Processes the given challenge token. Some authentication schemes
75 * may involve multiple challenge-response exchanges. Such schemes must be able
76 * to maintain the state information when dealing with sequential challenges
77 *
78 * @param challenge the challenge string
79 *
80 * @since 3.0
81 */
82 void processChallenge(final String challenge) throws MalformedChallengeException;
83
84 /***
85 * Returns textual designation of the given authentication scheme.
86 *
87 * @return the name of the given authentication scheme
88 */
89 String getSchemeName();
90
91 /***
92 * Returns authentication parameter with the given name, if available.
93 *
94 * @param name The name of the parameter to be returned
95 *
96 * @return the parameter with the given name
97 */
98 String getParameter(final String name);
99
100 /***
101 * Returns authentication realm. If the concept of an authentication
102 * realm is not applicable to the given authentication scheme, returns
103 * <code>null</code>.
104 *
105 * @return the authentication realm
106 */
107 String getRealm();
108
109 /***
110 * Returns a String identifying the authentication challenge. This is
111 * used, in combination with the host and port to determine if
112 * authorization has already been attempted or not. Schemes which
113 * require multiple requests to complete the authentication should
114 * return a different value for each stage in the request.
115 *
116 * <p>Additionally, the ID should take into account any changes to the
117 * authentication challenge and return a different value when appropriate.
118 * For example when the realm changes in basic authentication it should be
119 * considered a different authentication attempt and a different value should
120 * be returned.</p>
121 *
122 * @return String a String identifying the authentication challenge. The
123 * returned value may be null.
124 *
125 * @deprecated no longer used
126 */
127 String getID();
128
129 /***
130 * Tests if the authentication scheme is provides authorization on a per
131 * connection basis instead of usual per request basis
132 *
133 * @return <tt>true</tt> if the scheme is connection based, <tt>false</tt>
134 * if the scheme is request based.
135 *
136 * @since 3.0
137 */
138 boolean isConnectionBased();
139
140 /***
141 * Authentication process may involve a series of challenge-response exchanges.
142 * This method tests if the authorization process has been completed, either
143 * successfully or unsuccessfully, that is, all the required authorization
144 * challenges have been processed in their entirety.
145 *
146 * @return <tt>true</tt> if the authentication process has been completed,
147 * <tt>false</tt> otherwise.
148 *
149 * @since 3.0
150 */
151 boolean isComplete();
152 /***
153 * @deprecated Use {@link #authenticate(Credentials, HttpMethod)}
154 *
155 * Produces an authorization string for the given set of {@link Credentials},
156 * method name and URI using the given authentication scheme in response to
157 * the actual authorization challenge.
158 *
159 * @param credentials The set of credentials to be used for athentication
160 * @param method The name of the method that requires authorization.
161 * This parameter may be ignored, if it is irrelevant
162 * or not applicable to the given authentication scheme
163 * @param uri The URI for which authorization is needed.
164 * This parameter may be ignored, if it is irrelevant or not
165 * applicable to the given authentication scheme
166 * @throws AuthenticationException if authorization string cannot
167 * be generated due to an authentication failure
168 *
169 * @return the authorization string
170 *
171 * @see org.apache.commons.httpclient.HttpMethod#getName()
172 * @see org.apache.commons.httpclient.HttpMethod#getPath()
173 */
174 String authenticate(Credentials credentials, String method, String uri)
175 throws AuthenticationException;
176
177 /***
178 * Produces an authorization string for the given set of {@link Credentials}.
179 *
180 * @param credentials The set of credentials to be used for athentication
181 * @param method The method being authenticated
182 * @throws AuthenticationException if authorization string cannot
183 * be generated due to an authentication failure
184 *
185 * @return the authorization string
186 *
187 * @since 3.0
188 */
189 String authenticate(Credentials credentials, HttpMethod method) throws AuthenticationException;
190
191 }