001: /*
002: * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/auth/AuthScheme.java,v 1.12 2004/05/13 04:02:00 mbecke Exp $
003: * $Revision: 480424 $
004: * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient.auth;
032:
033: import org.apache.commons.httpclient.Credentials;
034: import org.apache.commons.httpclient.HttpMethod;
035:
036: /**
037: * <p>
038: * This interface represents an abstract challenge-response oriented
039: * authentication scheme.
040: * </p>
041: * <p>
042: * An authentication scheme should be able to support the following
043: * functions:
044: * <ul>
045: * <li>Parse and process the challenge sent by the targer server
046: * in response to request for a protected resource
047: * <li>Provide its textual designation
048: * <li>Provide its parameters, if available
049: * <li>Provide the realm this authentication scheme is applicable to,
050: * if available
051: * <li>Generate authorization string for the given set of credentials,
052: * request method and URI as specificed in the HTTP request line
053: * in response to the actual authorization challenge
054: * </ul>
055: * </p>
056: * <p>
057: * Authentication schemes may ignore method name and URI parameters
058: * if they are not relevant for the given authentication mechanism
059: * </p>
060: * <p>
061: * Authentication schemes may be stateful involving a series of
062: * challenge-response exchanges
063: * </p>
064: *
065: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
066: * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
067: *
068: * @since 2.0beta1
069: */
070:
071: public interface AuthScheme {
072:
073: /**
074: * Processes the given challenge token. Some authentication schemes
075: * may involve multiple challenge-response exchanges. Such schemes must be able
076: * to maintain the state information when dealing with sequential challenges
077: *
078: * @param challenge the challenge string
079: *
080: * @since 3.0
081: */
082: void processChallenge(final String challenge)
083: throws MalformedChallengeException;
084:
085: /**
086: * Returns textual designation of the given authentication scheme.
087: *
088: * @return the name of the given authentication scheme
089: */
090: String getSchemeName();
091:
092: /**
093: * Returns authentication parameter with the given name, if available.
094: *
095: * @param name The name of the parameter to be returned
096: *
097: * @return the parameter with the given name
098: */
099: String getParameter(final String name);
100:
101: /**
102: * Returns authentication realm. If the concept of an authentication
103: * realm is not applicable to the given authentication scheme, returns
104: * <code>null</code>.
105: *
106: * @return the authentication realm
107: */
108: String getRealm();
109:
110: /**
111: * Returns a String identifying the authentication challenge. This is
112: * used, in combination with the host and port to determine if
113: * authorization has already been attempted or not. Schemes which
114: * require multiple requests to complete the authentication should
115: * return a different value for each stage in the request.
116: *
117: * <p>Additionally, the ID should take into account any changes to the
118: * authentication challenge and return a different value when appropriate.
119: * For example when the realm changes in basic authentication it should be
120: * considered a different authentication attempt and a different value should
121: * be returned.</p>
122: *
123: * @return String a String identifying the authentication challenge. The
124: * returned value may be null.
125: *
126: * @deprecated no longer used
127: */
128: String getID();
129:
130: /**
131: * Tests if the authentication scheme is provides authorization on a per
132: * connection basis instead of usual per request basis
133: *
134: * @return <tt>true</tt> if the scheme is connection based, <tt>false</tt>
135: * if the scheme is request based.
136: *
137: * @since 3.0
138: */
139: boolean isConnectionBased();
140:
141: /**
142: * Authentication process may involve a series of challenge-response exchanges.
143: * This method tests if the authorization process has been completed, either
144: * successfully or unsuccessfully, that is, all the required authorization
145: * challenges have been processed in their entirety.
146: *
147: * @return <tt>true</tt> if the authentication process has been completed,
148: * <tt>false</tt> otherwise.
149: *
150: * @since 3.0
151: */
152: boolean isComplete();
153:
154: /**
155: * @deprecated Use {@link #authenticate(Credentials, HttpMethod)}
156: *
157: * Produces an authorization string for the given set of {@link Credentials},
158: * method name and URI using the given authentication scheme in response to
159: * the actual authorization challenge.
160: *
161: * @param credentials The set of credentials to be used for athentication
162: * @param method The name of the method that requires authorization.
163: * This parameter may be ignored, if it is irrelevant
164: * or not applicable to the given authentication scheme
165: * @param uri The URI for which authorization is needed.
166: * This parameter may be ignored, if it is irrelevant or not
167: * applicable to the given authentication scheme
168: * @throws AuthenticationException if authorization string cannot
169: * be generated due to an authentication failure
170: *
171: * @return the authorization string
172: *
173: * @see org.apache.commons.httpclient.HttpMethod#getName()
174: * @see org.apache.commons.httpclient.HttpMethod#getPath()
175: */
176: String authenticate(Credentials credentials, String method,
177: String uri) throws AuthenticationException;
178:
179: /**
180: * Produces an authorization string for the given set of {@link Credentials}.
181: *
182: * @param credentials The set of credentials to be used for athentication
183: * @param method The method being authenticated
184: * @throws AuthenticationException if authorization string cannot
185: * be generated due to an authentication failure
186: *
187: * @return the authorization string
188: *
189: * @since 3.0
190: */
191: String authenticate(Credentials credentials, HttpMethod method)
192: throws AuthenticationException;
193:
194: }
|