You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by fe...@apache.org on 2010/08/13 06:48:39 UTC
svn commit: r985093 - in /directory/sandbox/felixk/apacheds-docs/src:
docbkx-stylesheet/html/ docbkx/ main/resources/images/
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><APACHDS_HOME>/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&title=Search%20the%20directory&linkCreation=true&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