Authenticator


1   /*
2    * @(#)Authenticator.java   1.33 05/11/17
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.net;
9   
10  /**
11   * The class Authenticator represents an object that knows how to obtain
12   * authentication for a network connection.  Usually, it will do this
13   * by prompting the user for information.
14   * <p>
15   * Applications use this class by overriding {@link 
16   * #getPasswordAuthentication()} in a sub-class. This method will
17   * typically use the various getXXX() accessor methods to get information
18   * about the entity requesting authentication. It must then acquire a 
19   * username and password either by interacting with the user or through
20   * some other non-interactive means. The credentials are then returned
21   * as a {@link PasswordAuthentication} return value.
22   * <p>
23   * An instance of this concrete sub-class is then registered
24   * with the system by calling {@link #setDefault(Authenticator)}.
25   * When authentication is required, the system will invoke one of the
26   * requestPasswordAuthentication() methods which in turn will call the
27   * getPasswordAuthentication() method of the registered object. 
28   * <p>
29   * All methods that request authentication have a default implementation
30   * that fails.
31   *
32   * @see java.net.Authenticator#setDefault(java.net.Authenticator)
33   * @see java.net.Authenticator#getPasswordAuthentication()
34   *
35   * @author  Bill Foote
36   * @version 1.33, 11/17/05
37   * @since   1.2
38   */
39  
40  // There are no abstract methods, but to be useful the user must
41  // subclass.
42  public abstract 
43  class Authenticator {
44  
45      // The system-wide authenticator object.  See setDefault().
46      private static Authenticator   theAuthenticator;
47  
48      private String   requestingHost;
49      private InetAddress   requestingSite;
50      private int requestingPort;
51      private String   requestingProtocol;
52      private String   requestingPrompt;
53      private String   requestingScheme;
54      private URL   requestingURL;
55      private RequestorType requestingAuthType;
56  
57      /**
58       * The type of the entity requesting authentication.
59       *
60       * @since 1.5
61       */
62      public enum RequestorType {
63      /**
64       * Entity requesting authentication is a HTTP proxy server.
65       */
66      PROXY,
67      /**
68       * Entity requesting authentication is a HTTP origin server.
69       */
70      SERVER
71      }
72  
73      private void reset() {
74      requestingHost = null;
75      requestingSite = null;
76      requestingPort = -1;
77      requestingProtocol = null;
78      requestingPrompt = null;
79      requestingScheme = null;
80      requestingURL = null;
81      requestingAuthType = RequestorType.SERVER;
82      }
83  
84  
85      /**
86       * Sets the authenticator that will be used by the networking code
87       * when a proxy or an HTTP server asks for authentication.
88       * <p>
89       * First, if there is a security manager, its <code>checkPermission</code> 
90       * method is called with a 
91       * <code>NetPermission("setDefaultAuthenticator")</code> permission.
92       * This may result in a java.lang.SecurityException. 
93       *
94       * @param   a   The authenticator to be set. If a is <code>null</code> then
95       *          any previously set authenticator is removed.
96       *
97       * @throws SecurityException
98       *        if a security manager exists and its 
99       *        <code>checkPermission</code> method doesn't allow 
100      *        setting the default authenticator.
101      *
102      * @see SecurityManager#checkPermission
103      * @see java.net.NetPermission
104      */
105     public synchronized static void setDefault(Authenticator   a) {
106     SecurityManager   sm = System.getSecurityManager();
107     if (sm != null) {
108         NetPermission   setDefaultPermission
109         = new NetPermission  ("setDefaultAuthenticator");
110         sm.checkPermission(setDefaultPermission);
111     }
112 
113     theAuthenticator = a;
114     }
115 
116     /**
117      * Ask the authenticator that has been registered with the system
118      * for a password.
119      * <p>
120      * First, if there is a security manager, its <code>checkPermission</code> 
121      * method is called with a 
122      * <code>NetPermission("requestPasswordAuthentication")</code> permission.
123      * This may result in a java.lang.SecurityException. 
124      *
125      * @param addr The InetAddress of the site requesting authorization,
126      *             or null if not known.
127      * @param port the port for the requested connection
128      * @param protocol The protocol that's requesting the connection
129      *          ({@link java.net.Authenticator#getRequestingProtocol()})
130      * @param prompt A prompt string for the user
131      * @param scheme The authentication scheme
132      *
133      * @return The username/password, or null if one can't be gotten.
134      *
135      * @throws SecurityException
136      *        if a security manager exists and its 
137      *        <code>checkPermission</code> method doesn't allow 
138      *        the password authentication request.
139      *
140      * @see SecurityManager#checkPermission
141      * @see java.net.NetPermission
142      */
143     public static PasswordAuthentication   requestPasswordAuthentication(
144                         InetAddress   addr,
145                         int port,
146                         String   protocol,
147                         String   prompt,
148                         String   scheme) {
149 
150     SecurityManager   sm = System.getSecurityManager();
151     if (sm != null) {
152         NetPermission   requestPermission
153         = new NetPermission  ("requestPasswordAuthentication");
154         sm.checkPermission(requestPermission);
155     }
156 
157     Authenticator   a = theAuthenticator;
158     if (a == null) {
159         return null;
160     } else {
161         synchronized(a) {
162         a.reset();
163         a.requestingSite = addr;
164         a.requestingPort = port;
165         a.requestingProtocol = protocol;
166         a.requestingPrompt = prompt;
167         a.requestingScheme = scheme;
168         return a.getPasswordAuthentication();
169         }
170     }
171     }
172 
173     /**
174      * Ask the authenticator that has been registered with the system
175      * for a password. This is the preferred method for requesting a password
176      * because the hostname can be provided in cases where the InetAddress
177      * is not available.
178      * <p>
179      * First, if there is a security manager, its <code>checkPermission</code> 
180      * method is called with a 
181      * <code>NetPermission("requestPasswordAuthentication")</code> permission.
182      * This may result in a java.lang.SecurityException. 
183      *
184      * @param host The hostname of the site requesting authentication.
185      * @param addr The InetAddress of the site requesting authentication,
186      *             or null if not known. 
187      * @param port the port for the requested connection.
188      * @param protocol The protocol that's requesting the connection
189      *          ({@link java.net.Authenticator#getRequestingProtocol()})
190      * @param prompt A prompt string for the user which identifies the authentication realm.
191      * @param scheme The authentication scheme
192      *
193      * @return The username/password, or null if one can't be gotten.
194      *
195      * @throws SecurityException
196      *        if a security manager exists and its 
197      *        <code>checkPermission</code> method doesn't allow 
198      *        the password authentication request.
199      *
200      * @see SecurityManager#checkPermission
201      * @see java.net.NetPermission
202      * @since 1.4
203      */
204     public static PasswordAuthentication   requestPasswordAuthentication(
205                         String   host,
206                         InetAddress   addr,
207                         int port,
208                         String   protocol,
209                         String   prompt,
210                         String   scheme) {
211 
212     SecurityManager   sm = System.getSecurityManager();
213     if (sm != null) {
214         NetPermission   requestPermission
215         = new NetPermission  ("requestPasswordAuthentication");
216         sm.checkPermission(requestPermission);
217     }
218 
219     Authenticator   a = theAuthenticator;
220     if (a == null) {
221         return null;
222     } else {
223         synchronized(a) {
224         a.reset();
225         a.requestingHost = host;
226         a.requestingSite = addr;
227         a.requestingPort = port;
228         a.requestingProtocol = protocol;
229         a.requestingPrompt = prompt;
230         a.requestingScheme = scheme;
231         return a.getPasswordAuthentication();
232         }
233     }
234     }
235 
236     /**
237      * Ask the authenticator that has been registered with the system
238      * for a password.
239      * <p>
240      * First, if there is a security manager, its <code>checkPermission</code> 
241      * method is called with a 
242      * <code>NetPermission("requestPasswordAuthentication")</code> permission.
243      * This may result in a java.lang.SecurityException. 
244      *
245      * @param host The hostname of the site requesting authentication.
246      * @param addr The InetAddress of the site requesting authorization,
247      *             or null if not known.
248      * @param port the port for the requested connection
249      * @param protocol The protocol that's requesting the connection
250      *          ({@link java.net.Authenticator#getRequestingProtocol()})
251      * @param prompt A prompt string for the user
252      * @param scheme The authentication scheme
253      * @param url The requesting URL that caused the authentication
254      * @param reqType The type (server or proxy) of the entity requesting
255      *          authentication.
256      *
257      * @return The username/password, or null if one can't be gotten.
258      *
259      * @throws SecurityException
260      *        if a security manager exists and its 
261      *        <code>checkPermission</code> method doesn't allow 
262      *        the password authentication request.
263      *
264      * @see SecurityManager#checkPermission
265      * @see java.net.NetPermission
266      *
267      * @since 1.5
268      */
269     public static PasswordAuthentication   requestPasswordAuthentication(
270                     String   host,
271                     InetAddress   addr,
272                     int port,
273                     String   protocol,
274                     String   prompt,
275                     String   scheme,
276                     URL   url,
277                     RequestorType reqType) {
278 
279     SecurityManager   sm = System.getSecurityManager();
280     if (sm != null) {
281         NetPermission   requestPermission
282         = new NetPermission  ("requestPasswordAuthentication");
283         sm.checkPermission(requestPermission);
284     }
285 
286     Authenticator   a = theAuthenticator;
287     if (a == null) {
288         return null;
289     } else {
290         synchronized(a) {
291         a.reset();
292         a.requestingHost = host;
293         a.requestingSite = addr;
294         a.requestingPort = port;
295         a.requestingProtocol = protocol;
296         a.requestingPrompt = prompt;
297         a.requestingScheme = scheme;
298         a.requestingURL = url;
299         a.requestingAuthType = reqType;
300         return a.getPasswordAuthentication();
301         }
302     }
303     }
304 
305     /**
306      * Gets the <code>hostname</code> of the
307      * site or proxy requesting authentication, or <code>null</code>
308      * if not available.
309      * 
310      * @return the hostname of the connection requiring authentication, or null
311      *      if it's not available.
312      * @since 1.4
313      */
314     protected final String   getRequestingHost() {
315     return requestingHost;
316     }
317 
318     /**
319      * Gets the <code>InetAddress</code> of the
320      * site requesting authorization, or <code>null</code>
321      * if not available.
322      * 
323      * @return the InetAddress of the site requesting authorization, or null
324      *      if it's not available.
325      */
326     protected final InetAddress   getRequestingSite() {
327     return requestingSite;
328     }
329 
330     /**
331      * Gets the port number for the requested connection.
332      * @return an <code>int</code> indicating the 
333      * port for the requested connection.
334      */
335     protected final int getRequestingPort() {
336     return requestingPort;
337     }
338 
339     /**
340      * Give the protocol that's requesting the connection.  Often this
341      * will be based on a URL, but in a future JDK it could be, for
342      * example, "SOCKS" for a password-protected SOCKS5 firewall.
343      *
344      * @return the protcol, optionally followed by "/version", where
345      *      version is a version number.
346      *
347      * @see java.net.URL#getProtocol()
348      */
349     protected final String   getRequestingProtocol() {
350     return requestingProtocol;
351     }
352 
353     /**
354      * Gets the prompt string given by the requestor.
355      *
356      * @return the prompt string given by the requestor (realm for
357      *      http requests)
358      */
359     protected final String   getRequestingPrompt() {
360     return requestingPrompt;
361     }
362 
363     /**
364      * Gets the scheme of the requestor (the HTTP scheme
365      * for an HTTP firewall, for example).
366      *
367      * @return the scheme of the requestor
368      *        
369      */
370     protected final String   getRequestingScheme() {
371     return requestingScheme;
372     }
373 
374     /**
375      * Called when password authorization is needed.  Subclasses should
376      * override the default implementation, which returns null.
377      * @return The PasswordAuthentication collected from the
378      *      user, or null if none is provided.
379      */
380     protected PasswordAuthentication   getPasswordAuthentication() {
381     return null;
382     }
383 
384     /**
385      * Returns the URL that resulted in this
386      * request for authentication.
387      *
388      * @since 1.5
389      *
390      * @return the requesting URL
391      *        
392      */
393     protected URL   getRequestingURL () {
394     return requestingURL;
395     }
396 
397     /**
398      * Returns whether the requestor is a Proxy or a Server.
399      *
400      * @since 1.5
401      *
402      * @return the authentication type of the requestor
403      *        
404      */
405     protected RequestorType getRequestorType () {
406     return requestingAuthType;
407     }
408 }
409 
410 
411 
412 
413 
414 
415
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags