From fe5a31b7b24cdac9e8534c4b3661036f6ce969cc Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 09 Jul 2013 06:35:23 +0000
Subject: [PATCH] Backport r9195
---
src/main/docbkx/install-guide/chap-install-cli.xml | 14 ++++
src/main/docbkx/release-notes/chap-whats-new.xml | 4 +
src/main/docbkx/admin-guide/appendix-rest2ldap.xml | 106 ++++++++++++++++++++++++++++++++++-
3 files changed, 119 insertions(+), 5 deletions(-)
diff --git a/src/main/docbkx/admin-guide/appendix-rest2ldap.xml b/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
index 8ecf7c6..bf1efc1 100644
--- a/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
+++ b/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>
diff --git a/src/main/docbkx/install-guide/chap-install-cli.xml b/src/main/docbkx/install-guide/chap-install-cli.xml
index c5f6737..9941798 100644
--- a/src/main/docbkx/install-guide/chap-install-cli.xml
+++ b/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>
diff --git a/src/main/docbkx/release-notes/chap-whats-new.xml b/src/main/docbkx/release-notes/chap-whats-new.xml
index 2f79a91..509dd48 100644
--- a/src/main/docbkx/release-notes/chap-whats-new.xml
+++ b/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>
--
Gitblit v1.10.0