001: /*
002: * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.security;
027:
028: import javax.security.auth.Subject;
029: import javax.security.auth.login.LoginException;
030: import javax.security.auth.callback.CallbackHandler;
031:
032: /**
033: * This class defines login and logout methods for a provider.
034: *
035: * <p> While callers may invoke <code>login</code> directly,
036: * the provider may also invoke <code>login</code> on behalf of callers
037: * if it determines that a login must be performed
038: * prior to certain operations.
039: *
040: * @version 1.10, 05/05/07
041: * @since 1.5
042: */
043: public abstract class AuthProvider extends Provider {
044:
045: /**
046: * Constructs a provider with the specified name, version number,
047: * and information.
048: *
049: * @param name the provider name.
050: * @param version the provider version number.
051: * @param info a description of the provider and its services.
052: */
053: protected AuthProvider(String name, double version, String info) {
054: super (name, version, info);
055: }
056:
057: /**
058: * Log in to this provider.
059: *
060: * <p> The provider relies on a <code>CallbackHandler</code>
061: * to obtain authentication information from the caller
062: * (a PIN, for example). If the caller passes a <code>null</code>
063: * handler to this method, the provider uses the handler set in the
064: * <code>setCallbackHandler</code> method.
065: * If no handler was set in that method, the provider queries the
066: * <i>auth.login.defaultCallbackHandler</i> security property
067: * for the fully qualified class name of a default handler implementation.
068: * If the security property is not set,
069: * the provider is assumed to have alternative means
070: * for obtaining authentication information.
071: *
072: * @param subject the <code>Subject</code> which may contain
073: * principals/credentials used for authentication,
074: * or may be populated with additional principals/credentials
075: * after successful authentication has completed.
076: * This parameter may be <code>null</code>.
077: * @param handler the <code>CallbackHandler</code> used by
078: * this provider to obtain authentication information
079: * from the caller, which may be <code>null</code>
080: *
081: * @exception LoginException if the login operation fails
082: * @exception SecurityException if the caller does not pass a
083: * security check for
084: * <code>SecurityPermission("authProvider.<i>name</i>")</code>,
085: * where <i>name</i> is the value returned by
086: * this provider's <code>getName</code> method
087: */
088: public abstract void login(Subject subject, CallbackHandler handler)
089: throws LoginException;
090:
091: /**
092: * Log out from this provider.
093: *
094: * @exception LoginException if the logout operation fails
095: * @exception SecurityException if the caller does not pass a
096: * security check for
097: * <code>SecurityPermission("authProvider.<i>name</i>")</code>,
098: * where <i>name</i> is the value returned by
099: * this provider's <code>getName</code> method
100: */
101: public abstract void logout() throws LoginException;
102:
103: /**
104: * Set a <code>CallbackHandler</code>.
105: *
106: * <p> The provider uses this handler if one is not passed to the
107: * <code>login</code> method. The provider also uses this handler
108: * if it invokes <code>login</code> on behalf of callers.
109: * In either case if a handler is not set via this method,
110: * the provider queries the
111: * <i>auth.login.defaultCallbackHandler</i> security property
112: * for the fully qualified class name of a default handler implementation.
113: * If the security property is not set,
114: * the provider is assumed to have alternative means
115: * for obtaining authentication information.
116: *
117: * @param handler a <code>CallbackHandler</code> for obtaining
118: * authentication information, which may be <code>null</code>
119: *
120: * @exception SecurityException if the caller does not pass a
121: * security check for
122: * <code>SecurityPermission("authProvider.<i>name</i>")</code>,
123: * where <i>name</i> is the value returned by
124: * this provider's <code>getName</code> method
125: */
126: public abstract void setCallbackHandler(CallbackHandler handler);
127: }
| 