diff -r b0dd05ec3db1 -r bab15bbe2ca3 jdk/src/jdk.security.auth/share/classes/com/sun/security/auth/module/LdapLoginModule.java --- a/jdk/src/jdk.security.auth/share/classes/com/sun/security/auth/module/LdapLoginModule.java Tue Apr 28 11:10:45 2015 -0700 +++ b/jdk/src/jdk.security.auth/share/classes/com/sun/security/auth/module/LdapLoginModule.java Wed Apr 29 17:29:14 2015 +0400 @@ -70,8 +70,8 @@ * conjunction with a specified search filter. * If successful then authentication is attempted using the user's * distinguished name and the supplied password. - * To enable this mode, set the userFilter option and omit the - * authIdentity option. + * To enable this mode, set the {@code userFilter} option and omit the + * {@code authIdentity} option. * Use search-first mode when the user's distinguished name is not * known in advance. * @@ -79,22 +79,22 @@ * supplied username and password and then the LDAP directory is searched. * If authentication is successful then a search is performed using the * supplied username in conjunction with a specified search filter. - * To enable this mode, set the authIdentity and the - * userFilter options. + * To enable this mode, set the {@code authIdentity} and the + * {@code userFilter} options. * Use authentication-first mode when accessing an LDAP directory * that has been configured to disallow anonymous searches. * *

In authentication-only mode, authentication is attempted using the * supplied username and password. The LDAP directory is not searched because * the user's distinguished name is already known. - * To enable this mode, set the authIdentity option to a valid - * distinguished name and omit the userFilter option. + * To enable this mode, set the {@code authIdentity} option to a valid + * distinguished name and omit the {@code userFilter} option. * Use authentication-only mode when the user's distinguished name is * known in advance. * *

The following option is mandatory and must be specified in this * module's login {@link Configuration}: - *

+ *
*
*
userProvider=ldap_urls *
@@ -106,7 +106,7 @@ * When several LDAP URLs are specified then each is attempted, * in turn, until the first successful connection is established. * Spaces in the distinguished name component of the URL must be escaped - * using the standard mechanism of percent character ('%') + * using the standard mechanism of percent character ('{@code %}') * followed by two hexadecimal digits (see {@link java.net.URI}). * Query components must also be omitted from the URL. * @@ -120,33 +120,33 @@ * *

This module also recognizes the following optional {@link Configuration} * options: - *

+ *
*
*
userFilter=ldap_filter
*
This option specifies the search filter to use to locate a user's * entry in the LDAP directory. It is used to determine a user's * distinguished name. - * ldap_filter is an LDAP filter string + * {@code ldap_filter} is an LDAP filter string * (RFC 2254). - * If it contains the special token "{USERNAME}" + * If it contains the special token "{@code {USERNAME}}" * then that token will be replaced with the supplied username value * before the filter is used to search the directory.
* *
authIdentity=auth_id
*
This option specifies the identity to use when authenticating a user * to the LDAP directory. - * auth_id may be an LDAP distinguished name string + * {@code auth_id} may be an LDAP distinguished name string * (RFC 2253) or some * other string name. - * It must contain the special token "{USERNAME}" + * It must contain the special token "{@code {USERNAME}}" * which will be replaced with the supplied username value before the * name is used for authentication. * Note that if this option does not contain a distinguished name then - * the userFilter option must also be specified.
+ * the {@code userFilter} option must also be specified.
* *
authzIdentity=authz_id
*
This option specifies an authorization identity for the user. - * authz_id is any string name. + * {@code authz_id} is any string name. * If it comprises a single special token with curly braces then * that token is treated as a attribute name and will be replaced with a * single value of that attribute from the user's LDAP entry. @@ -156,23 +156,23 @@ * is created using the authorization identity and it is associated with * the current {@link Subject}.
* - *
useSSL
- *
if false, this module does not establish an SSL connection + *
{@code useSSL}
+ *
if {@code false}, this module does not establish an SSL connection * to the LDAP server before attempting authentication. SSL is used to * protect the privacy of the user's password because it is transmitted * in the clear over LDAP. * By default, this module uses SSL.
* - *
useFirstPass
- *
if true, this module retrieves the username and password + *
{@code useFirstPass}
+ *
if {@code true}, this module retrieves the username and password * from the module's shared state, using "javax.security.auth.login.name" * and "javax.security.auth.login.password" as the respective keys. The * retrieved values are used for authentication. If authentication fails, * no attempt for a retry is made, and the failure is reported back to * the calling application.
* - *
tryFirstPass
- *
if true, this module retrieves the username and password + *
{@code tryFirstPass}
+ *
if {@code true}, this module retrieves the username and password * from the module's shared state, using "javax.security.auth.login.name" * and "javax.security.auth.login.password" as the respective keys. The * retrieved values are used for authentication. If authentication fails, @@ -181,8 +181,8 @@ * authentication fails, the failure is reported back to the calling * application.
* - *
storePass
- *
if true, this module stores the username and password + *
{@code storePass}
+ *
if {@code true}, this module stores the username and password * obtained from the {@link CallbackHandler} in the module's shared state, * using * "javax.security.auth.login.name" and @@ -190,13 +190,13 @@ * not performed if existing values already exist for the username and * password in the shared state, or if authentication fails.
* - *
clearPass
- *
if true, this module clears the username and password + *
{@code clearPass}
+ *
if {@code true}, this module clears the username and password * stored in the module's shared state after both phases of authentication * (login and commit) have completed.
* - *
debug
- *
if true, debug messages are displayed on the standard + *
{@code debug}
+ *
if {@code true}, debug messages are displayed on the standard * output stream. *
*
@@ -209,36 +209,36 @@ * Note that the following four JNDI properties are set by this module directly * and are ignored if also present in the configuration: *
    - *
  • java.naming.provider.url - *
  • java.naming.security.principal - *
  • java.naming.security.credentials - *
  • java.naming.security.protocol + *
  • {@code java.naming.provider.url} + *
  • {@code java.naming.security.principal} + *
  • {@code java.naming.security.credentials} + *
  • {@code java.naming.security.protocol} *
* *

* Three sample {@link Configuration}s are shown below. * The first one activates search-first mode. It identifies the LDAP server - * and specifies that users' entries be located by their uid and - * objectClass attributes. It also specifies that an identity - * based on the user's employeeNumber attribute should be created. + * and specifies that users' entries be located by their {@code uid} and + * {@code objectClass} attributes. It also specifies that an identity + * based on the user's {@code employeeNumber} attribute should be created. * The second one activates authentication-first mode. It requests that the * LDAP server be located dynamically, that authentication be performed using * the supplied username directly but without the protection of SSL and that * users' entries be located by one of three naming attributes and their - * objectClass attribute. + * {@code objectClass} attribute. * The third one activates authentication-only mode. It identifies alternative * LDAP servers, it specifies the distinguished name to use for * authentication and a fixed identity to use for authorization. No directory * search is performed. * - * 

+ * 
{@literal
  *
  *     ExampleApplication {
  *         com.sun.security.auth.module.LdapLoginModule REQUIRED
- *             userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
- *             userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
- *             authzIdentity="{EMPLOYEENUMBER}"
- *             debug=true;
+ *              userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
+ *              userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
+ *              authzIdentity="{EMPLOYEENUMBER}"
+ *              debug=true;
  *     };
  *
  *     ExampleApplication {
@@ -258,7 +258,7 @@
  *             debug=true;
  *     };
  *
- * 

+ * }
* *
*
Note:
@@ -282,7 +282,6 @@ * caller-specified {@link Configuration} then the application * must be granted the permissions required by the {@link LoginModule}. * This module requires the following two permissions: - *

*

    *
  • The {@link SocketPermission} to connect to an LDAP server. *
  • The {@link AuthPermission} to modify the set of {@link Principal}s @@ -373,15 +372,15 @@ private SearchControls constraints = null; /** - * Initialize this LoginModule. + * Initialize this {@code LoginModule}. * - * @param subject the Subject to be authenticated. - * @param callbackHandler a CallbackHandler to acquire the + * @param subject the {@code Subject} to be authenticated. + * @param callbackHandler a {@code CallbackHandler} to acquire the * username and password. - * @param sharedState shared LoginModule state. + * @param sharedState shared {@code LoginModule} state. * @param options options specified in the login - * Configuration for this particular - * LoginModule. + * {@code Configuration} for this particular + * {@code LoginModule}. */ // Unchecked warning from (Map)sharedState is safe // since javax.security.auth.login.LoginContext passes a raw HashMap. @@ -492,10 +491,10 @@ *

    Acquire the user's credentials and verify them against the * specified LDAP directory. * - * @return true always, since this LoginModule + * @return true always, since this {@code LoginModule} * should not be ignored. * @exception FailedLoginException if the authentication fails. - * @exception LoginException if this LoginModule + * @exception LoginException if this {@code LoginModule} * is unable to perform the authentication. */ public boolean login() throws LoginException { @@ -593,10 +592,10 @@ * *

    If this LoginModule's own authentication attempt * succeeded (checked by retrieving the private state saved by the - * login method), then this method associates an - * LdapPrincipal and one or more UserPrincipals - * with the Subject located in the - * LoginModule. If this LoginModule's own + * {@code login} method), then this method associates an + * {@code LdapPrincipal} and one or more {@code UserPrincipal}s + * with the {@code Subject} located in the + * {@code LoginModule}. If this LoginModule's own * authentication attempted failed, then this method removes * any state that was originally saved. * @@ -662,7 +661,7 @@ * *

    If this LoginModule's own authentication attempt * succeeded (checked by retrieving the private state saved by the - * login and commit methods), + * {@code login} and {@code commit} methods), * then this method cleans up any state that was originally saved. * * @exception LoginException if the abort fails. @@ -697,10 +696,10 @@ * Logout a user. * *

    This method removes the Principals - * that were added by the commit method. + * that were added by the {@code commit} method. * * @exception LoginException if the logout fails. - * @return true in all cases since this LoginModule + * @return true in all cases since this {@code LoginModule} * should not be ignored. */ public boolean logout() throws LoginException {