1 /* 2 * Copyright (c) 2003, 2019, 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.security; 27 28 import javax.security.auth.Subject; 29 import javax.security.auth.login.LoginException; 30 import javax.security.auth.callback.CallbackHandler; 31 32 /** 33 * This class defines login and logout methods for a provider. 34 * 35 * <p> While callers may invoke {@code login} directly, 36 * the provider may also invoke {@code login} on behalf of callers 37 * if it determines that a login must be performed 38 * prior to certain operations. 39 * 40 * @since 1.5 41 */ 42 public abstract class AuthProvider extends Provider { 43 44 @java.io.Serial 45 private static final long serialVersionUID = 4197859053084546461L; 46 47 /** 48 * Constructs a provider with the specified name, version number, 49 * and information. 50 * 51 * @param name the provider name. 52 * @param version the provider version number. 53 * @param info a description of the provider and its services. 54 * @deprecated use {@link #AuthProvider(String, String, String)} instead. 55 */ 56 @Deprecated(since="9") AuthProvider(String name, double version, String info)57 protected AuthProvider(String name, double version, String info) { 58 super(name, Double.toString(version), info); 59 } 60 61 /** 62 * Constructs a provider with the specified name, version string, 63 * and information. 64 * 65 * @param name the provider name. 66 * @param versionStr the provider version string. 67 * @param info a description of the provider and its services. 68 * @since 9 69 */ AuthProvider(String name, String versionStr, String info)70 protected AuthProvider(String name, String versionStr, String info) { 71 super(name, versionStr, info); 72 } 73 74 /** 75 * Log in to this provider. 76 * 77 * <p> The provider relies on a {@code CallbackHandler} 78 * to obtain authentication information from the caller 79 * (a PIN, for example). If the caller passes a {@code null} 80 * handler to this method, the provider uses the handler set in the 81 * {@code setCallbackHandler} method. 82 * If no handler was set in that method, the provider queries the 83 * <i>auth.login.defaultCallbackHandler</i> security property 84 * for the fully qualified class name of a default handler implementation. 85 * If the security property is not set, 86 * the provider is assumed to have alternative means 87 * for obtaining authentication information. 88 * 89 * @param subject the {@code Subject} which may contain 90 * principals/credentials used for authentication, 91 * or may be populated with additional principals/credentials 92 * after successful authentication has completed. 93 * This parameter may be {@code null}. 94 * @param handler the {@code CallbackHandler} used by 95 * this provider to obtain authentication information 96 * from the caller, which may be {@code null} 97 * 98 * @throws IllegalStateException if the provider requires configuration 99 * and {@link configure} has not been called 100 * @throws LoginException if the login operation fails 101 * @throws SecurityException if the caller does not pass a 102 * security check for 103 * {@code SecurityPermission("authProvider.name")}, 104 * where {@code name} is the value returned by 105 * this provider's {@code getName} method 106 */ login(Subject subject, CallbackHandler handler)107 public abstract void login(Subject subject, CallbackHandler handler) 108 throws LoginException; 109 110 /** 111 * Log out from this provider. 112 * 113 * @throws IllegalStateException if the provider requires configuration 114 * and {@link configure} has not been called 115 * @throws LoginException if the logout operation fails 116 * @throws SecurityException if the caller does not pass a 117 * security check for 118 * {@code SecurityPermission("authProvider.name")}, 119 * where {@code name} is the value returned by 120 * this provider's {@code getName} method 121 */ logout()122 public abstract void logout() throws LoginException; 123 124 /** 125 * Set a {@code CallbackHandler}. 126 * 127 * <p> The provider uses this handler if one is not passed to the 128 * {@code login} method. The provider also uses this handler 129 * if it invokes {@code login} on behalf of callers. 130 * In either case if a handler is not set via this method, 131 * the provider queries the 132 * <i>auth.login.defaultCallbackHandler</i> security property 133 * for the fully qualified class name of a default handler implementation. 134 * If the security property is not set, 135 * the provider is assumed to have alternative means 136 * for obtaining authentication information. 137 * 138 * @param handler a {@code CallbackHandler} for obtaining 139 * authentication information, which may be {@code null} 140 * 141 * @throws IllegalStateException if the provider requires configuration 142 * and {@link configure} has not been called 143 * @throws SecurityException if the caller does not pass a 144 * security check for 145 * {@code SecurityPermission("authProvider.name")}, 146 * where {@code name} is the value returned by 147 * this provider's {@code getName} method 148 */ setCallbackHandler(CallbackHandler handler)149 public abstract void setCallbackHandler(CallbackHandler handler); 150 } 151