View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/auth/BasicScheme.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.codec.binary.Base64;
34  import org.apache.commons.httpclient.Credentials;
35  import org.apache.commons.httpclient.HttpMethod;
36  import org.apache.commons.httpclient.UsernamePasswordCredentials;
37  import org.apache.commons.httpclient.util.EncodingUtil;
38  import org.apache.commons.logging.Log;
39  import org.apache.commons.logging.LogFactory;
40  
41  /***
42   * <p>
43   * Basic authentication scheme as defined in RFC 2617.
44   * </p>
45   * 
46   * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
47   * @author Rodney Waldhoff
48   * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
49   * @author Ortwin Gl?ck
50   * @author Sean C. Sullivan
51   * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
52   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
53   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
54   */
55  
56  public class BasicScheme extends RFC2617Scheme {
57      
58      /*** Log object for this class. */
59      private static final Log LOG = LogFactory.getLog(BasicScheme.class);
60      
61      /*** Whether the basic authentication process is complete */
62      private boolean complete;
63      
64      /***
65       * Default constructor for the basic authetication scheme.
66       * 
67       * @since 3.0
68       */
69      public BasicScheme() {
70          super();
71          this.complete = false;
72      }
73  
74      /***
75       * Constructor for the basic authetication scheme.
76       * 
77       * @param challenge authentication challenge
78       * 
79       * @throws MalformedChallengeException is thrown if the authentication challenge
80       * is malformed
81       * 
82       * @deprecated Use parameterless constructor and {@link AuthScheme#processChallenge(String)} 
83       *             method
84       */
85      public BasicScheme(final String challenge) throws MalformedChallengeException {
86          super(challenge);
87          this.complete = true;
88      }
89  
90      /***
91       * Returns textual designation of the basic authentication scheme.
92       * 
93       * @return <code>basic</code>
94       */
95      public String getSchemeName() {
96          return "basic";
97      }
98  
99      /***
100      * Processes the Basic challenge.
101      *  
102      * @param challenge the challenge string
103      * 
104      * @throws MalformedChallengeException is thrown if the authentication challenge
105      * is malformed
106      * 
107      * @since 3.0
108      */
109     public void processChallenge(String challenge) 
110         throws MalformedChallengeException 
111     {
112         super.processChallenge(challenge);
113         this.complete = true;
114     }
115 
116     /***
117      * Tests if the Basic authentication process has been completed.
118      * 
119      * @return <tt>true</tt> if Basic authorization has been processed,
120      *   <tt>false</tt> otherwise.
121      * 
122      * @since 3.0
123      */
124     public boolean isComplete() {
125         return this.complete;
126     }
127 
128     /***
129      * Produces basic authorization string for the given set of 
130      * {@link Credentials}.
131      * 
132      * @param credentials The set of credentials to be used for athentication
133      * @param method Method name is ignored by the basic authentication scheme
134      * @param uri URI is ignored by the basic authentication scheme
135      * @throws InvalidCredentialsException if authentication credentials
136      *         are not valid or not applicable for this authentication scheme
137      * @throws AuthenticationException if authorization string cannot 
138      *   be generated due to an authentication failure
139      * 
140      * @return a basic authorization string
141      * 
142      * @deprecated Use {@link #authenticate(Credentials, HttpMethod)}
143      */
144     public String authenticate(Credentials credentials, String method, String uri)
145       throws AuthenticationException {
146 
147         LOG.trace("enter BasicScheme.authenticate(Credentials, String, String)");
148 
149         UsernamePasswordCredentials usernamepassword = null;
150         try {
151             usernamepassword = (UsernamePasswordCredentials) credentials;
152         } catch (ClassCastException e) {
153             throw new InvalidCredentialsException(
154              "Credentials cannot be used for basic authentication: " 
155               + credentials.getClass().getName());
156         }
157         return BasicScheme.authenticate(usernamepassword);
158     }
159 
160     /***
161      * Returns <tt>false</tt>. Basic authentication scheme is request based.
162      * 
163      * @return <tt>false</tt>.
164      * 
165      * @since 3.0
166      */
167     public boolean isConnectionBased() {
168         return false;    
169     }
170 
171     /***
172      * Produces basic authorization string for the given set of {@link Credentials}.
173      * 
174      * @param credentials The set of credentials to be used for athentication
175      * @param method The method being authenticated
176      * @throws InvalidCredentialsException if authentication credentials
177      *         are not valid or not applicable for this authentication scheme
178      * @throws AuthenticationException if authorization string cannot 
179      *   be generated due to an authentication failure
180      * 
181      * @return a basic authorization string
182      * 
183      * @since 3.0
184      */
185     public String authenticate(Credentials credentials, HttpMethod method) throws AuthenticationException {
186 
187         LOG.trace("enter BasicScheme.authenticate(Credentials, HttpMethod)");
188 
189         if (method == null) {
190             throw new IllegalArgumentException("Method may not be null");
191         }
192         UsernamePasswordCredentials usernamepassword = null;
193         try {
194             usernamepassword = (UsernamePasswordCredentials) credentials;
195         } catch (ClassCastException e) {
196             throw new InvalidCredentialsException(
197                     "Credentials cannot be used for basic authentication: " 
198                     + credentials.getClass().getName());
199         }
200         return BasicScheme.authenticate(
201             usernamepassword, 
202             method.getParams().getCredentialCharset());
203     }
204     
205     /***
206      * @deprecated Use {@link #authenticate(UsernamePasswordCredentials, String)}
207      * 
208      * Returns a basic <tt>Authorization</tt> header value for the given 
209      * {@link UsernamePasswordCredentials}.
210      * 
211      * @param credentials The credentials to encode.
212      * 
213      * @return a basic authorization string
214      */
215     public static String authenticate(UsernamePasswordCredentials credentials) {
216         return authenticate(credentials, "ISO-8859-1");
217     }
218 
219     /***
220      * Returns a basic <tt>Authorization</tt> header value for the given 
221      * {@link UsernamePasswordCredentials} and charset.
222      * 
223      * @param credentials The credentials to encode.
224      * @param charset The charset to use for encoding the credentials
225      * 
226      * @return a basic authorization string
227      * 
228      * @since 3.0
229      */
230     public static String authenticate(UsernamePasswordCredentials credentials, String charset) {
231 
232         LOG.trace("enter BasicScheme.authenticate(UsernamePasswordCredentials, String)");
233 
234         if (credentials == null) {
235             throw new IllegalArgumentException("Credentials may not be null"); 
236         }
237         if (charset == null || charset.length() == 0) {
238             throw new IllegalArgumentException("charset may not be null or empty");
239         }
240         StringBuffer buffer = new StringBuffer();
241         buffer.append(credentials.getUserName());
242         buffer.append(":");
243         buffer.append(credentials.getPassword());
244         
245         return "Basic " + EncodingUtil.getAsciiString(
246                 Base64.encodeBase64(EncodingUtil.getBytes(buffer.toString(), charset)));
247     }
248     
249 }