001: /*
002: * @(#)Authenticator.java 1.28 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.net;
029:
030: /**
031: * The class Authenticator represents an object that knows how to obtain
032: * authentication for a network connection. Usually, it will do this
033: * by prompting the user for information.
034: * <p>
035: * Applications use this class by creating a subclass, and registering
036: * an instance of that subclass with the system with setDefault().
037: * When authentication is required, the system will invoke a method
038: * on the subclass (like getPasswordAuthentication). The subclass's
039: * method can query about the authentication being requested with a
040: * number of inherited methods (getRequestingXXX()), and form an
041: * appropriate message for the user.
042: * <p>
043: * All methods that request authentication have a default implementation
044: * that fails.
045: *
046: * @see java.net.Authenticator#setDefault(java.net.Authenticator)
047: * @see java.net.Authenticator#getPasswordAuthentication()
048: *
049: * @version 1.20, 02/02/00
050: * @since 1.2
051: */
052:
053: // There are no abstract methods, but to be useful the user must
054: // subclass.
055: public abstract class Authenticator {
056:
057: // The system-wide authenticator object. See setDefault().
058: private static Authenticator theAuthenticator;
059:
060: private String requestingHost;
061: private InetAddress requestingSite;
062: private int requestingPort;
063: private String requestingProtocol;
064: private String requestingPrompt;
065: private String requestingScheme;
066:
067: private void reset() {
068: requestingHost = null;
069: requestingSite = null;
070: requestingPort = -1;
071: requestingProtocol = null;
072: requestingPrompt = null;
073: requestingScheme = null;
074: }
075:
076: /**
077: * Sets the authenticator that will be used by the networking code
078: * when a proxy or an HTTP server asks for authentication.
079: * <p>
080: * First, if there is a security manager, its <code>checkPermission</code>
081: * method is called with a
082: * <code>NetPermission("setDefaultAuthenticator")</code> permission.
083: * This may result in a java.lang.SecurityException.
084: *
085: * @param a The authenticator to be set. If a is <code>null</code> then
086: * any previously set authenticator is removed.
087: *
088: * @throws SecurityException
089: * if a security manager exists and its
090: * <code>checkPermission</code> method doesn't allow
091: * setting the default authenticator.
092: *
093: * @see SecurityManager#checkPermission
094: * @see java.net.NetPermission
095: */
096: public synchronized static void setDefault(Authenticator a) {
097: SecurityManager sm = System.getSecurityManager();
098: if (sm != null) {
099: NetPermission setDefaultPermission = new NetPermission(
100: "setDefaultAuthenticator");
101: sm.checkPermission(setDefaultPermission);
102: }
103:
104: theAuthenticator = a;
105: }
106:
107: /**
108: * Ask the authenticator that has been registered with the system
109: * for a password.
110: * <p>
111: * First, if there is a security manager, its <code>checkPermission</code>
112: * method is called with a
113: * <code>NetPermission("requestPasswordAuthentication")</code> permission.
114: * This may result in a java.lang.SecurityException.
115: *
116: * @param addr The InetAddress of the site requesting authorization,
117: * or null if not known.
118: * @param port the port for the requested connection
119: * @param protocol The protocol that's requesting the connection
120: * ({@link java.net.Authenticator#getRequestingProtocol()})
121: * @param prompt A prompt string for the user
122: * @param scheme The authentication scheme
123: *
124: * @return The username/password, or null if one can't be gotten.
125: *
126: * @throws SecurityException
127: * if a security manager exists and its
128: * <code>checkPermission</code> method doesn't allow
129: * the password authentication request.
130: *
131: * @see SecurityManager#checkPermission
132: * @see java.net.NetPermission
133: */
134: public static PasswordAuthentication requestPasswordAuthentication(
135: InetAddress addr, int port, String protocol, String prompt,
136: String scheme) {
137:
138: SecurityManager sm = System.getSecurityManager();
139: if (sm != null) {
140: NetPermission requestPermission = new NetPermission(
141: "requestPasswordAuthentication");
142: sm.checkPermission(requestPermission);
143: }
144:
145: Authenticator a = theAuthenticator;
146: if (a == null) {
147: return null;
148: } else {
149: synchronized (a) {
150: a.reset();
151: a.requestingSite = addr;
152: a.requestingPort = port;
153: a.requestingProtocol = protocol;
154: a.requestingPrompt = prompt;
155: a.requestingScheme = scheme;
156: return a.getPasswordAuthentication();
157: }
158: }
159: }
160:
161: /**
162: * Ask the authenticator that has been registered with the system
163: * for a password. This is the preferred method for requesting a password
164: * because the hostname can be provided in cases where the InetAddress
165: * is not available.
166: * <p>
167: * First, if there is a security manager, its <code>checkPermission</code>
168: * method is called with a
169: * <code>NetPermission("requestPasswordAuthentication")</code> permission.
170: * This may result in a java.lang.SecurityException.
171: *
172: * @param host The hostname of the site requesting authentication.
173: * @param addr The InetAddress of the site requesting authentication,
174: * or null if not known.
175: * @param port the port for the requested connection.
176: * @param protocol The protocol that's requesting the connection
177: * ({@link java.net.Authenticator#getRequestingProtocol()})
178: * @param prompt A prompt string for the user which identifies the authentication realm.
179: * @param scheme The authentication scheme
180: *
181: * @return The username/password, or null if one can't be gotten.
182: *
183: * @throws SecurityException
184: * if a security manager exists and its
185: * <code>checkPermission</code> method doesn't allow
186: * the password authentication request.
187: *
188: * @see SecurityManager#checkPermission
189: * @see java.net.NetPermission
190: * @since 1.4
191: */
192: public static PasswordAuthentication requestPasswordAuthentication(
193: String host, InetAddress addr, int port, String protocol,
194: String prompt, String scheme) {
195:
196: SecurityManager sm = System.getSecurityManager();
197: if (sm != null) {
198: NetPermission requestPermission = new NetPermission(
199: "requestPasswordAuthentication");
200: sm.checkPermission(requestPermission);
201: }
202:
203: Authenticator a = theAuthenticator;
204: if (a == null) {
205: return null;
206: } else {
207: synchronized (a) {
208: a.reset();
209: a.requestingHost = host;
210: a.requestingSite = addr;
211: a.requestingPort = port;
212: a.requestingProtocol = protocol;
213: a.requestingPrompt = prompt;
214: a.requestingScheme = scheme;
215: return a.getPasswordAuthentication();
216: }
217: }
218: }
219:
220: /**
221: * Gets the <code>hostname</code> of the
222: * site or proxy requesting authentication, or <code>null</code>
223: * if not available.
224: *
225: * @return the hostname of the connection requiring authentication, or null
226: * if it's not available.
227: * @since 1.4
228: */
229: protected final String getRequestingHost() {
230: return requestingHost;
231: }
232:
233: /**
234: * Gets the <code>InetAddress</code> of the
235: * site requesting authorization, or <code>null</code>
236: * if not available.
237: *
238: * @return the InetAddress of the site requesting authorization, or null
239: * if it's not available.
240: */
241: protected final InetAddress getRequestingSite() {
242: return requestingSite;
243: }
244:
245: /**
246: * Gets the port number for the requested connection.
247: * @return an <code>int</code> indicating the
248: * port for the requested connection.
249: */
250: protected final int getRequestingPort() {
251: return requestingPort;
252: }
253:
254: /**
255: * Give the protocol that's requesting the connection. Often this
256: * will be based on a URL, but in a future SDK it could be, for
257: * example, "SOCKS" for a password-protected SOCKS5 firewall.
258: *
259: * @return the protcol, optionally followed by "/version", where
260: * version is a version number.
261: *
262: * @see java.net.URL#getProtocol()
263: */
264: protected final String getRequestingProtocol() {
265: return requestingProtocol;
266: }
267:
268: /**
269: * Gets the prompt string given by the requestor.
270: *
271: * @return the prompt string given by the requestor (realm for
272: * http requests)
273: */
274: protected final String getRequestingPrompt() {
275: return requestingPrompt;
276: }
277:
278: /**
279: * Gets the scheme of the requestor (the HTTP scheme
280: * for an HTTP firewall, for example).
281: *
282: * @return the scheme of the requestor
283: *
284: */
285: protected final String getRequestingScheme() {
286: return requestingScheme;
287: }
288:
289: /**
290: * Called when password authorization is needed. Subclasses should
291: * override the default implementation, which returns null.
292: * @return The PasswordAuthentication collected from the
293: * user, or null if none is provided.
294: */
295: protected PasswordAuthentication getPasswordAuthentication() {
296: return null;
297: }
298:
299: }
|