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