View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/auth/AuthScheme.java $
3    * $Revision$
4    * $Date$
5    *
6    * ====================================================================
7    *
8    *  Licensed to the Apache Software Foundation (ASF) under one or more
9    *  contributor license agreements.  See the NOTICE file distributed with
10   *  this work for additional information regarding copyright ownership.
11   *  The ASF licenses this file to You under the Apache License, Version 2.0
12   *  (the "License"); you may not use this file except in compliance with
13   *  the License.  You may obtain a copy of the License at
14   *
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   *
17   *  Unless required by applicable law or agreed to in writing, software
18   *  distributed under the License is distributed on an "AS IS" BASIS,
19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   *  See the License for the specific language governing permissions and
21   *  limitations under the License.
22   * ====================================================================
23   *
24   * This software consists of voluntary contributions made by many
25   * individuals on behalf of the Apache Software Foundation.  For more
26   * information on the Apache Software Foundation, please see
27   * <http://www.apache.org/>.
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 }