doAs -                  allow the caller to invoke the
                          Subject.doAs methods.

 doAsPrivileged -        allow the caller to invoke the
                          Subject.doAsPrivileged methods.

 getSubject -            allow for the retrieval of the
                         Subject(s) associated with the
                         current Thread.

 getSubjectFromDomainCombiner -  allow for the retrieval of the
                         Subject associated with the
                         a  SubjectDomainCombiner.

 setReadOnly -           allow the caller to set a Subject
                         to be read-only.

 modifyPrincipals -      allow the caller to modify the  Set
                         of Principals associated with a
                          Subject

 modifyPublicCredentials - allow the caller to modify the
                          Set of public credentials
                         associated with a  Subject

 modifyPrivateCredentials - allow the caller to modify the
                          Set of private credentials
                         associated with a  Subject

 refreshCredential -     allow code to invoke the  refresh
                         method on a credential which implements
                         the  Refreshable interface.

 destroyCredential -     allow code to invoke the  destroy
                         method on a credential  object
                         which implements the  Destroyable
                         interface.

 createLoginContext.{name} -  allow code to instantiate a
                          LoginContext with the
                         specified name.  name
                         is used as the index into the installed login
                          Configuration
                         (that returned by
                          Configuration.getConfiguration()).
                         name can be wildcarded (set to '*')
                         to allow for any name.

 getLoginConfiguration - allow for the retrieval of the system-wide
                         login Configuration.

 createLoginConfiguration.{type} - allow code to obtain a Configuration
                         object via
                          Configuration.getInstance.

 setLoginConfiguration - allow for the setting of the system-wide
                         login Configuration.

 refreshLoginConfiguration - allow for the refreshing of the system-wide
                         login Configuration.

 createLoginContext -    allow code to instantiate a
                          LoginContext.

 getPolicy -             allow the caller to retrieve the system-wide
                         Subject-based access control policy.

 setPolicy -             allow the caller to set the system-wide
                         Subject-based access control policy.

 refreshPolicy -         allow the caller to refresh the system-wide
                         Subject-based access control policy.

This class is for authentication permissions.
An AuthPermission contains a name
(also referred to as a "target name")
but no actions list; you either have the named permission
or you don't.

 The target name is the name of a security configuration parameter
(see below).  Currently the AuthPermission object is used to
guard access to the Policy, Subject, LoginContext,
and Configuration objects.

 The possible target names for an Authentication Permission are:



     doAs -                  allow the caller to invoke the
                              Subject.doAs methods.

     doAsPrivileged -        allow the caller to invoke the
                              Subject.doAsPrivileged methods.

     getSubject -            allow for the retrieval of the
                             Subject(s) associated with the
                             current Thread.

     getSubjectFromDomainCombiner -  allow for the retrieval of the
                             Subject associated with the
                             a  SubjectDomainCombiner.

     setReadOnly -           allow the caller to set a Subject
                             to be read-only.

     modifyPrincipals -      allow the caller to modify the  Set
                             of Principals associated with a
                              Subject

     modifyPublicCredentials - allow the caller to modify the
                              Set of public credentials
                             associated with a  Subject

     modifyPrivateCredentials - allow the caller to modify the
                              Set of private credentials
                             associated with a  Subject

     refreshCredential -     allow code to invoke the  refresh
                             method on a credential which implements
                             the  Refreshable interface.

     destroyCredential -     allow code to invoke the  destroy
                             method on a credential  object
                             which implements the  Destroyable
                             interface.

     createLoginContext.{name} -  allow code to instantiate a
                              LoginContext with the
                             specified name.  name
                             is used as the index into the installed login
                              Configuration
                             (that returned by
                              Configuration.getConfiguration()).
                             name can be wildcarded (set to '*')
                             to allow for any name.

     getLoginConfiguration - allow for the retrieval of the system-wide
                             login Configuration.

     createLoginConfiguration.{type} - allow code to obtain a Configuration
                             object via
                              Configuration.getInstance.

     setLoginConfiguration - allow for the setting of the system-wide
                             login Configuration.

     refreshLoginConfiguration - allow for the refreshing of the system-wide
                             login Configuration.

 The following target name has been deprecated in favor of
createLoginContext.{name}.



     createLoginContext -    allow code to instantiate a
                              LoginContext.

 javax.security.auth.Policy has been
deprecated in favor of java.security.Policy.
Therefore, the following target names have also been deprecated:



     getPolicy -             allow the caller to retrieve the system-wide
                             Subject-based access control policy.

     setPolicy -             allow the caller to set the system-wide
                             Subject-based access control policy.

     refreshPolicy -         allow the caller to refresh the system-wide
                             Subject-based access control policy.

 Implementations of this interface are passed to a
CallbackHandler, allowing underlying security services
the ability to interact with a calling application to retrieve specific
authentication data such as usernames and passwords, or to display
certain information, such as error and warning messages.

 Callback implementations do not retrieve or
display the information requested by underlying security services.
Callback implementations simply provide the means
to pass such requests to applications, and for applications,
if appropriate, to return requested information back to the
underlying security services.

 An application implements a CallbackHandler and passes
it to underlying security services so that they may interact with
the application to retrieve specific authentication data,
such as usernames and passwords, or to display certain information,
such as error and warning messages.

 CallbackHandlers are implemented in an application-dependent fashion.
For example, implementations for an application with a graphical user
interface (GUI) may pop up windows to prompt for requested information
or to display error messages.  An implementation may also choose to obtain
requested information from an alternate source without asking the end user.

 Underlying security services make requests for different types
of information by passing individual Callbacks to the
CallbackHandler.  The CallbackHandler
implementation decides how to retrieve and display information
depending on the Callbacks passed to it.  For example,
if the underlying service needs a username and password to
authenticate a user, it uses a NameCallback and
PasswordCallback.  The CallbackHandler
can then choose to prompt for a username and password serially,
or to prompt for both in a single window.

 A default CallbackHandler class implementation
may be specified by setting the value of the
auth.login.defaultCallbackHandler security property.

 If the security property is set to the fully qualified name of a
CallbackHandler implementation class,
then a LoginContext will load the specified
CallbackHandler and pass it to the underlying LoginModules.
The LoginContext only loads the default handler
if it was not provided one.

 All default handler implementations must provide a public
zero-argument constructor.

 Underlying security services instantiate and pass a
ChoiceCallback to the handle
method of a CallbackHandler to display a list of choices
and to retrieve the selected choice(s).

 Underlying security services instantiate and pass a
ConfirmationCallback to the handle
method of a CallbackHandler to ask for YES/NO,
OK/CANCEL, YES/NO/CANCEL or other similar confirmations.

 Underlying security services instantiate and pass a
LanguageCallback to the handle
method of a CallbackHandler to retrieve the Locale
used for localizing text.

 Underlying security services instantiate and pass a
NameCallback to the handle
method of a CallbackHandler to retrieve name information.

 Underlying security services instantiate and pass a
PasswordCallback to the handle
method of a CallbackHandler to retrieve password information.

 Underlying security services instantiate and pass a
TextInputCallback to the handle
method of a CallbackHandler to retrieve generic text
information.

 Underlying security services instantiate and pass a
TextOutputCallback to the handle
method of a CallbackHandler to display information messages,
warning messages and error messages.

Signals that a CallbackHandler does not
recognize a particular Callback.

Objects such as credentials may optionally implement this interface
to provide the capability to destroy its contents.

Signals that a destroy operation failed.

 This exception is thrown by credentials implementing
the Destroyable interface when the destroy
method fails.

This class is used to restrict the usage of the Kerberos
delegation model, ie: forwardable and proxiable tickets.

The target name of this Permission specifies a pair of
kerberos service principals. The first is the subordinate service principal
being entrusted to use the TGT. The second service principal designates
the target service the subordinate service principal is to
interact with on behalf of the initiating KerberosPrincipal. This
latter service principal is specified to restrict the use of a
proxiable ticket.

For example, to specify the "host" service use of a forwardable TGT the
target permission is specified as follows:



 DelegationPermission("\"host/foo.example.com@EXAMPLE.COM\" \"krbtgt/EXAMPLE.COM@EXAMPLE.COM\"");

To give the "backup" service a proxiable nfs service ticket the target permission
might be specified:



 DelegationPermission("\"backup/bar.example.com@EXAMPLE.COM\" \"nfs/home.EXAMPLE.COM@EXAMPLE.COM\"");

This class encapsulates a long term secret key for a Kerberos
principal.

All Kerberos JAAS login modules that obtain a principal's password and
generate the secret key from it should use this class.
Sometimes, such as when authenticating a server in
the absence of user-to-user authentication, the login module will store
an instance of this class in the private credential set of a
Subject during the commit phase of the
authentication process.

A Kerberos service using a keytab to read secret keys should use
the KeyTab class, where latest keys can be read when needed.

It might be necessary for the application to be granted a
PrivateCredentialPermission if it needs to access the KerberosKey
instance from a Subject. This permission is not needed when the
application depends on the default JGSS Kerberos mechanism to access the
KerberosKey. In that case, however, the application will need an
appropriate
ServicePermission.

This class encapsulates a Kerberos principal.

This class encapsulates a Kerberos ticket and associated
information as viewed from the client's point of view. It captures all
information that the Key Distribution Center (KDC) sends to the client
in the reply message KDC-REP defined in the Kerberos Protocol
Specification (RFC 4120).

All Kerberos JAAS login modules that authenticate a user to a KDC should
use this class. Where available, the login module might even read this
information from a ticket cache in the operating system instead of
directly communicating with the KDC. During the commit phase of the JAAS
authentication process, the JAAS login module should instantiate this
class and store the instance in the private credential set of a
Subject.

It might be necessary for the application to be granted a
PrivateCredentialPermission if it needs to access a KerberosTicket
instance from a Subject. This permission is not needed when the
application depends on the default JGSS Kerberos mechanism to access the
KerberosTicket. In that case, however, the application will need an
appropriate
ServicePermission.

Note that this class is applicable to both ticket granting tickets and
other regular service tickets. A ticket granting ticket is just a
special case of a more generalized service ticket.

This class encapsulates a keytab file.

A Kerberos JAAS login module that obtains long term secret keys from a
keytab file should use this class. The login module will store
an instance of this class in the private credential set of a
Subject during the commit phase of the
authentication process.

If a KeyTab object is obtained from getUnboundInstance()
or getUnboundInstance(java.io.File), it is unbound and thus can be
used by any service principal. Otherwise, if it's obtained from
getInstance(KerberosPrincipal) or
getInstance(KerberosPrincipal, java.io.File), it is bound to the
specific service principal and can only be used by it.

Please note the constructors getInstance() and
getInstance(java.io.File) were created when there was no support
for unbound keytabs. These methods should not be used anymore. An object
created with either of these methods are considered to be bound to an
unknown principal, which means, its isBound() returns true and
getPrincipal() returns null.

It might be necessary for the application to be granted a
PrivateCredentialPermission if it needs to access the KeyTab
instance from a Subject. This permission is not needed when the
application depends on the default JGSS Kerberos mechanism to access the
KeyTab. In that case, however, the application will need an appropriate
ServicePermission.

The keytab file format is described at

http://www.ioplex.com/utilities/keytab.txt.

ServicePermission("krbtgt/EXAMPLE.COM@EXAMPLE.COM", "initiate");

ServicePermission("host/foo.example.com@EXAMPLE.COM", "initiate");

ServicePermission("host/foo.example.com@EXAMPLE.COM", "accept");

This class is used to protect Kerberos services and the
credentials necessary to access those services. There is a one to
one mapping of a service principal and the credentials necessary
to access the service. Therefore granting access to a service
principal implicitly grants access to the credential necessary to
establish a security context with the service principal. This
applies regardless of whether the credentials are in a cache
or acquired via an exchange with the KDC. The credential can
be either a ticket granting ticket, a service ticket or a secret
key from a key table.

A ServicePermission contains a service principal name and
a list of actions which specify the context the credential can be
used within.

The service principal name is the canonical name of the
KerberosPrincipal supplying the service, that is
the KerberosPrincipal represents a Kerberos service
principal. This name is treated in a case sensitive manner.
An asterisk may appear by itself, to signify any service principal.

Granting this permission implies that the caller can use a cached
credential (TGT, service ticket or secret key) within the context
designated by the action. In the case of the TGT, granting this
permission also implies that the TGT can be obtained by an
Authentication Service exchange.

The possible actions are:



   initiate -              allow the caller to use the credential to
                           initiate a security context with a service
                           principal.

   accept -                allow the caller to use the credential to
                           accept security context as a particular
                           principal.

For example, to specify the permission to access to the TGT to
initiate a security context the permission is constructed as follows:



    ServicePermission("krbtgt/EXAMPLE.COM@EXAMPLE.COM", "initiate");

To obtain a service ticket to initiate a context with the "host"
service the permission is constructed as follows:


    ServicePermission("host/foo.example.com@EXAMPLE.COM", "initiate");

For a Kerberized server the action is "accept". For example, the permission
necessary to access and use the secret key of the  Kerberized "host"
service (telnet and the likes)  would be constructed as follows:



    ServicePermission("host/foo.example.com@EXAMPLE.COM", "accept");

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.

  public PermissionCollection getPermissions
      (java.security.ProtectionDomain pd)

  public ProtectionDomain
      (CodeSource cs,
       PermissionCollection permissions,
       ClassLoader loader,
       Principal[] principals)

Deprecated.
as of JDK version 1.4 -- Replaced by java.security.Policy.
              java.security.Policy has a method:


      public PermissionCollection getPermissions
          (java.security.ProtectionDomain pd)
 and ProtectionDomain has a constructor:


      public ProtectionDomain
          (CodeSource cs,
           PermissionCollection permissions,
           ClassLoader loader,
           Principal[] principals)

 These two APIs provide callers the means to query the
 Policy for Principal-based Permission entries.

 CredentialClass {PrincipalClass "PrincipalName"}*

This class is used to protect access to private Credentials
belonging to a particular Subject.  The Subject
is represented by a Set of Principals.

 The target name of this Permission specifies
a Credential class name, and a Set of Principals.
The only valid value for this Permission's actions is, "read".
The target name must abide by the following syntax:



     CredentialClass {PrincipalClass "PrincipalName"}*

For example, the following permission grants access to the
com.sun.PrivateCredential owned by Subjects which have
a com.sun.Principal with the name, "duke".  Note that although
this example, as well as all the examples below, do not contain
Codebase, SignedBy, or Principal information in the grant statement
(for simplicity reasons), actual policy configurations should
specify that information when appropriate.



   grant {
     permission javax.security.auth.PrivateCredentialPermission
             "com.sun.PrivateCredential com.sun.Principal \"duke\"",
             "read";
   };

If CredentialClass is "*", then access is granted to
all private Credentials belonging to the specified
Subject.
If "PrincipalName" is "*", then access is granted to the
specified Credential owned by any Subject that has the
specified Principal (the actual PrincipalName doesn't matter).
For example, the following grants access to the
a.b.Credential owned by any Subject that has
an a.b.Principal.



   grant {
     permission javax.security.auth.PrivateCredentialPermission
             "a.b.Credential a.b.Principal "*"",
             "read";
   };

If both the PrincipalClass and "PrincipalName" are "*",
then access is granted to the specified Credential owned by
any Subject.

 In addition, the PrincipalClass/PrincipalName pairing may be repeated:



   grant {
     permission javax.security.auth.PrivateCredentialPermission
             "a.b.Credential a.b.Principal "duke" c.d.Principal "dukette"",
             "read";
   };

The above grants access to the private Credential, "a.b.Credential",
belonging to a Subject with at least two associated Principals:
"a.b.Principal" with the name, "duke", and "c.d.Principal", with the name,
"dukette".

Objects such as credentials may optionally implement this
interface to provide the capability to refresh itself.
For example, a credential with a particular time-restricted lifespan
may implement this interface to allow callers to refresh the time period
for which it is valid.

Signals that a refresh operation failed.

 This exception is thrown by credentials implementing
the Refreshable interface when the refresh
method fails.

 LoginModule describes the interface
implemented by authentication technology providers.  LoginModules
are plugged in under applications to provide a particular type of
authentication.

 While applications write to the LoginContext API,
authentication technology providers implement the
LoginModule interface.
A Configuration specifies the LoginModule(s)
to be used with a particular login application.  Therefore different
LoginModules can be plugged in under the application without
requiring any modifications to the application itself.

 The LoginContext is responsible for reading the
Configuration and instantiating the appropriate
LoginModules.  Each LoginModule is initialized with
a Subject, a CallbackHandler, shared
LoginModule state, and LoginModule-specific options.

The Subject represents the
Subject currently being authenticated and is updated
with relevant Credentials if authentication succeeds.
LoginModules use the CallbackHandler to
communicate with users.  The CallbackHandler may be
used to prompt for usernames and passwords, for example.
Note that the CallbackHandler may be null.  LoginModules
which absolutely require a CallbackHandler to authenticate
the Subject may throw a LoginException.
LoginModules optionally use the shared state to share information
or data among themselves.

 The LoginModule-specific options represent the options
configured for this LoginModule by an administrator or user
in the login Configuration.
The 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.  Options are defined using a key-value syntax,
such as debug=true.  The LoginModule
stores the options as a Map so that the values may
be retrieved using the key.  Note that there is no limit to the number
of options a LoginModule chooses to define.

 The calling application sees the authentication process as a single
operation.  However, the authentication process within the
LoginModule proceeds in two distinct phases.
In the first phase, the LoginModule's
login method gets invoked by the LoginContext's
login method.  The login
method for the LoginModule then performs
the actual authentication (prompt for and verify a password for example)
and saves its authentication status as private state
information.  Once finished, the LoginModule's login
method either returns true (if it succeeded) or
false (if it should be ignored), or throws a
LoginException to specify a failure.
In the failure case, the LoginModule must not retry the
authentication or introduce delays.  The responsibility of such tasks
belongs to the application.  If the application attempts to retry
the authentication, the LoginModule's login method will be
called again.

 In the second phase, if the LoginContext's overall authentication
succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL
LoginModules succeeded), then the commit
method for the LoginModule gets invoked.
The commit method for a LoginModule checks its
privately saved state to see if its own authentication succeeded.
If the overall LoginContext authentication succeeded
and the LoginModule's own authentication succeeded, then the
commit method associates the relevant
Principals (authenticated identities) and Credentials (authentication data
such as cryptographic keys) with the Subject
located within the LoginModule.

 If the LoginContext's overall authentication failed (the relevant
REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed),
then the abort method for each LoginModule
gets invoked.  In this case, the LoginModule removes/destroys
any authentication state originally saved.

 Logging out a Subject involves only one phase.
The LoginContext invokes the LoginModule's logout
method.  The logout method for the LoginModule
then performs the logout procedures, such as removing Principals or
Credentials from the Subject or logging session information.

 A LoginModule implementation must have a constructor with
no arguments.  This allows classes which load the LoginModule
to instantiate it.

 Subject subject;
 Principal principal;
 Object credential;

 // add a Principal and credential to the Subject
 subject.getPrincipals().add(principal);
 subject.getPublicCredentials().add(credential);

 A Subject represents a grouping of related information
for a single entity, such as a person.
Such information includes the Subject's identities as well as
its security-related attributes
(passwords and cryptographic keys, for example).

 Subjects may potentially have multiple identities.
Each identity is represented as a Principal
within the Subject.  Principals simply bind names to a
Subject.  For example, a Subject that happens
to be a person, Alice, might have two Principals:
one which binds "Alice Bar", the name on her driver license,
to the Subject, and another which binds,
"999-99-9999", the number on her student identification card,
to the Subject.  Both Principals refer to the same
Subject even though each has a different name.

 A Subject may also own security-related attributes,
which are referred to as credentials.
Sensitive credentials that require special protection, such as
private cryptographic keys, are stored within a private credential
Set.  Credentials intended to be shared, such as
public key certificates or Kerberos server tickets are stored
within a public credential Set.  Different permissions
are required to access and modify the different credential Sets.

 To retrieve all the Principals associated with a Subject,
invoke the getPrincipals method.  To retrieve
all the public or private credentials belonging to a Subject,
invoke the getPublicCredentials method or
getPrivateCredentials method, respectively.
To modify the returned Set of Principals and credentials,
use the methods defined in the Set class.
For example:


     Subject subject;
     Principal principal;
     Object credential;

     // add a Principal and credential to the Subject
     subject.getPrincipals().add(principal);
     subject.getPublicCredentials().add(credential);

 This Subject class implements Serializable.
While the Principals associated with the Subject are serialized,
the credentials associated with the Subject are not.
Note that the java.security.Principal class
does not implement Serializable.  Therefore all concrete
Principal implementations associated with Subjects
must implement Serializable.

A SubjectDomainCombiner updates ProtectionDomains
with Principals from the Subject associated with this
SubjectDomainCombiner.

 This class represents an X.500 Principal.
X500Principals are represented by distinguished names such as
"CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US".

 This class can be instantiated by using a string representation
of the distinguished name, or by using the ASN.1 DER encoded byte
representation of the distinguished name.  The current specification
for the string representation of a distinguished name is defined in
RFC 2253: Lightweight
Directory Access Protocol (v3): UTF-8 String Representation of
Distinguished Names. This class, however, accepts string formats from
both RFC 2253 and RFC 1779:
A String Representation of Distinguished Names, and also recognizes
attribute type keywords whose OIDs (Object Identifiers) are defined in
RFC 3280: Internet X.509
Public Key Infrastructure Certificate and CRL Profile.

 The string representation for this X500Principal
can be obtained by calling the getName methods.

 Note that the getSubjectX500Principal and
getIssuerX500Principal methods of
X509Certificate return X500Principals representing the
issuer and subject fields of the certificate.

 This class represents an X500PrivateCredential.
It associates an X.509 certificate, corresponding private key and the
KeyStore alias used to reference that exact key pair in the KeyStore.
This enables looking up the private credentials for an X.500 principal
in a subject.

Abstract class for managing a variety of identity certificates.
An identity certificate is a guarantee by a principal that
a public key is that of another principal.  (A principal represents
an entity such as an individual user, a group, or a corporation.)

This class is an abstraction for certificates that have different
formats but important common uses.  For example, different types of
certificates, such as X.509 and PGP, share general certificate
functionality (like encoding and verifying) and
some types of information (like a public key).

X.509, PGP, and SDSI certificates can all be implemented by
subclassing the Certificate class, even though they contain different
sets of information, and they store and retrieve the information in
different ways.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

Certificate Encoding Exception. This is thrown whenever an error
occurs whilst attempting to encode a certificate.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

This exception indicates one of a variety of certificate problems.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

Certificate Expired Exception. This is thrown whenever the current
Date or the specified Date is after the
notAfter date/time specified in the validity period
of the certificate.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

Certificate is not yet valid exception. This is thrown whenever
the current Date or the specified Date
is before the notBefore date/time in the Certificate
validity period.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

Certificate Parsing Exception. This is thrown whenever
invalid DER encoded certificate is parsed or unsupported DER features
are found in the Certificate.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

Abstract class for X.509 v1 certificates. This provides a standard
way to access all the version 1 attributes of an X.509 certificate.
Attributes that are specific to X.509 v2 or v3 are not available
through this interface. Future API evolution will provide full access to
complete X.509 v3 attributes.

The basic X.509 format was defined by
ISO/IEC and ANSI X9 and is described below in ASN.1:


Certificate  ::=  SEQUENCE  {
    tbsCertificate       TBSCertificate,
    signatureAlgorithm   AlgorithmIdentifier,
    signature            BIT STRING  }

These certificates are widely used to support authentication and
other functionality in Internet security systems. Common applications
include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
code signing for trusted software distribution, and Secure Electronic
Transactions (SET).

These certificates are managed and vouched for by Certificate
Authorities (CAs). CAs are services which create certificates by
placing data in the X.509 standard format and then digitally signing
that data. CAs act as trusted third parties, making introductions
between principals who have no direct knowledge of each other.
CA certificates are either signed by themselves, or by some other
CA such as a "root" CA.

The ASN.1 definition of tbsCertificate is:


TBSCertificate  ::=  SEQUENCE  {
    version         [0]  EXPLICIT Version DEFAULT v1,
    serialNumber         CertificateSerialNumber,
    signature            AlgorithmIdentifier,
    issuer               Name,
    validity             Validity,
    subject              Name,
    subjectPublicKeyInfo SubjectPublicKeyInfo,
    }

Here is sample code to instantiate an X.509 certificate:


InputStream inStream = new FileInputStream("fileName-of-cert");
X509Certificate cert = X509Certificate.getInstance(inStream);
inStream.close();
OR


byte[] certData = <certificate read from a file, say>
X509Certificate cert = X509Certificate.getInstance(certData);

In either case, the code that instantiates an X.509 certificate
consults the value of the cert.provider.x509v1 security property
to locate the actual implementation or instantiates a default implementation.

The cert.provider.x509v1 property is set to a default
implementation for X.509 such as:


cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl

The value of this cert.provider.x509v1 property has to be
changed to instantiate another implementation. If this security
property is not set, a default implementation will be used.
Currently, due to possible security restrictions on access to
Security properties, this value is looked up and cached at class
initialization time and will fallback on a default implementation if
the Security property is not accessible.

Note: The classes in the package javax.security.cert
exist for compatibility with earlier versions of the
Java Secure Sockets Extension (JSSE). New applications should instead
use the standard Java SE certificate classes located in
java.security.cert.

This exception is thrown by a SASL mechanism implementation
to indicate that the SASL
exchange has failed due to reasons related to authentication, such as
an invalid identity, passphrase, or key.

Note that the lack of an AuthenticationException does not mean that
the failure was not due to an authentication error.  A SASL mechanism
implementation might throw the more general SaslException instead of
AuthenticationException if it is unable to determine the nature
of the failure, or if does not want to disclose the nature of
the failure, for example, due to security reasons.

This callback is used by SaslServer to determine whether
one entity (identified by an authenticated authentication id)
can act on
behalf of another entity (identified by an authorization id).

This callback is used by SaslClient and SaslServer
to retrieve realm information.

This callback is used by SaslClient and SaslServer
to obtain a realm given a list of realm choices.

A static class for creating SASL clients and servers.

This class defines the policy of how to locate, load, and instantiate
SASL clients and servers.

For example, an application or library gets a SASL client by doing
something like:


SaslClient sc = Sasl.createSaslClient(mechanisms,
    authorizationId, protocol, serverName, props, callbackHandler);
It can then proceed to use the instance to create an authentication connection.

Similarly, a server gets a SASL server by using code that looks as follows:


SaslServer ss = Sasl.createSaslServer(mechanism,
    protocol, serverName, props, callbackHandler);

 // Use SaslClient.wrap() and SaslClient.unwrap() for future
 // communication with server
 ldap.in = new SecureInputStream(sc, ldap.in);
 ldap.out = new SecureOutputStream(sc, ldap.out);

Performs SASL authentication as a client.

A protocol library such as one for LDAP gets an instance of this
class in order to perform authentication defined by a specific SASL
mechanism. Invoking methods on the SaslClient instance
process challenges and create responses according to the SASL
mechanism implemented by the SaslClient.
As the authentication proceeds, the instance
encapsulates the state of a SASL client's authentication exchange.

Here's an example of how an LDAP library might use a SaslClient.
It first gets an instance of a SaslClient:


SaslClient sc = Sasl.createSaslClient(mechanisms,
    authorizationId, protocol, serverName, props, callbackHandler);
It can then proceed to use the client for authentication.
For example, an LDAP library might use the client as follows:


// Get initial response and send to server
byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
    null);
LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
while (!sc.isComplete() &&
    (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
    response = sc.evaluateChallenge(res.getBytes());
    if (res.status == SUCCESS) {
        // we're done; don't expect to send another BIND
        if (response != null) {
            throw new SaslException(
                "Protocol error: attempting to send response after completion");
        }
        break;
    }
    res = ldap.sendBindRequest(dn, sc.getName(), response);
}
if (sc.isComplete() && res.status == SUCCESS) {
   String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
   if (qop != null
       && (qop.equalsIgnoreCase("auth-int")
           || qop.equalsIgnoreCase("auth-conf"))) {

     // Use SaslClient.wrap() and SaslClient.unwrap() for future
     // communication with server
     ldap.in = new SecureInputStream(sc, ldap.in);
     ldap.out = new SecureOutputStream(sc, ldap.out);
   }
}

If the mechanism has an initial response, the library invokes
evaluateChallenge() with an empty
challenge and to get initial response.
Protocols such as IMAP4, which do not include an initial response with
their first authentication command to the server, initiates the
authentication without first calling hasInitialResponse()
or evaluateChallenge().
When the server responds to the command, it sends an initial challenge.
For a SASL mechanism in which the client sends data first, the server should
have issued a challenge with no data. This will then result in a call
(on the client) to evaluateChallenge() with an empty challenge.

An interface for creating instances of SaslClient.
A class that implements this interface
must be thread-safe and handle multiple simultaneous
requests. It must also have a public constructor that accepts no
argument.

This interface is not normally accessed directly by a client, which will use the
Sasl static methods
instead. However, a particular environment may provide and install a
new or different SaslClientFactory.

This class represents an error that has occurred when using SASL.

 // Use SaslServer.wrap() and SaslServer.unwrap() for future
 // communication with client
 ldap.in = new SecureInputStream(ss, ldap.in);
 ldap.out = new SecureOutputStream(ss, ldap.out);

Performs SASL authentication as a server.

A server such an LDAP server gets an instance of this
class in order to perform authentication defined by a specific SASL
mechanism. Invoking methods on the SaslServer instance
generates challenges according to the SASL
mechanism implemented by the SaslServer.
As the authentication proceeds, the instance
encapsulates the state of a SASL server's authentication exchange.

Here's an example of how an LDAP server might use a SaslServer.
It first gets an instance of a SaslServer for the SASL mechanism
requested by the client:


SaslServer ss = Sasl.createSaslServer(mechanism,
    "ldap", myFQDN, props, callbackHandler);
It can then proceed to use the server for authentication.
For example, suppose the LDAP server received an LDAP BIND request
containing the name of the SASL mechanism and an (optional) initial
response. It then might use the server as follows:


while (!ss.isComplete()) {
    try {
        byte[] challenge = ss.evaluateResponse(response);
        if (ss.isComplete()) {
            status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
        } else {
            status = ldap.sendBindResponse(mechanism, challenge,
                  SASL_BIND_IN_PROGRESS);
            response = ldap.readBindRequest();
        }
    } catch (SaslException e) {
         status = ldap.sendErrorResponse(e);
         break;
    }
}
if (ss.isComplete() && status == SUCCESS) {
   String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
   if (qop != null
       && (qop.equalsIgnoreCase("auth-int")
           || qop.equalsIgnoreCase("auth-conf"))) {

     // Use SaslServer.wrap() and SaslServer.unwrap() for future
     // communication with client
     ldap.in = new SecureInputStream(ss, ldap.in);
     ldap.out = new SecureOutputStream(ss, ldap.out);
   }
}

An interface for creating instances of SaslServer.
A class that implements this interface
must be thread-safe and handle multiple simultaneous
requests. It must also have a public constructor that accepts no
argument.

This interface is not normally accessed directly by a server, which will use the
Sasl static methods
instead. However, a particular environment may provide and install a
new or different SaslServerFactory.