directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fel...@apache.org
Subject svn commit: r985093 - in /directory/sandbox/felixk/apacheds-docs/src: docbkx-stylesheet/html/ docbkx/ main/resources/images/
Date Fri, 13 Aug 2010 04:48:39 GMT
Author: felixk
Date: Fri Aug 13 04:48:38 2010
New Revision: 985093

URL: http://svn.apache.org/viewvc?rev=985093&view=rev
Log:
Starting with Basic User Guide to docbook

Added:
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_certificate.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_keystore.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/studio_ssl.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_adressbook.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_1.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_2.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_directory_menu.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_open_adressbook.png   (with props)
Modified:
    directory/sandbox/felixk/apacheds-docs/src/docbkx-stylesheet/html/docbook.xsl
    directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx-stylesheet/html/docbook.xsl
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx-stylesheet/html/docbook.xsl?rev=985093&r1=985092&r2=985093&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx-stylesheet/html/docbook.xsl (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx-stylesheet/html/docbook.xsl Fri Aug 13 04:48:38 2010
@@ -35,5 +35,12 @@
   </xsl:template>
 
   <!-- Important links: - http://www.sagehill.net/docbookxsl/ - http://docbkx-tools.sourceforge.net/ -->
+  
+  <!--
+    TODO
+    - template match="warning", add image
+    - template match="caution", add image
+  
+   -->
 
 </xsl:stylesheet>
\ No newline at end of file

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml?rev=985093&r1=985092&r2=985093&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml Fri Aug 13 04:48:38 2010
@@ -8,9 +8,7 @@
   xmlns:ns3="http://www.w3.org/1999/xhtml"
   xml:lang="en">
   <title>Basic User's Guide</title>
-  <para>
-    <graphic
-      fileref="images/warning.gif" />
+  <warning>
     Work in progress
     Unfortunately the Basic User's Guide for ApacheDS 1.5 is not finished yet. We have started to move
     and revise the content, things
@@ -20,7 +18,7 @@
     <ulink
       url="http://directory.apache.org/apacheds/1.0/apacheds-v10-basic-users-guide.html">ApacheDS 1.0 Basic User's Guide</ulink>
     , which is currently more complete.
-  </para>
+  </warning>
   <section>
     <title>About this guide</title>
     <para>Getting started. Learn how to download and install ApacheDS 1.5 on different platforms, connect to it with

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml?rev=985093&r1=985092&r2=985093&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml Fri Aug 13 04:48:38 2010
@@ -94,8 +94,8 @@
         Native installers are available for Windows, MacOS and Solaris (both SPARC and intel platform), but in fact the
         set of possible targets is by far more extensive.
       </para>
-      <section>
-        <subtitle>Architectural overview</subtitle>
+      <section id="Architectural overview">
+        <title>Architectural overview</title>
         <figure
           id="50k FT Architecture">
           <title>50k FT Architecture</title>
@@ -261,8 +261,8 @@
     <section
       id="ldapTheLightWeightDirectoryAccessProtocol">
       <title>LDAP – the Lightweight Directory Access Protocol</title>
-      <section>
-        <subtitle>What is it? Some history.</subtitle>
+      <section id="What is it? Some history">
+        <title>What is it? Some history</title>
         <para>
           The comprehensive standard
           <emphasis
@@ -307,8 +307,8 @@
             fileref="images/fromX500toLDAP.png" />
         </figure>
       </section>
-      <section>
-        <subtitle>Information model primer</subtitle>
+      <section id="Information model primer">
+        <title>Information model primer</title>
         <para>
           Within the information model of LDAP, data is stored in entries, which build up a hierarchical, tree like
           structure. Each entry has a unique name (
@@ -351,8 +351,8 @@
           get extended according to special requirements.
         </para>
       </section>
-      <section>
-        <subtitle>Common applications of LDAP based directories</subtitle>
+      <section id="Common applications of LDAP based directories">
+        <title>Common applications of LDAP based directories</title>
         <para>LDAP operations include entry creation, modification, deletion and search. As a general rule, LDAP
           directories are optimized for read and search operations, at the cost of write performance. Data, which will
           be
@@ -369,8 +369,8 @@
           this
           case - most average users probably don't know.</para>
       </section>
-      <section>
-        <subtitle>Examples of software components which support LDAP</subtitle>
+      <section id="Examples of software components which support LDAP">
+        <title>Examples of software components which support LDAP</title>
         <figure
           id="LDAP-Tools">
           <title>LDAP-Tools</title>
@@ -406,8 +406,8 @@
     <section
       id="ldapResources">
       <title>LDAP resources</title>
-      <section>
-        <subtitle>Books</subtitle>
+      <section id="Books">
+        <title>Books</title>
         <para>There are several good LDAP books available. Here are two examples which provide sample chapters on their
           homepages.</para>
         <para>
@@ -444,10 +444,10 @@
             url="http://www.entwickler-press.de/buecher/ldap/">Webseite zum Buch (Zoerner)</ulink>
         </para>
       </section>
-      <section>
-        <subtitle>Articles, forums, blogs and other online resources</subtitle>
-        <section>
-          <subtitle>Blogs</subtitle>
+      <section id="Articles, forums, blogs and other online resources">
+        <title>Articles, forums, blogs and other online resources</title>
+        <section id="Blogs">
+          <title>Blogs</title>
           <itemizedlist>
             <listitem>
               <para>
@@ -458,8 +458,8 @@
             </listitem>
           </itemizedlist>
         </section>
-        <section>
-          <subtitle>Articles and other online resources</subtitle>
+        <section id="Articles and other online resources">
+          <title>Articles and other online resources</title>
           <itemizedlist
             mark="bullet">
             <listitem>
@@ -632,8 +632,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           role="bold">Administrator</emphasis>
         privileges.
       </para>
-      <section>
-        <subtitle>Starting and stopping the server</subtitle>
+      <section id="Starting and stopping the server Windows">
+        <title>Starting and stopping the server</title>
         <para>
           The server can be started and stopped with Windows Services manager (
           <emphasis
@@ -655,8 +655,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           fileref="images/MacOSX_Installer.png" />
       </figure>
       <para>From there, you will be guided to install Apache DS on your system.</para>
-      <section>
-        <subtitle>Starting and stopping the server</subtitle>
+      <section id="Starting and stopping the server MacOSX">
+        <title>Starting and stopping the server</title>
         <para>On Mac OS X, Apache DS is installed as a launchd service and is loaded at startup time (and upon
           successful
           installation).</para>
@@ -723,12 +723,11 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           and change the values of port to your needs. You have to restart the server afterwards in order to take this
           change effect.
         </para>
-        <para>
-          <graphic
-            fileref="images/warning.gif" />
-          Due to traditional Unix security restrictions, ports less than 1024 were "trusted". Thus on a Unix-System, a
+        <warning>
+          Due to traditional Unix security restrictions, ports less than 1024 were "trusted". Thus on a
+          Unix-System, a
           non-root process must listen on a port greater than 1023.
-        </para>
+        </warning>
       </section>
       <section
         id="Resources_1">
@@ -823,7 +822,7 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Connection Properties">
           <title>Connection Properties</title>
-          <grpahic
+          <graphic
             fileref="images/connectionProperties.png" />
         </figure>
         <para>
@@ -1099,7 +1098,7 @@ directoryService.getPartitionNexus().add
       </section>
     </section>
 
-    <section>
+    <section id="Configure logging">
       <title>Configure logging</title>
       <para>In order to detect and analyze problems, adjusting the log level of a server can be a valuable tool. This
         section describes how to configure logging within a standalone ApacheDS.</para>
@@ -1258,8 +1257,8 @@ log4j.logger.org.apache.directory.shared
             <emphasis>&lt;APACHDS_HOME&gt;/var/log/</emphasis>
             , but that can be changed.
           </para>
-          <section>
-            <subtitle>Linux/MacOS/Solaris</subtitle>
+          <section id="Linux/MacOS/Solaris">
+            <title>Linux/MacOS/Solaris</title>
             <para>
               On this systems the location of the log files is configured via an entry in
               <emphasis
@@ -1278,8 +1277,8 @@ $APACHEDS_HOME start
               ]]></programlisting>
             </example>
           </section>
-          <section>
-            <subtitle>Windows</subtitle>
+          <section id="Windows">
+            <title>Windows</title>
             <para>
               On Windows you can use the configuration wizard for the service as shown in the screenshot above. To
               adjust the log path you have to adjust the values of
@@ -1449,13 +1448,10 @@ log4j.appender.R.layout.ConversionPatter
 [29.12.2006 13:50:44] INFO: Service.init() - server: started in 3016 milliseconds
 ...
           ]]></programlisting>
-          <warning>
-            <graphic
-              fileref="images/forbidden.gif" />
-            <title>Warning</title>
+          <caution>
             <para>"Generating caller location information like with %M or %L is extremely slow. Its use should be
               avoided unless execution speed is not an issue." (from the log4j documentation)</para>
-          </warning>
+          </caution>
         </section>
         <section
           id="Advanced log4j configuration">
@@ -1661,7 +1657,7 @@ log4j.logger.org.apache.directory.server
     </section>
     <section
       id="The sample data (Sailors of the seven seas)">
-      <title>The sample data (Sailors of the seven seas)"</title>
+      <title>The sample data (Sailors of the seven seas)</title>
       <para>
         The file
         <ulink

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml?rev=985093&r1=985092&r2=985093&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml Fri Aug 13 04:48:38 2010
@@ -205,14 +205,11 @@ $ java SimpleBindDemo "cn=Horatio Hornbl
         ) is able to read them. This holds true even if authorization is enabled. The passwords would also be visible in
         exported LDIF files. This is often unacceptable.
       </para>
-      <para>
-        <warning>
-          <graphic
-            fileref="images/forbidden.gif" />
-          Not only the administrator will be able to read your password, or be visible in LDIF files, but if one does
-          not use SSL, the the password is transmitted in clear text above the wire...
-        </warning>
-      </para>
+      <caution>
+        Not only the administrator will be able to read your password, or be visible in LDIF files, but if one
+        does
+        not use SSL, the the password is transmitted in clear text above the wire...
+      </caution>
       <section
         id="Passwords not stored in clear text">
         <title>Passwords not stored in clear text</title>
@@ -323,21 +320,21 @@ ldap_simple_bind: additional info: Bind 
       ]]></programlisting>
         <para>This is intended. If someone was able to catch this value (from an LDIF export for instance), s/he must
           still provide the password itself in order to get authenticated.</para>
-        <para>
-          <warning>
-            <graphic
-              fileref="images/warning.gif" />
+        <warning>
+          <para>
             <emphasis
               role="bold">Be Warned: Limited security added</emphasis>
-            <para>Please note that storing user passwords one-way encrypted only adds limited security. During the bind
-              operation, the credentials are still transmitted unencrypted, if no SSL/TLS communication is used (thus
-              you should definitely consider to do so). </para>
-            <para>Furthermore, if someone gets an LDIF file with userpassword values digested with SHA etc., s/he may be
-              able to determine some of the passwords with brute force. Calculation of hash functions can be done very
-              fast, and the attacker can attempt millions of values with ease, without you getting notice of it.
-              Therefore protect your data, even if one-way encryption is applied to the passwords!</para>
-          </warning>
-        </para>
+          </para>
+          <para>Please note that storing user passwords one-way encrypted only adds limited security. During the bind
+            operation, the credentials are still transmitted unencrypted, if no SSL/TLS communication is used (thus
+            you
+            should definitely consider to do so). </para>
+          <para>Furthermore, if someone gets an LDIF file with userpassword values digested with SHA etc., s/he may be
+            able to determine some of the passwords with brute force. Calculation of hash functions can be done very
+            fast, and the attacker can attempt millions of values with ease, without you getting notice of it.
+            Therefore
+            protect your data, even if one-way encryption is applied to the passwords!</para>
+        </warning>
       </section>
     </section>
     <section
@@ -404,23 +401,22 @@ objectclass: top
           <graphic
             fileref="images/authentication_options_ls.png" />
         </figure>
-        <para>
-          <warning>
-            <graphic
-              fileref="images/warning.gif" />
+        <warning>
+          <para>
             <emphasis
               role="bold">Use this feature wisely</emphasis>
-            <para>
-              With anonymous access enabled it is not only possible to search the directory without providing username
-              and password. With autorization disabled, anonymous users may also be able to modify data. It is therefore
-              highly recommended to enable and configure the authorization subsystem as well. Learn more about
-              authorization in the
-              <xref
-                linkend="Basic authorization" />
-              section
-            </para>
-          </warning>
-        </para>
+          </para>
+          <para>
+            With anonymous access enabled it is not only possible to search the directory without providing username
+            and
+            password. With autorization disabled, anonymous users may also be able to modify data. It is therefore
+            highly recommended to enable and configure the authorization subsystem as well. Learn more about
+            authorization in the
+            <xref
+              linkend="Basic authorization" />
+            section
+          </para>
+        </warning>
       </section>
     </section>
     <section
@@ -1449,18 +1445,495 @@ $
     <section
       id="Transport layer security and LDAP">
       <title>Transport layer security and LDAP</title>
+      <para>
+        Several requirements related to security can be easily accomplished with the help of
+        <emphasis
+          role="bold">SSL</emphasis>
+        technology (Secure
+        Socket Layer) or its standardized successor
+        <emphasis
+          role="bold">TLS</emphasis>
+        (Transport Layer Security, RFC 2246). Among these are the
+        protection of data against eavesdropping and
+        modification, when on transit between client and server (data
+        integrity), and the authentication of a server
+        toward a client with the help of a certificate.
+      </para>
+      <para>
+        There are two approaches to utilize these technologies in the LDAP world.
+        <orderedlist>
+          <listitem>
+            <para>ldaps (LDAP over SSL/TLS, port 636)</para>
+          </listitem>
+          <listitem>
+            <para>StartTLS (extended operation)</para>
+          </listitem>
+        </orderedlist>
+      </para>
+      <para>
+        The first option is comparable to HTTPS and inserts an SSL/TLS layer between the TCP/IP protocol and LDAP.
+        Establishing a connection like this is normally provided via a different server port (port 636 is common, it is
+        a well-known port, like port 389 is for LDAP). In URIs the schema "ldaps" is specified (for instance
+        <emphasis>ldaps://zanzibar:636/</emphasis>
+        ) instead of "ldap". It is possible to write programs which switch between ldap and ldaps
+        without changes in the
+        source, if the connection data is configured external.
+      </para>
+      <para>In the second option a client establishes at first a "normal" LDAP connection. With a special request
+        (extended operation StartTLS) it tries to switch to secure communication afterwards. It is not necessary to
+        change the port for this, the communication continues on the established connection. The client may go back to
+        the original connection state ("TLS Closure Alert"), in doing so protecting only selected parts of the
+        communication.</para>
+      <para>Both ways to utilize SSL/TLS within LDAP require the configuration of the server with an appropriate
+        certificate.</para>
     </section>
     <section
       id="Server configuration">
       <title>Server configuration</title>
+      <para>ApacheDS 1.5.5 supports both options and requires a JDK 1.5 or above. The feature is enabled by default, but
+        you may need to configure it. There are some steps to follow in order to obtain a SSL enabled server.</para>
+      <warning>
+        <para>In order to keep it simple for beginners, you don't need any certificate to get LDAPS working. The latest
+          version generates its own self signed certificate. From the user point of view, it's just a matter of enabling
+          the ldaps service to get it working.</para>
+        <para>However, if one wants to use a signed certificate, another configuration is needed, where you tell the
+          server about the keystore to use, and the certificate password to use.</para>
+      </warning>
+      <section
+        id="In case you want ADS to generate the certificate">
+        <warning>In case you want ADS to generate the certificate</warning>
+        <para>
+          There is nothing to do but enabling SSL and specifying the port to use in the
+          <emphasis>server.xml</emphasis>
+          configuration file :
+        </para>
+        <programlisting><![CDATA[
+...
+  <ldapServer id="ldapServer"
+            ...>
+    <transports>
+      ...
+      <tcpTransport address="localhost" port="10636" enableSSL="true"/>
+    </transports>
+    ...
+  </ldapServer>
+  ...
+        ]]></programlisting>
+        <para>That's it, the server is LDAPS capable !</para>
+        <warning>
+          <para>
+            The default
+            <emphasis>server.xml</emphasis>
+            configuration file contains an typo, by default the port is set to 10686.
+          </para>
+        </warning>
+      </section>
+      <section
+        id="In case you want to use an external keystore">
+        <title>In case you want to use an external keystore</title>
+        <para>A certificate is a signed public key (signed normally by a third party, a certificate authority, CA).
+        </para>
+        <para>
+          There are different options
+          <itemizedlist>
+            <listitem>
+              <para>either you buy a certificate from a Certificate Authority (like Verisign, etc.), or you obtain one
+                from your enterprise CA, if available</para>
+            </listitem>
+            <listitem>
+              <para>
+                or you ask for a free certificate from
+                <ulink
+                  url="http://www.cacert.org/">CACERT organisation</ulink>
+              </para>
+            </listitem>
+            <listitem>
+              <para>or you create your own certificate, self-signed or signed by your private CA, which will not be
+                trusted.</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+        <para>We will do it the last way (self-signed), primarily because it's easy and fast (you won't have to pay nor
+          to wait to obtain your certificate)</para>
+        <section
+          id="Key creation">
+          <title>Key creation</title>
+          <para>First it is necessary to create a key pair (public/private key) for your server, zanzibar in our case.
+            One option is to use the JDK tool keytool for this task. In the following example, we use these options
+          </para>
+          <table
+            id="Key creation table">
+            <title>SSL Key creation</title>
+            <tgroup
+              cols="3">
+              <thead>
+                <row>
+                  <entry>Option</entry>
+                  <entry>value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>-genkey</entry>
+                  <entry></entry>
+                  <entry>command to generate a key pair</entry>
+                </row>
+                <row>
+                  <entry>-keyalg</entry>
+                  <entry>"RSA"</entry>
+                  <entry>algorithm to be used to generate the key pair, in our case, default is "DSA"</entry>
+                </row>
+                <row>
+                  <entry>-dname</entry>
+                  <entry>"cn=zanzibar, ou=ApacheDS, o=ASF, c=US"</entry>
+                  <entry>the X.500 Distinguished Name to be associated with alias, used as the issuer and subject fields
+                    in the self-signed certificate</entry>
+                </row>
+                <row>
+                  <entry>-alias</entry>
+                  <entry>zanzibar</entry>
+                  <entry>name to refer the entry within the keystore</entry>
+                </row>
+                <row>
+                  <entry>-keystore</entry>
+                  <entry>zanzibar.ks </entry>
+                  <entry>keystore file location</entry>
+                </row>
+                <row>
+                  <entry>-storepass</entry>
+                  <entry>secret</entry>
+                  <entry>password used to protect the integrity of the keystore</entry>
+                </row>
+                <row>
+                  <entry>-validity</entry>
+                  <entry>730</entry>
+                  <entry>number of days for which the certificate should be considered valid, default is 90</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+            Learn more about keytool at the
+            <ulink
+              url="http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html">manpage</ulink>
+            .
+          </para>
+          <programlisting><![CDATA[
+$ keytool -genkey -keyalg "RSA" -dname "cn=zanzibar, ou=ApacheDS, o=ASF, c=US" \\
+    -alias zanzibar -keystore zanzibar.ks -storepass secret -validity 730
+Enter key password for <zanzibar>
+        (RETURN if same as keystore password):
+$ ls -l
+total 4
+-rw-r--r--   1 stefan   users       1275 Jun 10 20:42 zanzibar.ks
+$ keytool -list -keystore zanzibar.ks
+Enter keystore password:  secret
+
+Keystore type: jks
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+zanzibar, Jun 10, 2007, keyEntry,
+Certificate fingerprint (MD5): 95:4A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C
+$
+          ]]></programlisting>
+          <para>
+            Another option is to use graphical tools for key creation like
+            <ulink
+              url="http://portecle.sourceforge.net/">Portecle</ulink>
+            , which is basically a user-friendly front-end for keytool with comparable functionality. For a first
+            impression see a screen shot below.
+          </para>
+          <graphic
+            fileref="images/portecle_with_keystore.png" />
+        </section>
+        <section
+          id="Configuring ApacheDS to use this external keystore">
+          <title>Configuring ApacheDS to use this external keystore</title>
+          <para>
+            Enabling SSL in Apache Directory Server and using the key pair created as above is quite easy. Simply
+            put the
+            keystore file in the
+            <emphasis>conf</emphasis>
+            directory of ApacheDS, and enable ldaps. Here is the fragment from
+            <emphasis>server.xml</emphasis>
+            on how to do so.
+          </para>
+          <programlisting><![CDATA[
+...
+  <ldapServer id="ldapServer"
+           ...
+           keystoreFile="C:/java/apacheds-1.5.5/conf/zanzibar.ks"
+           certificatePassword="secret">
+    <transports>
+      ...
+      <tcpTransport address="localhost" port="10636" enableSSL="true"/>
+    </transports>
+    ...
+  </ldapServer>
+  ...
+          ]]></programlisting>
+          <para>The following properties were used</para>
+          <table
+            id="External Keystore Properties table">
+            <title>External Keystore Properties</title>
+            <tgroup
+              cols="3">
+              <thead>
+                <row>
+                  <entry>Property</entry>
+                  <entry>default value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>keystoreFile</entry>
+                  <entry>none</entry>
+                  <entry>path of the X509 (or JKS) certificate file for LDAPS</entry>
+                </row>
+                <row>
+                  <entry>certificatePassword</entry>
+                  <entry>changeit</entry>
+                  <entry>password which is used to load the LDAPS certificate file</entry>
+                </row>
+                <row>
+                  <entry>port</entry>
+                  <entry>10636</entry>
+                  <entry>LDAPS TCP/IP port number to listen to</entry>
+                </row>
+                <row>
+                  <entry>enableSSL</entry>
+                  <entry>true</entry>
+                  <entry>sets if SSL is enabled or not</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+            After modification of the
+            <emphasis>server.xml</emphasis>
+            , the server has to be restarted in order to take effect.
+          </para>
+        </section>
+      </section>
     </section>
     <section
       id="Verification, Clients">
       <title>Verification, Clients</title>
+      <para>After restarting the server, you should have a server offering both ldap and ldaps. How to verify whether it
+        works?</para>
+      <section
+        id="Using Apache Directory Studio to connect">
+        <title>Using Apache Directory Studio to connect</title>
+        <para>Apache Directory Studio happily supports ldaps connections. Enter the connection data (hostname and port)
+          and select "Use SSL encryption" from the dropdown, if you create or modify a connection:</para>
+        <figure
+          id="Studio SSL figure">
+          <title>Studio SSL</title>
+          <graphic
+            fileref="images/studio_ssl.png" />
+        </figure>
+        <para>Afterwards the connection behaves like LDAP does. No difference in functionality, but the transmission is
+          secured by SSL.</para>
+        <para>Because our self-signed certificate is not trustworthy, many tools will present a warning (as Studio does
+          in version 1.5.0). You will likely be able to view the certificate, and decide to continue (accepting the
+          certificate always or this session only), like with web browsers.</para>
+      </section>
+      <section
+        id="Other clients, Java programs using JNDI">
+        <title>Other clients, Java programs using JNDI</title>
+        <para>If you use other graphical clients, the behavior will be comparable. Sometimes clients don't allow to
+          connect to a server, if the certificate is not trustworthy. This is for instance the case for Java clients
+          using JNDI.</para>
+        <para>
+          The following simple Java program tries to connect via JNDI/JSSE (Java Secure Socket Extension) and LDAPS to
+          <emphasis>ldaps://zanzibar:10636</emphasis>
+        </para>
+        <programlisting><![CDATA[
+import java.util.Hashtable;
+import javax.naming.*;
+import javax.naming.directory.*;
+
+public class ConnectWithLdaps {
+
+    public static void main(String[] args) throws NamingException {
+
+        Hashtable env = new Hashtable();
+
+        // Simple bind
+        env.put(Context.SECURITY_AUTHENTICATION, "simple");
+        env.put(Context.SECURITY_PRINCIPAL,
+                "cn=Horatio Hornblower,ou=people,o=sevenSeas");
+        env.put(Context.SECURITY_CREDENTIALS, "pass");
+
+        env.put(Context.INITIAL_CONTEXT_FACTORY,
+                "com.sun.jndi.ldap.LdapCtxFactory");
+        env.put(Context.PROVIDER_URL, "ldaps://zanzibar:636/o=sevenSeas");
+
+        DirContext ctx = new InitialDirContext(env);
+        NamingEnumeration enm = ctx.list("");
+        while (enm.hasMore()) {
+            System.out.println(enm.next());
+        }
+        ctx.close();
+    }
+}
+]]></programlisting>
+        <para>
+          It causes a
+          <emphasis>CommunicationException</emphasis>
+          , if the certificate is not trusted:
+        </para>
+        <programlisting><![CDATA[
+$ java ConnectWithLdaps
+Exception in thread "main" javax.naming.CommunicationException: 
+  simple bind failed: zanzibar:636 
+      [Root exception is javax.net.ssl.SSLHandshakeException: 
+       sun.security.validator.ValidatorException: PKIX path building failed:    
+       sun.security.provider.certpath.SunCertPathBuilderException: 
+       unable to find valid certification path to requested target]
+at com.sun.jndi.ldap.LdapClient.authenticate(Unknown Source)
+...
+]]></programlisting>
+        <para>In order to make the client trust our server, one option is to share a self signed certificate.
+          So we
+          export the certificate (DER format) using keytool like this:</para>
+        <programlisting><![CDATA[
+$ keytool -export -keystore zanzibar.ks -alias zanzibar -file zanzibar.cer
+Enter keystore password:  secret
+Certificate stored in file <zanzibar.cer>
+$ ls -l
+total 6
+-rw-r--r--   1 stefan   users        504 Jun 10 21:51 zanzibar.cer
+-rw-r--r--   1 stefan   users       1275 Jun 10 20:42 zanzibar.ks
+$ 
+]]></programlisting>
+        <para>
+          Please note that you don't want to share the server keystore file itself with arbitrary clients, because
+          it
+          holds the private key. Instead we create a separate keystore
+          <emphasis>trusted.ks</emphasis>
+          with the help of
+          <emphasis>keytool</emphasis>
+          . We import
+          the certificate
+          <emphasis>zanzibar.cer</emphasis>
+          like this:
+        </para>
+        <programlisting><![CDATA[
+$ keytool -import -file zanzibar.cer -alias zanzibar -keystore trusted.ks -storepass secret
+Owner: CN=zanzibar, OU=ApacheDS, O=ASF, C=US
+Issuer: CN=zanzibar, OU=ApacheDS, O=ASF, C=US
+Serial number: 466c4611
+Valid from: Sun Jun 10 20:42:25 CEST 2007 until: Tue Jun 09 20:42:25 CEST 2009
+Certificate fingerprints:
+         MD5:  95:4A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C
+         SHA1: C5:63:E0:DA:BB:C8:0E:E8:27:D0:91:1D:28:DD:11:BB:93:21:13:C9
+Trust this certificate? [no]:  yes
+Certificate was added to keystore
+$ keytool -list -keystore trusted.ks -storepass secret                
+Keystore type: jks
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+zanzibar, Jun 11, 2007, trustedCertEntry,
+Certificate fingerprint (MD5): 95:4A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C
+$
+]]></programlisting>
+        <para>Instead of using the command line version of keytool, it is also possible to perform the certificate
+          export and import operations with Portecle or any other graphical frontend. This is for instance how the
+          trusted.ks files with the imported certificate looks like in Portecle.</para>
+        <figure
+          id="Portecle with Certificate figure">
+          <title>Portecle with Certificate</title>
+          <graphic
+            fileref="images/portecle_with_certificate.png" />
+        </figure>
+        <para>
+          Clients may use this keystore in order to connect to the server. Therefore they can configure
+          <emphasis>trusted.ks</emphasis>
+          as the trusted store via the environment like this:
+        </para>
+        <programlisting><![CDATA[
+$ java -Djavax.net.ssl.trustStore=trusted.ks ConnectWithLdaps
+ou=people: javax.naming.directory.DirContext
+ou=groups: javax.naming.directory.DirContext 
+]]></programlisting>
+        <para>Another option would be to import the certificate in the default keystore of the JRE installation (within
+          $JAVA_HOME/jre/lib/security). For a test certificate this proceeding is not appropriate.</para>
+        <section
+          id="Troubleshooting">
+          <title>Troubleshooting</title>
+          <para>
+            In practice connection establishment with LDAP over SSL may lead to various problems. In order to
+            eliminate
+            the errors it is helpful to see communication-specific debug information. The system property
+            <emphasis>javax.net.debug</emphasis>
+            is available for this task. The value "ssl" provides information about the certificates in
+            the used key
+            store, the server certificate, and the steps during establishing of the SSL connection
+            (handshake):
+          </para>
+          <programlisting><![CDATA[
+$ java -Djavax.net.ssl.trustStore=trusted.ks -Djavax.net.debug=ssl ConnectWithLdaps
+setting up default SSLSocketFactory
+use default SunJSSE impl class: com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl
+class com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl is loaded
+keyStore is : 
+keyStore type is : jks
+keyStore provider is : 
+init keystore
+init keymanager of type SunX509
+trustStore is: trusted.ks
+trustStore type is : jks
+trustStore provider is : 
+init truststore
+adding as trusted cert:
+  Subject: CN=zanzibar, OU=ApacheDS, O=ASF, C=US
+  Issuer:  CN=zanzibar, OU=ApacheDS, O=ASF, C=US
+  Algorithm: RSA; Serial number: 0x466c4611
+  Valid from Sun Jun 10 20:42:25 CEST 2007 until Tue Jun 09 20:42:25 CEST 2009
+
+init context
+trigger seeding of SecureRandom
+done seeding SecureRandom
+instantiated an instance of class com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl
+%% No cached client session
+*** ClientHello, TLSv1
+...
+]]></programlisting>
+          <para>You should be able to determine any SSL-related configuration problem with the help of this log.</para>
+        </section>
+      </section>
     </section>
     <section
       id="Resources SSL">
       <title>Resources</title>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <ulink
+              url="http://java.sun.com/products/jsse/">Java Secure Socket Extension (JSSE)</ulink>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <ulink
+              url="http://portecle.sourceforge.net/">Portecle</ulink>
+            a free UI application for creating, managing and examining keystores
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <ulink
+              url="http://wp.netscape.com/eng/ssl3/">SSL 3.0 Specification (Netscape)</ulink>
+          </para>
+        </listitem>
+      </itemizedlist>
     </section>
   </section>
 </chapter>

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml?rev=985093&r1=985092&r2=985093&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml Fri Aug 13 04:48:38 2010
@@ -11,5 +11,253 @@
   <title>Integrating ApacheDS with other programs</title>
   <section>
     <title>Mozilla Thunderbird</title>
+    <para>In this section you will learn how to integrate Apache Directory Server into a mail client in order to use the
+      data as an address book. Mozilla Thunderbird is used as an example.</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <xref
+            linkend="E-Mail clients and Mozilla Thunderbird" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Prerequisites Thunderbird" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Define Apache Directory Server as an address book" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Searching your new address book" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Resources Thunderbird" />
+        </para>
+      </listitem>
+    </itemizedlist>
+    <section
+      id="E-Mail clients and Mozilla Thunderbird">
+      <title>E-Mail clients and Mozilla Thunderbird</title>
+      <para>
+        Integrating an LDAP server in an E-Mail client is a very traditionally task, because directories are
+        commonly
+        used as user repositories within companies and organizations. Contact data is stored for all users of
+        the
+        enterprise, and it is quite common to build the companies online phone/address book on this directory. These
+        address books are often web based application within the intranet. But many E-Mail clients allow to connect to
+        an LDAP based directory directly and use its data as an address book. This seamless integration provides better
+        user experience. One of these clients is Mozilla Thunderbird. Other E-Mail clients that support LDAP integration
+        for address books include
+        <ulink
+          url="http://www.microsoft.com/windows/oe/">Microsoft Outlook Expess</ulink>
+        ,
+        <ulink
+          url="http://www.eudora.com/">Eudora Email</ulink>
+        and
+        <ulink
+          url="http://www.ibm.com/software/lotus/">IBM Lotus Notes</ulink>
+        .
+      </para>
+      <para>Technically, a mail program acts as a normal LDAP client, as described in earlier sections (i.e. the client
+        connects to the server and performs LDAP search operations). Therefore the parameters you have to specify are
+        the same. Main difference between searches with E-Mail clients and searches with LDAP Browsers like Softerra or
+        JXplorer is that most of the complexity of the LDAP search is hidden to the user. Hence these tools are easier
+        to use, but less powerful.</para>
+      <section
+        id="Mozilla Thunderbird">
+        <title>Mozilla Thunderbird</title>
+        <para>
+          Mozilla Thunderbird is a popular open source E-Mail client which supports many platforms. Actually it is more
+          than just an E-Mail client (e.g. a news client as well). Features include junk mail control and RSS reading.
+          Learn more about this software at the projects Homepage:
+          <ulink
+            url="http://www.mozilla.org/products/thunderbird/">Mozilla Thunderbird</ulink>
+          .
+        </para>
+        <para>Within this lesson we use Thunderbird primarily because of its broad support for different operation
+          systems and hardware platforms (and because it allows the integration of LDAP servers as address books, of
+          course). You may use other E-Mail clients as well. It is likely that that allow the integration of LDAP
+          directories as well, and even that the configuration is similar to Thunderbird. Check your product
+          documentation for details.</para>
+      </section>
+    </section>
+    <section
+      id="Prerequisites Thunderbird">
+      <title>Prerequisites</title>
+      <para>
+        We assume that you have Mozilla Thunderbird installed on your system (or you use another E-Mail client and are
+        willing to assimilate the instructions to your situation). You may wish to download the software at the homepage
+        (
+        <ulink
+          url="http://www.mozilla.org/products/thunderbird/">Mozilla Thunderbird</ulink>
+        ) and install it, before proceed with this lesson.
+      </para>
+      <para>
+        Furthermore you need an LDAP server up and running, which address data should be used as an address book
+        within
+        your E-Mail client. For the instructions it is assumed that you have installed Apache Directory Server as
+        described in the first trail and loaded our sample data. To sum it up the following is assumed for the
+        environment:
+        <itemizedlist>
+          <listitem>
+            <para>
+              Apache Directory runs on host
+              <emphasis
+                role="bold">zanzibar</emphasis>
+              . LDAP and listens to port
+              <emphasis
+                role="bold">10389</emphasis>
+            </para>
+          </listitem>
+          <listitem>
+            <para>Anonymous access to the directory is allowed</para>
+          </listitem>
+          <listitem>
+            <para>
+              Data is imported as described in section 2, Base DN is
+              <emphasis
+                role="bold">o=sevenSeas</emphasis>
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+      <para>
+        You may use this lesson as a blueprint to integrate other directory servers as well. At least you need the data
+        given above in
+        <emphasis
+          role="bold">bold.</emphasis>
+      </para>
+    </section>
+    <section
+      id="Define Apache Directory Server as an address book">
+      <title>Define Apache Directory Server as an address book</title>
+      <section
+        id="Open the address book">
+        <title>Open the address book</title>
+        <para>After starting Mozilla Thunderbird on your workstation, go to the address book by</para>
+        <itemizedlist>
+          <listitem>
+            <para>clicking the adress book icon or</para>
+          </listitem>
+          <listitem>
+            <para>activation of the corresponding menu item ("Tools" – "Address Book") or</para>
+          </listitem>
+          <listitem>
+            <para>pressing Ctrl+2</para>
+          </listitem>
+        </itemizedlist>
+        <figure
+          id="Thunderbird open Adressbook figure">
+          <title>Thunderbird open Adressbook</title>
+          <graphic
+            fileref="images/thunderbird_open_adressbook.png" />
+        </figure>
+      </section>
+      <section
+        id="Define a new LDAP directory">
+        <title>Define a new LDAP directory</title>
+        <para>Within the adress book window open the dialog to define a new LDAP directory by</para>
+        <itemizedlist>
+          <listitem>
+            <para>activation of the corresponding menu item ("File" – "New" – "LDAP Directory...")</para>
+          </listitem>
+        </itemizedlist>
+        <figure
+          id="Thunderbird LDAP Directory menu figure">
+          <title>Thunderbird LDAP Directory menu</title>
+          <graphic
+            fileref="images/thunderbird_new_ldap_directory_menu.png" />
+        </figure>
+        <para>Thunderbird opens a dialog with three tabbed panes to provide the data of the directory.</para>
+      </section>
+      <section
+        id="Provide connection data">
+        <title>Provide connection data</title>
+        <para>
+          Within the "General" tab, enter basic connection data to your directory:
+          <itemizedlist>
+            <listitem>
+              <para>Name: A name which is used by Thunderbird within the UI, e.g. "Seven Seas"</para>
+            </listitem>
+            <listitem>
+              <para>Hostname: th hostname or IP address of the server, "zanzibar" in our case</para>
+            </listitem>
+            <listitem>
+              <para>Base DN: Search base for looking up people, we choose "ou=people,o=sevenSeas"</para>
+            </listitem>
+            <listitem>
+              <para>Port number: The port the LDAP provider of Apache Directory Server is listening on, "10389" in our
+                case</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+        <figure
+          id="Thunderbrid new LDAP Connection 1 figure">
+          <title>Thunderbrid new LDAP Connection 1</title>
+          <graphic
+            fileref="images/thunderbird_new_ldap_1.png" />
+        </figure>
+        <para>In this example we do not provide a Bind DN but let Thunderbird look up the users within our directory
+          anonymously. Apache Directory Server should be appropriately configured for that, or you have to provide a
+          user here.</para>
+        <para>The advance tab of the dialog provides input fields for result set limits, search scope and search filter.
+          In our example we perform a search with subtree scope and a maximum number of 100 entries within the result
+          set. The search filter restricts the results to person entries only.</para>
+        <figure
+          id="Thunderbrid new LDAP Connection 2 figure">
+          <title>Thunderbrid new LDAP Connection 2</title>
+          <graphic
+            fileref="images/thunderbird_new_ldap_2.png" />
+        </figure>
+        <para>
+          You probably have noticed that the input fields in the two tabbed panes corresponds exactly to the
+          parameters
+          for an LDAP search operation as described in lesson
+          <ulink
+            url="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=DIRxSRVx11&amp;title=Search%20the%20directory&amp;linkCreation=true&amp;fromPageId=55542">Search the directory</ulink>
+          of this trail.
+        </para>
+      </section>
+    </section>
+    <section
+      id="Searching your new address book">
+      <title>Searching your new address book</title>
+      <figure
+        id="Thunderbird Adressbook figure">
+        <title>Thunderbird Adressbook</title>
+        <graphic
+          fileref="images/thunderbird_adressbook.png" />
+      </figure>
+    </section>
+    <section
+      id="Resources Thunderbird">
+      <title>Resources</title>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <ulink
+              url="http://opensourcearticles.com/articles/introduction_to_thunderbird">An introduction to Thunderbird</ulink>
+            , Open Source Articles
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <ulink
+              url="http://www.mozilla.org/projects/thunderbird/specs/ldap.html">LDAP Attribute Mapping</ulink>
+            for Mozilla Thunderbird
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
   </section>
 </chapter>

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_certificate.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_certificate.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_certificate.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_keystore.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_keystore.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/portecle_with_keystore.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/studio_ssl.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/studio_ssl.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/studio_ssl.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_adressbook.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_adressbook.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_adressbook.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_1.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_1.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_1.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_2.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_2.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_2.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_directory_menu.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_directory_menu.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_new_ldap_directory_menu.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_open_adressbook.png
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_open_adressbook.png?rev=985093&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/sandbox/felixk/apacheds-docs/src/main/resources/images/thunderbird_open_adressbook.png
------------------------------------------------------------------------------
    svn:mime-type = image/png



Mime
View raw message