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