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