Save This Page
Home » openjdk-7 » java » security » [javadoc | source]
    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   }

Save This Page
Home » openjdk-7 » java » security » [javadoc | source]