1 /* 2 * Copyright (c) 2003, 2004, 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</code> directly, 36 * the provider may also invoke <code>login</code> 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 /** 45 * Constructs a provider with the specified name, version number, 46 * and information. 47 * 48 * @param name the provider name. 49 * @param version the provider version number. 50 * @param info a description of the provider and its services. 51 */ 52 protected AuthProvider(String name, double version, String info) { 53 super(name, version, info); 54 } 55 56 /** 57 * Log in to this provider. 58 * 59 * <p> The provider relies on a <code>CallbackHandler</code> 60 * to obtain authentication information from the caller 61 * (a PIN, for example). If the caller passes a <code>null</code> 62 * handler to this method, the provider uses the handler set in the 63 * <code>setCallbackHandler</code> method. 64 * If no handler was set in that method, the provider queries the 65 * <i>auth.login.defaultCallbackHandler</i> security property 66 * for the fully qualified class name of a default handler implementation. 67 * If the security property is not set, 68 * the provider is assumed to have alternative means 69 * for obtaining authentication information. 70 * 71 * @param subject the <code>Subject</code> which may contain 72 * principals/credentials used for authentication, 73 * or may be populated with additional principals/credentials 74 * after successful authentication has completed. 75 * This parameter may be <code>null</code>. 76 * @param handler the <code>CallbackHandler</code> used by 77 * this provider to obtain authentication information 78 * from the caller, which may be <code>null</code> 79 * 80 * @exception LoginException if the login operation fails 81 * @exception SecurityException if the caller does not pass a 82 * security check for 83 * <code>SecurityPermission("authProvider.<i>name</i>")</code>, 84 * where <i>name</i> is the value returned by 85 * this provider's <code>getName</code> method 86 */ 87 public abstract void login(Subject subject, CallbackHandler handler) 88 throws LoginException; 89 90 /** 91 * Log out from this provider. 92 * 93 * @exception LoginException if the logout operation fails 94 * @exception SecurityException if the caller does not pass a 95 * security check for 96 * <code>SecurityPermission("authProvider.<i>name</i>")</code>, 97 * where <i>name</i> is the value returned by 98 * this provider's <code>getName</code> method 99 */ 100 public abstract void logout() throws LoginException; 101 102 /** 103 * Set a <code>CallbackHandler</code>. 104 * 105 * <p> The provider uses this handler if one is not passed to the 106 * <code>login</code> method. The provider also uses this handler 107 * if it invokes <code>login</code> on behalf of callers. 108 * In either case if a handler is not set via this method, 109 * the provider queries the 110 * <i>auth.login.defaultCallbackHandler</i> security property 111 * for the fully qualified class name of a default handler implementation. 112 * If the security property is not set, 113 * the provider is assumed to have alternative means 114 * for obtaining authentication information. 115 * 116 * @param handler a <code>CallbackHandler</code> for obtaining 117 * authentication information, which may be <code>null</code> 118 * 119 * @exception SecurityException if the caller does not pass a 120 * security check for 121 * <code>SecurityPermission("authProvider.<i>name</i>")</code>, 122 * where <i>name</i> is the value returned by 123 * this provider's <code>getName</code> method 124 */ 125 public abstract void setCallbackHandler(CallbackHandler handler); 126 } | 1 /* 2 * Copyright (c) 2003, 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.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 /** 45 * Constructs a provider with the specified name, version number, 46 * and information. 47 * 48 * @param name the provider name. 49 * @param version the provider version number. 50 * @param info a description of the provider and its services. 51 */ 52 protected AuthProvider(String name, double version, String info) { 53 super(name, version, info); 54 } 55 56 /** 57 * Log in to this provider. 58 * 59 * <p> The provider relies on a {@code CallbackHandler} 60 * to obtain authentication information from the caller 61 * (a PIN, for example). If the caller passes a {@code null} 62 * handler to this method, the provider uses the handler set in the 63 * {@code setCallbackHandler} method. 64 * If no handler was set in that method, the provider queries the 65 * <i>auth.login.defaultCallbackHandler</i> security property 66 * for the fully qualified class name of a default handler implementation. 67 * If the security property is not set, 68 * the provider is assumed to have alternative means 69 * for obtaining authentication information. 70 * 71 * @param subject the {@code Subject} which may contain 72 * principals/credentials used for authentication, 73 * or may be populated with additional principals/credentials 74 * after successful authentication has completed. 75 * This parameter may be {@code null}. 76 * @param handler the {@code CallbackHandler} used by 77 * this provider to obtain authentication information 78 * from the caller, which may be {@code null} 79 * 80 * @exception LoginException if the login operation fails 81 * @exception SecurityException if the caller does not pass a 82 * security check for 83 * {@code SecurityPermission("authProvider.name")}, 84 * where {@code name} is the value returned by 85 * this provider's {@code getName} method 86 */ 87 public abstract void login(Subject subject, CallbackHandler handler) 88 throws LoginException; 89 90 /** 91 * Log out from this provider. 92 * 93 * @exception LoginException if the logout operation fails 94 * @exception SecurityException if the caller does not pass a 95 * security check for 96 * {@code SecurityPermission("authProvider.name")}, 97 * where {@code name} is the value returned by 98 * this provider's {@code getName} method 99 */ 100 public abstract void logout() throws LoginException; 101 102 /** 103 * Set a {@code CallbackHandler}. 104 * 105 * <p> The provider uses this handler if one is not passed to the 106 * {@code login} method. The provider also uses this handler 107 * if it invokes {@code login} on behalf of callers. 108 * In either case if a handler is not set via this method, 109 * the provider queries the 110 * <i>auth.login.defaultCallbackHandler</i> security property 111 * for the fully qualified class name of a default handler implementation. 112 * If the security property is not set, 113 * the provider is assumed to have alternative means 114 * for obtaining authentication information. 115 * 116 * @param handler a {@code CallbackHandler} for obtaining 117 * authentication information, which may be {@code null} 118 * 119 * @exception SecurityException if the caller does not pass a 120 * security check for 121 * {@code SecurityPermission("authProvider.name")}, 122 * where {@code name} is the value returned by 123 * this provider's {@code getName} method 124 */ 125 public abstract void setCallbackHandler(CallbackHandler handler); 126 } |