Align with r7602, and adjust some formatting

Mark Craig

04.48.2012 18a84d42a1bbdf7be91abb52b6b554f7964ea68b

Align with r7602, and adjust some formatting

 opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011 ForgeRock AS
  !      Copyright 2011-2012 ForgeRock AS
  !    
-->
<chapter xml:id='chap-authenticating'
@@ -50,7 +50,7 @@
  <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> with the
  password <literal>hifalutin</literal>. An example is provided with the
  OpenDJ LDAP SDK examples in
  <filename>org.forgerock.opendj.examples.simpleauth.Main.java</filename>.</para>
  <filename>org.forgerock.opendj.examples.SimpleAuth.java</filename>.</para>
  
  <para>The directory stores the password value used for simple authentication
  in binary form on the <literal>userPassword</literal> attribute of the entry.
@@ -67,38 +67,39 @@
  the directory determines authorization for operations on the connection
  based on the users identity.</para>
  
  <programlisting language="java">  /**
   * Authenticate over LDAP.
   */
  private static void connect()
  {
    final LDAPConnectionFactory factory = new LDAPConnectionFactory(
      host, port);
    Connection connection = null;
  <programlisting language="java">
/**
 * Authenticate over LDAP.
 */
private static void connect()
{
  final LDAPConnectionFactory factory = new LDAPConnectionFactory(
    host, port);
  Connection connection = null;

    try
    {
      connection = factory.getConnection();
      connection.bind(bindDN, bindPassword.toCharArray());
      System.out.println("Authenticated as " + bindDN + ".");
    }
    catch (final ErrorResultException e)
    {
      System.err.println(e.getMessage());
      System.exit(e.getResult().getResultCode().intValue());
      return;
    }
    catch (final InterruptedException e)
    {
      System.err.println(e.getMessage());
      System.exit(ResultCode.CLIENT_SIDE_USER_CANCELLED.intValue());
      return;
    }
    finally
    {
      if (connection != null) connection.close();
    }
  }</programlisting>
  try
  {
    connection = factory.getConnection();
    connection.bind(bindDN, bindPassword.toCharArray());
    System.out.println("Authenticated as " + bindDN + ".");
  }
  catch (final ErrorResultException e)
  {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
  }
  catch (final InterruptedException e)
  {
    System.err.println(e.getMessage());
    System.exit(ResultCode.CLIENT_SIDE_USER_CANCELLED.intValue());
    return;
  }
  finally
  {
    if (connection != null) connection.close();
  }
}</programlisting>
  
  <para>If the password values do not match, a directory might nevertheless
  authenticate the client application. The LDAP specifications say that in this
@@ -122,18 +123,19 @@
  set up a trust manager that trusts all certificates.</para>
  
  <para>The following example is an excerpt from the OpenDJ LDAP SDK example,
  <filename>org.forgerock.opendj.examples.simpleauth.Main.java</filename>.</para>
  <filename>org.forgerock.opendj.examples.SimpleAuth.java</filename>.</para>
  
  <programlisting language="java">  private static LDAPOptions getTrustAllOptions()
    throws GeneralSecurityException
  {
    LDAPOptions lo = new LDAPOptions();
    SSLContext sslContext = new SSLContextBuilder()
      .setTrustManager(TrustManagers.trustAll()).getSSLContext();
    lo.setSSLContext(sslContext);
    lo.setUseStartTLS(useStartTLS);
    return lo;
  }</programlisting>
  <programlisting language="java">
private static LDAPOptions getTrustAllOptions()
  throws GeneralSecurityException
{
  LDAPOptions lo = new LDAPOptions();
  SSLContext sslContext = new SSLContextBuilder()
    .setTrustManager(TrustManagers.trustAll()).getSSLContext();
  lo.setSSLContext(sslContext);
  lo.setUseStartTLS(useStartTLS);
  return lo;
}</programlisting>
  
  <para>A more secure and extensive SSL context would include a trust manager
  using a trust store and trust manager methods to check server certificates.
@@ -146,45 +148,46 @@
  to the LDAP connection factory, and that you handle the potential security
  exception involved in setting up the SSL context.</para>
  
  <programlisting language="java">  /**
   * Perform authentication over a secure connection, trusting all server
   * certificates.
   */
  private static void trustAllConnect()
  {
    Connection connection = null;
  <programlisting language="java">
/**
 * Perform authentication over a secure connection, trusting all server
 * certificates.
 */
private static void trustAllConnect()
{
  Connection connection = null;

    try
    {
      final LDAPConnectionFactory factory =
          new LDAPConnectionFactory(host, port, getTrustAllOptions());
      connection = factory.getConnection();
      connection.bind(bindDN, bindPassword.toCharArray());
      System.out.println("Authenticated as " + bindDN + ".");
    }
    catch (final ErrorResultException e)
    {
      System.err.println(e.getMessage());
      System.exit(e.getResult().getResultCode().intValue());
      return;
    }
    catch (final InterruptedException e)
    {
      System.err.println(e.getMessage());
      System.exit(ResultCode.CLIENT_SIDE_USER_CANCELLED.intValue());
      return;
    }
    catch (final GeneralSecurityException e)
    {
      System.err.println(e.getMessage());
      System.exit(ResultCode.CLIENT_SIDE_CONNECT_ERROR.intValue());
    }
    finally
    {
      if (connection != null)
        connection.close();
    }
  }</programlisting>
  try
  {
    final LDAPConnectionFactory factory =
        new LDAPConnectionFactory(host, port, getTrustAllOptions());
    connection = factory.getConnection();
    connection.bind(bindDN, bindPassword.toCharArray());
    System.out.println("Authenticated as " + bindDN + ".");
  }
  catch (final ErrorResultException e)
  {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
  }
  catch (final InterruptedException e)
  {
    System.err.println(e.getMessage());
    System.exit(ResultCode.CLIENT_SIDE_USER_CANCELLED.intValue());
    return;
  }
  catch (final GeneralSecurityException e)
  {
    System.err.println(e.getMessage());
    System.exit(ResultCode.CLIENT_SIDE_CONNECT_ERROR.intValue());
  }
  finally
  {
    if (connection != null)
      connection.close();
  }
}</programlisting>
 </section>
 
 <section xml:id="sasl-auth">
@@ -222,11 +225,11 @@
  ID as the authorization ID that identifies the user who performs operations.
  The SASL PLAIN mechanism itself does not secure the connection, so the
  example uses StartTLS. The example is provided with the OpenDJ LDAP SDK
  examples in
  <filename>org.forgerock.opendj.examples.saslauth.Main.java</filename>.
  examples in <filename>org.forgerock.opendj.examples.SASLAuth.java</filename>.
  The following excerpt shows the core of the bind process.</para>
  
  <programlisting language="java">try
  <programlisting language="java">
try
{
  final LDAPConnectionFactory factory =
      new LDAPConnectionFactory(host, port, getTrustAllOptions());
@@ -252,4 +255,4 @@
  <literal>uid</literal> values. If you use another directory server, you might
  have to configure how it maps user IDs to user entries.</para>
 </section>
</chapter>
</chapter>