84  * respective {@code getPrincipals}, {@code getPublicCredentials},
  85  * and {@code getPrivateCredentials} methods.
  86  *
  87  * <p> To logout the Subject, the caller calls
  88  * the {@code logout} method.  As with the {@code login}
  89  * method, this {@code logout} method invokes the {@code logout}
  90  * method for the configured modules.
  91  *
  92  * <p> A LoginContext should not be used to authenticate
  93  * more than one Subject.  A separate LoginContext
  94  * should be used to authenticate each different Subject.
  95  *
  96  * <p> The following documentation applies to all LoginContext constructors:
  97  * <ol>
  98  *
  99  * <li> {@code Subject}
 100  * <ul>
 101  * <li> If the constructor has a Subject
 102  * input parameter, the LoginContext uses the caller-specified
 103  * Subject object.
 104  * <p>
 105  * <li> If the caller specifies a {@code null} Subject
 106  * and a {@code null} value is permitted,
 107  * the LoginContext instantiates a new Subject.
 108  * <p>
 109  * <li> If the constructor does <b>not</b> have a Subject
 110  * input parameter, the LoginContext instantiates a new Subject.
 111  * <p>
 112  * </ul>
 113  *
 114  * <li> {@code Configuration}
 115  * <ul>
 116  * <li> If the constructor has a Configuration
 117  * input parameter and the caller specifies a non-null Configuration,
 118  * the LoginContext uses the caller-specified Configuration.
 119  * <p>
 120  * If the constructor does <b>not</b> have a Configuration
 121  * input parameter, or if the caller specifies a {@code null}
 122  * Configuration object, the constructor uses the following call to
 123  * get the installed Configuration:
 124  * <pre>
 125  *      config = Configuration.getConfiguration();
 126  * </pre>
 127  * For both cases,
 128  * the <i>name</i> argument given to the constructor is passed to the
 129  * {@code Configuration.getAppConfigurationEntry} method.
 130  * If the Configuration has no entries for the specified <i>name</i>,
 131  * then the {@code LoginContext} calls
 132  * {@code getAppConfigurationEntry} with the name, "<i>other</i>"
 133  * (the default entry name).  If there is no entry for "<i>other</i>",
 134  * then a {@code LoginException} is thrown.
 135  * <p>
 136  * <li> When LoginContext uses the installed Configuration, the caller
 137  * requires the createLoginContext.<em>name</em> and possibly
 138  * createLoginContext.other AuthPermissions. Furthermore, the
 139  * LoginContext will invoke configured modules from within an
 140  * {@code AccessController.doPrivileged} call so that modules that
 141  * perform security-sensitive tasks (such as connecting to remote hosts,
 142  * and updating the Subject) will require the respective permissions, but
 143  * the callers of the LoginContext will not require those permissions.
 144  * <p>
 145  * <li> When LoginContext uses a caller-specified Configuration, the caller
 146  * does not require any createLoginContext AuthPermission.  The LoginContext
 147  * saves the {@code AccessControlContext} for the caller,
 148  * and invokes the configured modules from within an
 149  * {@code AccessController.doPrivileged} call constrained by that context.
 150  * This means the caller context (stored when the LoginContext was created)
 151  * must have sufficient permissions to perform any security-sensitive tasks
 152  * that the modules may perform.
 153  * <p>
 154  * </ul>
 155  *
 156  * <li> {@code CallbackHandler}
 157  * <ul>
 158  * <li> If the constructor has a CallbackHandler
 159  * input parameter, the LoginContext uses the caller-specified
 160  * CallbackHandler object.
 161  * <p>
 162  * <li> If the constructor does <b>not</b> have a CallbackHandler
 163  * input parameter, or if the caller specifies a {@code null}
 164  * CallbackHandler object (and a {@code null} value is permitted),
 165  * the LoginContext queries the
 166  * {@code auth.login.defaultCallbackHandler} security property for the
 167  * fully qualified class name of a default handler
 168  * implementation. If the security property is not set,
 169  * then the underlying modules will not have a
 170  * CallbackHandler for use in communicating
 171  * with users.  The caller thus assumes that the configured
 172  * modules have alternative means for authenticating the user.
 173  *
 174  * <p>
 175  * <li> When the LoginContext uses the installed Configuration (instead of
 176  * a caller-specified Configuration, see above),
 177  * then this LoginContext must wrap any
 178  * caller-specified or default CallbackHandler implementation
 179  * in a new CallbackHandler implementation
 180  * whose {@code handle} method implementation invokes the
 181  * specified CallbackHandler's {@code handle} method in a
 182  * {@code java.security.AccessController.doPrivileged} call
 183  * constrained by the caller's current {@code AccessControlContext}.
 184  * </ul>
 185  * </ol>
 186  *
 187  * @see java.security.Security
 188  * @see javax.security.auth.AuthPermission
 189  * @see javax.security.auth.Subject
 190  * @see javax.security.auth.callback.CallbackHandler
 191  * @see javax.security.auth.login.Configuration
 192  * @see javax.security.auth.spi.LoginModule
 193  * @see java.security.Security security properties
 194  */

  84  * respective {@code getPrincipals}, {@code getPublicCredentials},
  85  * and {@code getPrivateCredentials} methods.
  86  *
  87  * <p> To logout the Subject, the caller calls
  88  * the {@code logout} method.  As with the {@code login}
  89  * method, this {@code logout} method invokes the {@code logout}
  90  * method for the configured modules.
  91  *
  92  * <p> A LoginContext should not be used to authenticate
  93  * more than one Subject.  A separate LoginContext
  94  * should be used to authenticate each different Subject.
  95  *
  96  * <p> The following documentation applies to all LoginContext constructors:
  97  * <ol>
  98  *
  99  * <li> {@code Subject}
 100  * <ul>
 101  * <li> If the constructor has a Subject
 102  * input parameter, the LoginContext uses the caller-specified
 103  * Subject object.
 104  *
 105  * <li> If the caller specifies a {@code null} Subject
 106  * and a {@code null} value is permitted,
 107  * the LoginContext instantiates a new Subject.
 108  *
 109  * <li> If the constructor does <b>not</b> have a Subject
 110  * input parameter, the LoginContext instantiates a new Subject.
 111  * <p>
 112  * </ul>
 113  *
 114  * <li> {@code Configuration}
 115  * <ul>
 116  * <li> If the constructor has a Configuration
 117  * input parameter and the caller specifies a non-null Configuration,
 118  * the LoginContext uses the caller-specified Configuration.
 119  * <p>
 120  * If the constructor does <b>not</b> have a Configuration
 121  * input parameter, or if the caller specifies a {@code null}
 122  * Configuration object, the constructor uses the following call to
 123  * get the installed Configuration:
 124  * <pre>
 125  *      config = Configuration.getConfiguration();
 126  * </pre>
 127  * For both cases,
 128  * the <i>name</i> argument given to the constructor is passed to the
 129  * {@code Configuration.getAppConfigurationEntry} method.
 130  * If the Configuration has no entries for the specified <i>name</i>,
 131  * then the {@code LoginContext} calls
 132  * {@code getAppConfigurationEntry} with the name, "<i>other</i>"
 133  * (the default entry name).  If there is no entry for "<i>other</i>",
 134  * then a {@code LoginException} is thrown.
 135  *
 136  * <li> When LoginContext uses the installed Configuration, the caller
 137  * requires the createLoginContext.<em>name</em> and possibly
 138  * createLoginContext.other AuthPermissions. Furthermore, the
 139  * LoginContext will invoke configured modules from within an
 140  * {@code AccessController.doPrivileged} call so that modules that
 141  * perform security-sensitive tasks (such as connecting to remote hosts,
 142  * and updating the Subject) will require the respective permissions, but
 143  * the callers of the LoginContext will not require those permissions.
 144  *
 145  * <li> When LoginContext uses a caller-specified Configuration, the caller
 146  * does not require any createLoginContext AuthPermission.  The LoginContext
 147  * saves the {@code AccessControlContext} for the caller,
 148  * and invokes the configured modules from within an
 149  * {@code AccessController.doPrivileged} call constrained by that context.
 150  * This means the caller context (stored when the LoginContext was created)
 151  * must have sufficient permissions to perform any security-sensitive tasks
 152  * that the modules may perform.
 153  * <p>
 154  * </ul>
 155  *
 156  * <li> {@code CallbackHandler}
 157  * <ul>
 158  * <li> If the constructor has a CallbackHandler
 159  * input parameter, the LoginContext uses the caller-specified
 160  * CallbackHandler object.
 161  *
 162  * <li> If the constructor does <b>not</b> have a CallbackHandler
 163  * input parameter, or if the caller specifies a {@code null}
 164  * CallbackHandler object (and a {@code null} value is permitted),
 165  * the LoginContext queries the
 166  * {@code auth.login.defaultCallbackHandler} security property for the
 167  * fully qualified class name of a default handler
 168  * implementation. If the security property is not set,
 169  * then the underlying modules will not have a
 170  * CallbackHandler for use in communicating
 171  * with users.  The caller thus assumes that the configured
 172  * modules have alternative means for authenticating the user.
 173  *
 174  *
 175  * <li> When the LoginContext uses the installed Configuration (instead of
 176  * a caller-specified Configuration, see above),
 177  * then this LoginContext must wrap any
 178  * caller-specified or default CallbackHandler implementation
 179  * in a new CallbackHandler implementation
 180  * whose {@code handle} method implementation invokes the
 181  * specified CallbackHandler's {@code handle} method in a
 182  * {@code java.security.AccessController.doPrivileged} call
 183  * constrained by the caller's current {@code AccessControlContext}.
 184  * </ul>
 185  * </ol>
 186  *
 187  * @see java.security.Security
 188  * @see javax.security.auth.AuthPermission
 189  * @see javax.security.auth.Subject
 190  * @see javax.security.auth.callback.CallbackHandler
 191  * @see javax.security.auth.login.Configuration
 192  * @see javax.security.auth.spi.LoginModule
 193  * @see java.security.Security security properties
 194  */