1: /* Authenticator.java -- Abstract class for obtaining authentication info 2: Copyright (C) 1998, 2000, 2003 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.net; 39: 40: 41: /** 42: * This abstract class provides a model for obtaining authentication 43: * information (in the form of a username and password) required by 44: * some network operations (such as hitting a password protected 45: * web site). 46: * <p> 47: * To make use of this feature, a programmer must create a subclass 48: * that knows how to obtain the necessary info. An example 49: * would be a class that popped up a dialog box to prompt the user. 50: * After creating an instance of that subclass, the static 51: * <code>setDefault</code> method of this class is called to set up 52: * that instance as the object to use on subsequent calls to obtain 53: * authorization. 54: * 55: * @since 1.2 56: * 57: * @author Aaron M. Renn (arenn@urbanophile.com) 58: * @status Believed to be JDK 1.4 complete 59: */ 60: public abstract class Authenticator 61: { 62: /* 63: * Class Variables 64: */ 65: 66: /** 67: * This is the default Authenticator object to use for password requests 68: */ 69: private static Authenticator defaultAuthenticator; 70: 71: /* 72: * Instance Variables 73: */ 74: 75: /** 76: * The hostname of the site requesting authentication 77: */ 78: private String host; 79: 80: /** 81: * InternetAddress of the site requesting authentication 82: */ 83: private InetAddress addr; 84: 85: /** 86: * The port number of the site requesting authentication 87: */ 88: private int port; 89: 90: /** 91: * The protocol name of the site requesting authentication 92: */ 93: private String protocol; 94: 95: /** 96: * The prompt to display to the user when requesting authentication info 97: */ 98: private String prompt; 99: 100: /** 101: * The authentication scheme in use 102: */ 103: private String scheme; 104: 105: /* 106: * Class Methods 107: */ 108: 109: /** 110: * This method sets the default <code>Authenticator</code> object (an 111: * instance of a subclass of <code>Authenticator</code>) to use when 112: * prompting the user for 113: * information. Note that this method checks to see if the caller is 114: * allowed to set this value (the "setDefaultAuthenticator" permission) 115: * and throws a <code>SecurityException</code> if it is not. 116: * 117: * @param defAuth The new default <code>Authenticator</code> object to use 118: * 119: * @exception SecurityException If the caller does not have permission 120: * to perform this operation 121: */ 122: public static void setDefault(Authenticator defAuth) 123: { 124: SecurityManager sm = System.getSecurityManager(); 125: if (sm != null) 126: sm.checkPermission(new NetPermission("setDefaultAuthenticator")); 127: 128: defaultAuthenticator = defAuth; 129: } 130: 131: /** 132: * This method is called whenever a username and password for a given 133: * network operation is required. First, a security check is made to see 134: * if the caller has the "requestPasswordAuthentication" 135: * permission. If not, the method thows an exception. If there is no 136: * default <code>Authenticator</code> object, the method then returns 137: * <code>null</code>. Otherwise, the default authenticators's instance 138: * variables are initialized and it's <code>getPasswordAuthentication</code> 139: * method is called to get the actual authentication information to return. 140: * 141: * @param addr The address requesting authentication 142: * @param port The port requesting authentication 143: * @param protocol The protocol requesting authentication 144: * @param prompt The prompt to display to the user when requesting 145: * authentication info 146: * @param scheme The authentication scheme in use 147: * 148: * @return A <code>PasswordAuthentication</code> object with the user's 149: * authentication info. 150: * 151: * @exception SecurityException If the caller does not have permission to 152: * perform this operation 153: */ 154: public static PasswordAuthentication requestPasswordAuthentication(InetAddress addr, 155: int port, 156: String protocol, 157: String prompt, 158: String scheme) 159: throws SecurityException 160: { 161: return requestPasswordAuthentication(null, addr, port, protocol, prompt, 162: scheme); 163: } 164: 165: /** 166: * This method is called whenever a username and password for a given 167: * network operation is required. First, a security check is made to see 168: * if the caller has the "requestPasswordAuthentication" 169: * permission. If not, the method thows an exception. If there is no 170: * default <code>Authenticator</code> object, the method then returns 171: * <code>null</code>. Otherwise, the default authenticators's instance 172: * variables are initialized and it's <code>getPasswordAuthentication</code> 173: * method is called to get the actual authentication information to return. 174: * This method is the preferred one as it can be used with hostname 175: * when addr is unknown. 176: * 177: * @param host The hostname requesting authentication 178: * @param addr The address requesting authentication 179: * @param port The port requesting authentication 180: * @param protocol The protocol requesting authentication 181: * @param prompt The prompt to display to the user when requesting 182: * authentication info 183: * @param scheme The authentication scheme in use 184: * 185: * @return A <code>PasswordAuthentication</code> object with the user's 186: * authentication info. 187: * 188: * @exception SecurityException If the caller does not have permission to 189: * perform this operation 190: * 191: * @since 1.4 192: */ 193: public static PasswordAuthentication requestPasswordAuthentication(String host, 194: InetAddress addr, 195: int port, 196: String protocol, 197: String prompt, 198: String scheme) 199: throws SecurityException 200: { 201: SecurityManager sm = System.getSecurityManager(); 202: if (sm != null) 203: sm.checkPermission(new NetPermission("requestPasswordAuthentication")); 204: 205: if (defaultAuthenticator == null) 206: return null; 207: 208: defaultAuthenticator.host = host; 209: defaultAuthenticator.addr = addr; 210: defaultAuthenticator.port = port; 211: defaultAuthenticator.protocol = protocol; 212: defaultAuthenticator.prompt = prompt; 213: defaultAuthenticator.scheme = scheme; 214: 215: return defaultAuthenticator.getPasswordAuthentication(); 216: } 217: 218: /* 219: * Constructors 220: */ 221: 222: /** 223: * Default, no-argument constructor for subclasses to call. 224: */ 225: public Authenticator() 226: { 227: } 228: 229: /* 230: * Instance Methods 231: */ 232: 233: /** 234: * This method returns the address of the site that is requesting 235: * authentication. 236: * 237: * @return The requesting site's address 238: */ 239: protected final InetAddress getRequestingSite() 240: { 241: return addr; 242: } 243: 244: /** 245: * Returns the hostname of the host or proxy requesting authorization, 246: * or <code>null</code> if not available. 247: * 248: * @return The name of the host requesting authentication, or 249: * <code>null</code> if it is not available. 250: * 251: * @since 1.4 252: */ 253: protected final String getRequestingHost() 254: { 255: return host; 256: } 257: 258: /** 259: * This method returns the port of the site that is requesting 260: * authentication. 261: * 262: * @return The requesting port 263: */ 264: protected final int getRequestingPort() 265: { 266: return port; 267: } 268: 269: /** 270: * This method returns the requesting protocol of the operation that is 271: * requesting authentication 272: * 273: * @return The requesting protocol 274: */ 275: protected final String getRequestingProtocol() 276: { 277: return protocol; 278: } 279: 280: /** 281: * Returns the prompt that should be used when requesting authentication 282: * information from the user 283: * 284: * @return The user prompt 285: */ 286: protected final String getRequestingPrompt() 287: { 288: return prompt; 289: } 290: 291: /** 292: * This method returns the authentication scheme in use 293: * 294: * @return The authentication scheme 295: */ 296: protected final String getRequestingScheme() 297: { 298: return scheme; 299: } 300: 301: /** 302: * This method is called whenever a request for authentication is made. It 303: * can call the other getXXX methods to determine the information relevant 304: * to this request. Subclasses should override this method, which returns 305: * <code>null</code> by default. 306: * 307: * @return The <code>PasswordAuthentication</code> information 308: */ 309: protected PasswordAuthentication getPasswordAuthentication() 310: { 311: return null; 312: } 313: } // class Authenticator