Backport r9195

Mark Craig

09.35.2013 fe5a31b7b24cdac9e8534c4b3661036f6ce969cc

Backport r9195

The doc change backported here covers the improvement made with OPENDJ-1033, which adds SSL and StartTLS support for the REST LDAP gateway.

 src/main/docbkx/admin-guide/appendix-rest2ldap.xml

@@ -28,7 +28,7 @@
          xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
          xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
          xmlns:xlink='http://www.w3.org/1999/xlink'
        >
          xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>REST LDAP Configuration</title>
 <indexterm><primary>REST</primary></indexterm>
 <indexterm><primary>HTTP</primary></indexterm>
@@ -97,9 +97,36 @@
           <literal>connectionPoolSize</literal> connections to the
           servers.</para>

           <para>Default: 10</para>
           <para>Default: 24</para>

           <programlisting language="javascript">"connectionPoolSize": 10</programlisting>
           <programlisting language="javascript">"connectionPoolSize": 24</programlisting>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"connectionSecurity" (optional)</term>
          <listitem>
           <para>Whether connections to LDAP servers should be secured by using
           SSL or StartTLS. The following values are supported.</para>

           <itemizedlist>
            <listitem>
             <para>"none" (default) means connections use plain LDAP and are
             not secured.</para>
            </listitem>

            <listitem>
             <para>"ssl" means connections are secured using LDAPS.</para>
            </listitem>

            <listitem>
             <para>"startTLS" means connections are secured using LDAP and
             StartTLS.</para>
            </listitem>
           </itemizedlist>

            <para>If you set "connectionSecurity", also review the
            "trustManager" and "fileBasedTrustManager*" settings.</para>
          </listitem>
         </varlistentry>

@@ -117,6 +144,49 @@
         </varlistentry>

         <varlistentry>
          <term>"fileBasedTrustManagerFile" (optional)</term>
          <listitem>
           <para>If "trustManager" is set to "file", then this setting
           configures the location of the trust store file.</para>

           <para>Default: "/path/to/truststore"</para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"fileBasedTrustManagerPassword" (optional)</term>
          <listitem>
           <para>If "trustManager" is set to "file", then this setting
           specifies the trust store password.</para>

           <para>Default: "password"</para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"fileBasedTrustManagerType" (optional)</term>
          <listitem>
           <para>If "trustManager" is set to "file", then this setting
           configures the format for the data in the trust store file specified
           by the "fileBasedTrustManagerFile" setting. Formats include the
           following, though other implementations might be supported as well
           depending on the Java environment.</para>

           <itemizedlist>
            <listitem>
             <para>"JKS" (default) specifies Java Key Store format.</para>
            </listitem>

            <listitem>
             <para>"PKCS12" specifies Public-Key Cryptography Standards 12
             format.</para>
            </listitem>
           </itemizedlist>

          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"primaryLDAPServers" (required)</term>
          <listitem>
           <para>The gateway accesses this array of LDAP servers before failing
@@ -164,6 +234,36 @@
           <para>No secondary LDAP servers are configured by default.</para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"trustManager" (optional)</term>
          <listitem>
           <para>If "connectionSecurity" is set to "ssl" or "startTLS", then
           this setting configures how the LDAP servers are trusted. This
           setting is ignored if "connectionSecurity" is set to "none".</para>

           <itemizedlist>
            <listitem>
             <para>"file" means trust the LDAP server certificate if it is
             signed by a Certificate Authority (CA) trusted according to the
             file-based trust store configured with the "fileBasedTrustManager*"
             settings.</para>
            </listitem>

            <listitem>
             <para>"jvm" means trust the LDAP server certificate if it is signed
             by a CA trusted by the Java environment.</para>
            </listitem>

            <listitem>
             <para>"trustAll" (default) means blindly trust all LDAP server
             certificates.</para>
            </listitem>
           </itemizedlist>

          </listitem>
         </varlistentry>

        </variablelist>
       </listitem>
     </varlistentry>

 src/main/docbkx/install-guide/chap-install-cli.xml

@@ -737,9 +737,21 @@
   correctly match your directory data.</para>

   <para>For details on the configuration, see <link
   xlink:href="admin-guide#appendix-rest2ldap"
   xlink:href="admin-guide#appendix-rest2ldap" xlink:show="new"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
   Configuration</citetitle></link>.</para>

   <para>When connecting to directory servers over LDAPS or LDAP and StartTLS,
   you can configure the trust manager to use a file-based trust store for
   server certificates that the gateway should trust. This allows the gateway to
   validate server certificates signed for example by a Certificate Authority
   not recognized by the Java environment when setting up LDAPS or StartTLS
   connections. See <link xlink:show="new"
   xlink:href="admin-guide#setup-server-cert"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
   Secure Communications</citetitle></link> for an example showing how to use
   the <command>keytool</command> command to support a server certificate into
   a trust store file.</para>
  </step>

  <step>

 src/main/docbkx/release-notes/chap-whats-new.xml

@@ -48,7 +48,9 @@
     <para>OpenDJ REST LDAP gateway lets clients access directory data in remote
     LDAP servers over HTTP (<link xlink:show="new"
     xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-757"
     >OPENDJ-757</link>). See the procedure, <link xlink:show="new"
     >OPENDJ-757</link>, <link xlink:show="new"
     xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1033"
     >OPENDJ-1033</link>). See the procedure, <link xlink:show="new"
     xlink:href="install-guide#install-rest2ldap-servlet"
     xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Install
     OpenDJ REST LDAP Gateway</citetitle></link>, to get started.</para>