A generic account exception.

Signals that a user account has expired.

 This exception is thrown by LoginModules when they determine
that an account has expired.  For example, a LoginModule,
after successfully authenticating a user, may determine that the
user's account has expired.  In this case the LoginModule
throws this exception to notify the application.  The application can
then take the appropriate steps to notify the user.

Signals that an account was locked.

 This exception may be thrown by a LoginModule if it
determines that authentication is being attempted on a
locked account.

Signals that an account was not found.

 This exception may be thrown by a LoginModule if it is unable
to locate an account necessary to perform authentication.

This class represents a single LoginModule entry
configured for the application specified in the
getAppConfigurationEntry(String appName)
method in the Configuration class.  Each respective
AppConfigurationEntry contains a LoginModule name,
a control flag (specifying whether this LoginModule is
REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL), and LoginModule-specific
options.  Please refer to the Configuration class for
more information on the different control flags and their semantics.

This class represents whether or not a LoginModule
is REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL.

 Name {
       ModuleClass  Flag    ModuleOptions;
       ModuleClass  Flag    ModuleOptions;
       ModuleClass  Flag    ModuleOptions;
 };
 Name {
       ModuleClass  Flag    ModuleOptions;
       ModuleClass  Flag    ModuleOptions;
 };
 other {
       ModuleClass  Flag    ModuleOptions;
       ModuleClass  Flag    ModuleOptions;
 };

 1) Required     - The  LoginModule is required to succeed.
                 If it succeeds or fails, authentication still continues
                 to proceed down the  LoginModule list.

 2) Requisite    - The  LoginModule is required to succeed.
                 If it succeeds, authentication continues down the
                  LoginModule list.  If it fails,
                 control immediately returns to the application
                 (authentication does not proceed down the
                  LoginModule list).

 3) Sufficient   - The  LoginModule is not required to
                 succeed.  If it does succeed, control immediately
                 returns to the application (authentication does not
                 proceed down the  LoginModule list).
                 If it fails, authentication continues down the
                  LoginModule list.

 4) Optional     - The  LoginModule is not required to
                 succeed.  If it succeeds or fails,
                 authentication still continues to proceed down the
                  LoginModule list.

A Configuration object is responsible for specifying which LoginModules
should be used for a particular application, and in what order the
LoginModules should be invoked.

 A login configuration contains the following information.
Note that this example only represents the default syntax for the
Configuration.  Subclass implementations of this class
may implement alternative syntaxes and may retrieve the
Configuration from any source such as files, databases,
or servers.



     Name {
           ModuleClass  Flag    ModuleOptions;
           ModuleClass  Flag    ModuleOptions;
           ModuleClass  Flag    ModuleOptions;
     };
     Name {
           ModuleClass  Flag    ModuleOptions;
           ModuleClass  Flag    ModuleOptions;
     };
     other {
           ModuleClass  Flag    ModuleOptions;
           ModuleClass  Flag    ModuleOptions;
     };

 Each entry in the Configuration is indexed via an
application name, Name, and contains a list of
LoginModules configured for that application.  Each LoginModule
is specified via its fully qualified class name.
Authentication proceeds down the module list in the exact order specified.
If an application does not have a specific entry,
it defaults to the specific entry for "other".

 The Flag value controls the overall behavior as authentication
proceeds down the stack.  The following represents a description of the
valid values for Flag and their respective semantics:



     1) Required     - The  LoginModule is required to succeed.
                     If it succeeds or fails, authentication still continues
                     to proceed down the  LoginModule list.

     2) Requisite    - The  LoginModule is required to succeed.
                     If it succeeds, authentication continues down the
                      LoginModule list.  If it fails,
                     control immediately returns to the application
                     (authentication does not proceed down the
                      LoginModule list).

     3) Sufficient   - The  LoginModule is not required to
                     succeed.  If it does succeed, control immediately
                     returns to the application (authentication does not
                     proceed down the  LoginModule list).
                     If it fails, authentication continues down the
                      LoginModule list.

     4) Optional     - The  LoginModule is not required to
                     succeed.  If it succeeds or fails,
                     authentication still continues to proceed down the
                      LoginModule list.

 The overall authentication succeeds only if all Required and
Requisite LoginModules succeed.  If a Sufficient
LoginModule is configured and succeeds,
then only the Required and Requisite LoginModules prior to
that Sufficient LoginModule need to have succeeded for
the overall authentication to succeed. If no Required or
Requisite LoginModules are configured for an application,
then at least one Sufficient or Optional
LoginModule must succeed.

 ModuleOptions is a space separated list of
LoginModule-specific values which are passed directly to
the underlying LoginModules.  Options are defined by the
LoginModule itself, and control the behavior within it.
For example, a LoginModule may define options to support
debugging/testing capabilities.  The correct way to specify options in the
Configuration is by using the following key-value pairing:
debug="true".  The key and value should be separated by an
'equals' symbol, and the value should be surrounded by double quotes.
If a String in the form, ${system.property}, occurs in the value,
it will be expanded to the value of the system property.
Note that there is no limit to the number of
options a LoginModule may define.

 The following represents an example Configuration entry
based on the syntax above:



Login {
  com.sun.security.auth.module.UnixLoginModule required;
  com.sun.security.auth.module.Krb5LoginModule optional
                  useTicketCache="true"
                  ticketCache="${user.home}${/}tickets";
};

 This Configuration specifies that an application named,
"Login", requires users to first authenticate to the
com.sun.security.auth.module.UnixLoginModule, which is
required to succeed.  Even if the UnixLoginModule
authentication fails, the
com.sun.security.auth.module.Krb5LoginModule
still gets invoked.  This helps hide the source of failure.
Since the Krb5LoginModule is Optional, the overall
authentication succeeds only if the UnixLoginModule
(Required) succeeds.

 Also note that the LoginModule-specific options,
useTicketCache="true" and
ticketCache=${user.home}${/}tickets",
are passed to the Krb5LoginModule.
These options instruct the Krb5LoginModule to
use the ticket cache at the specified location.
The system properties, user.home and /
(file.separator), are expanded to their respective values.

 There is only one Configuration object installed in the runtime at any
given time.  A Configuration object can be installed by calling the
setConfiguration method.  The installed Configuration object
can be obtained by calling the getConfiguration method.

 If no Configuration object has been installed in the runtime, a call to
getConfiguration installs an instance of the default
Configuration implementation (a default subclass implementation of this
abstract class).
The default Configuration implementation can be changed by setting the value
of the login.configuration.provider security property to the fully
qualified name of the desired Configuration subclass implementation.

 Application code can directly subclass Configuration to provide a custom
implementation.  In addition, an instance of a Configuration object can be
constructed by invoking one of the getInstance factory methods
with a standard type.  The default policy type is "JavaLoginConfig".
See the Configuration section in the
Java Cryptography Architecture Standard Algorithm Name Documentation
for a list of standard Configuration types.

This represents a marker interface for Configuration parameters.

This class defines the Service Provider Interface (SPI)
for the Configuration class.
All the abstract methods in this class must be implemented by each
service provider who wishes to supply a Configuration implementation.

 Subclass implementations of this abstract class must provide
a public constructor that takes a Configuration.Parameters
object as an input parameter.  This constructor also must throw
an IllegalArgumentException if it does not understand the
Configuration.Parameters input.

A generic credential exception.

Signals that a Credential has expired.

 This exception is thrown by LoginModules when they determine
that a Credential has expired.
For example, a LoginModule authenticating a user
in its login method may determine that the user's
password, although entered correctly, has expired.  In this case
the LoginModule throws this exception to notify
the application.  The application can then take the appropriate
steps to assist the user in updating the password.

Signals that a credential was not found.

 This exception may be thrown by a LoginModule if it is unable
to locate a credential necessary to perform authentication.

Signals that user authentication failed.

 This exception is thrown by LoginModules if authentication failed.
For example, a LoginModule throws this exception if
the user entered an incorrect password.

 config = Configuration.getConfiguration();

 The LoginContext class describes the basic methods used
to authenticate Subjects and provides a way to develop an
application independent of the underlying authentication technology.
A Configuration specifies the authentication technology, or
LoginModule, to be used with a particular application.
Different LoginModules can be plugged in under an application
without requiring any modifications to the application itself.

 In addition to supporting pluggable authentication, this class
also supports the notion of stacked authentication.
Applications may be configured to use more than one
LoginModule.  For example, one could
configure both a Kerberos LoginModule and a smart card
LoginModule under an application.

 A typical caller instantiates a LoginContext with
a name and a CallbackHandler.
LoginContext uses the name as the index into a
Configuration to determine which LoginModules should be used,
and which ones must succeed in order for the overall authentication to
succeed.  The CallbackHandler is passed to the underlying
LoginModules so they may communicate and interact with users
(prompting for a username and password via a graphical user interface,
for example).

 Once the caller has instantiated a LoginContext,
it invokes the login method to authenticate
a Subject.  The login method invokes
the configured modules to perform their respective types of authentication
(username/password, smart card pin verification, etc.).
Note that the LoginModules will not attempt authentication retries nor
introduce delays if the authentication fails.
Such tasks belong to the LoginContext caller.

 If the login method returns without
throwing an exception, then the overall authentication succeeded.
The caller can then retrieve
the newly authenticated Subject by invoking the
getSubject method.  Principals and Credentials associated
with the Subject may be retrieved by invoking the Subject's
respective getPrincipals, getPublicCredentials,
and getPrivateCredentials methods.

 To logout the Subject, the caller calls
the logout method.  As with the login
method, this logout method invokes the logout
method for the configured modules.

 A LoginContext should not be used to authenticate
more than one Subject.  A separate LoginContext
should be used to authenticate each different Subject.

 The following documentation applies to all LoginContext constructors:


 Subject

 If the constructor has a Subject
input parameter, the LoginContext uses the caller-specified
Subject object.

 If the caller specifies a null Subject
and a null value is permitted,
the LoginContext instantiates a new Subject.

 If the constructor does not have a Subject
input parameter, the LoginContext instantiates a new Subject.



 Configuration

 If the constructor has a Configuration
input parameter and the caller specifies a non-null Configuration,
the LoginContext uses the caller-specified Configuration.

If the constructor does not have a Configuration
input parameter, or if the caller specifies a null
Configuration object, the constructor uses the following call to
get the installed Configuration:


     config = Configuration.getConfiguration();
For both cases,
the name argument given to the constructor is passed to the
Configuration.getAppConfigurationEntry method.
If the Configuration has no entries for the specified name,
then the LoginContext calls
getAppConfigurationEntry with the name, "other"
(the default entry name).  If there is no entry for "other",
then a LoginException is thrown.

 When LoginContext uses the installed Configuration, the caller
requires the createLoginContext.name and possibly
createLoginContext.other AuthPermissions. Furthermore, the
LoginContext will invoke configured modules from within an
AccessController.doPrivileged call so that modules that
perform security-sensitive tasks (such as connecting to remote hosts,
and updating the Subject) will require the respective permissions, but
the callers of the LoginContext will not require those permissions.

 When LoginContext uses a caller-specified Configuration, the caller
does not require any createLoginContext AuthPermission.  The LoginContext
saves the AccessControlContext for the caller,
and invokes the configured modules from within an
AccessController.doPrivileged call constrained by that context.
This means the caller context (stored when the LoginContext was created)
must have sufficient permissions to perform any security-sensitive tasks
that the modules may perform.



 CallbackHandler

 If the constructor has a CallbackHandler
input parameter, the LoginContext uses the caller-specified
CallbackHandler object.

 If the constructor does not have a CallbackHandler
input parameter, or if the caller specifies a null
CallbackHandler object (and a null value is permitted),
the LoginContext queries the
auth.login.defaultCallbackHandler security property for the
fully qualified class name of a default handler
implementation. If the security property is not set,
then the underlying modules will not have a
CallbackHandler for use in communicating
with users.  The caller thus assumes that the configured
modules have alternative means for authenticating the user.


 When the LoginContext uses the installed Configuration (instead of
a caller-specified Configuration, see above),
then this LoginContext must wrap any
caller-specified or default CallbackHandler implementation
in a new CallbackHandler implementation
whose handle method implementation invokes the
specified CallbackHandler's handle method in a
java.security.AccessController.doPrivileged call
constrained by the caller's current AccessControlContext.

This is the basic login exception.