1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27 package org.apache.http.auth;
28
29 import org.apache.http.Header;
30 import org.apache.http.HttpRequest;
31
32 /**
33 * This interface represents an abstract challenge-response oriented
34 * authentication scheme.
35 * <p>
36 * An authentication scheme should be able to support the following
37 * functions:
38 * <ul>
39 * <li>Parse and process the challenge sent by the target server
40 * in response to request for a protected resource
41 * <li>Provide its textual designation
42 * <li>Provide its parameters, if available
43 * <li>Provide the realm this authentication scheme is applicable to,
44 * if available
45 * <li>Generate authorization string for the given set of credentials
46 * and the HTTP request in response to the authorization challenge.
47 * </ul>
48 * <p>
49 * Authentication schemes may be stateful involving a series of
50 * challenge-response exchanges.
51 * <p>
52 * IMPORTANT: implementations of this interface MUST also implement {@link ContextAwareAuthScheme}
53 * interface in order to remain API compatible with newer versions of HttpClient.
54 *
55 * @since 4.0
56 */
57
58 public interface AuthScheme {
59
60 /**
61 * Processes the given challenge token. Some authentication schemes
62 * may involve multiple challenge-response exchanges. Such schemes must be able
63 * to maintain the state information when dealing with sequential challenges
64 *
65 * @param header the challenge header
66 */
67 void processChallenge(final Header header) throws MalformedChallengeException;
68
69 /**
70 * Returns textual designation of the given authentication scheme.
71 *
72 * @return the name of the given authentication scheme
73 */
74 String getSchemeName();
75
76 /**
77 * Returns authentication parameter with the given name, if available.
78 *
79 * @param name The name of the parameter to be returned
80 *
81 * @return the parameter with the given name
82 */
83 String getParameter(final String name);
84
85 /**
86 * Returns authentication realm. If the concept of an authentication
87 * realm is not applicable to the given authentication scheme, returns
88 * {@code null}.
89 *
90 * @return the authentication realm
91 */
92 String getRealm();
93
94 /**
95 * Tests if the authentication scheme is provides authorization on a per
96 * connection basis instead of usual per request basis
97 *
98 * @return {@code true} if the scheme is connection based, {@code false}
99 * if the scheme is request based.
100 */
101 boolean isConnectionBased();
102
103 /**
104 * Authentication process may involve a series of challenge-response exchanges.
105 * This method tests if the authorization process has been completed, either
106 * successfully or unsuccessfully, that is, all the required authorization
107 * challenges have been processed in their entirety.
108 *
109 * @return {@code true} if the authentication process has been completed,
110 * {@code false} otherwise.
111 */
112 boolean isComplete();
113
114 /**
115 * Produces an authorization string for the given set of {@link Credentials}.
116 *
117 * @param credentials The set of credentials to be used for athentication
118 * @param request The request being authenticated
119 * @throws AuthenticationException if authorization string cannot
120 * be generated due to an authentication failure
121 *
122 * @return the authorization string
123 *
124 * @deprecated (4.1) Use {@link ContextAwareAuthScheme#authenticate(Credentials, HttpRequest, org.apache.http.protocol.HttpContext)}
125 */
126 @Deprecated
127 Header authenticate(Credentials credentials, HttpRequest request)
128 throws AuthenticationException;
129
130 }