directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r836569 - in /websites/staging/directory/trunk/content: ./ apacheds/basic-ug/ apacheds/basic-ug/images/
Date Tue, 30 Oct 2012 07:12:00 GMT
Author: buildbot
Date: Tue Oct 30 07:11:59 2012
New Revision: 836569

Log:
Staging update by buildbot for directory

Added:
    websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-certificate.png   (with props)
    websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-keystore.png   (with props)
    websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-apacheds-configuration-ldaps.png   (with props)
    websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-ssl.png   (with props)
Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/apacheds/basic-ug/3.3-enabling-ssl.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Oct 30 07:11:59 2012
@@ -1 +1 @@
-1403462
+1403631

Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/3.3-enabling-ssl.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/3.3-enabling-ssl.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/3.3-enabling-ssl.html Tue Oct 30 07:11:59 2012
@@ -126,6 +126,316 @@
 
 
 <h1 id="33-how-to-enable-ssl">3.3 - How to enable SSL</h1>
+<p>This section describes the transport layer security options for LDAP, and especially how to enable LDAPS on ApacheDS.</p>
+<div class="toc">
+<ul>
+<li><a href="#33-how-to-enable-ssl">3.3 - How to enable SSL</a><ul>
+<li><a href="#transport-layer-security-and-ldap">Transport layer security and LDAP</a></li>
+<li><a href="#server-configuration">Server configuration</a><ul>
+<li><a href="#in-case-you-want-ads-to-generate-the-certificate">In case you want ADS to generate the certificate</a></li>
+<li><a href="#in-case-you-want-to-use-an-external-keystore">In case you want to use an external keystore</a><ul>
+<li><a href="#key-creation">Key creation</a></li>
+<li><a href="#configuring-apacheds-to-use-this-external-keystore">Configuring ApacheDS to use this external keystore</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#verification-clients">Verification, Clients</a><ul>
+<li><a href="#using-apache-directory-studio-to-connect">Using Apache Directory Studio to connect</a></li>
+<li><a href="#other-clients-java-programs-using-jndi">Other clients, Java programs using JNDI</a><ul>
+<li><a href="#troubleshooting">Troubleshooting</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#resources">Resources</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h2 id="transport-layer-security-and-ldap">Transport layer security and LDAP</h2>
+<p>Several requirements related to security can be easily accomplished with the help of <em>SSL</em> technology (Secure Socket Layer) or its standardized successor <em>TLS</em> (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.</p>
+<p>There are two approaches to utilize these technologies in the LDAP world. </p>
+<ul>
+<li>ldaps (LDAP over SSL/TLS, generally on port 636)</li>
+<li>StartTLS (extended operation) </li>
+</ul>
+<p>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 <em>ldaps://zanzibar:636/</em>) 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.</p>
+<p>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.</p>
+<p>Both ways to utilize SSL/TLS within LDAP require the configuration of the server with an appropriate certificate.</p>
+<p><DIV class="warning" markdown="1">
+<strong>LDAPS</strong> is considered as deprecated. You should always favor startTLS instead.
+</DIV></p>
+<h2 id="server-configuration">Server configuration</h2>
+<p>ApacheDS 2.0 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.</p>
+<p><DIV class="note" markdown="1">
+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.</p>
+<p>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.
+</DIV></p>
+<h3 id="in-case-you-want-ads-to-generate-the-certificate">In case you want ADS to generate the certificate</h3>
+<p>There is nothing to do but enabling SSL and specifying the port to use in the server configuration file :</p>
+<p><img alt="LDAPS configuration" src="images/studio-apacheds-configuration-ldaps.png" /></p>
+<p>As soon as the "Enable LDAPS server" checkbox is checked, your server is LDAPS capable !</p>
+<h3 id="in-case-you-want-to-use-an-external-keystore">In case you want to use an external keystore</h3>
+<p>A certificate is a signed public key (signed normally by a third party, a certificate authority, CA).</p>
+<p>There are different options
+- either you buy a certificate from a Certificate Authority (like Verisign, etc.), or you obtain one from your enterprise CA, if available
+- or you ask for a free certificate from <a href="http://www.cacert.org/">CACERT organisation</a>
+- or you create your own certificate, self-signed or signed by your private CA, which will not be trusted.</p>
+<p>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)</p>
+<h4 id="key-creation">Key creation</h4>
+<p>First it is necessary to create a key pair (public/private key) for your server, <em>zanzibar</em> in our case.  One option is to use the JDK tool <em>keytool</em> for this task. In the following example, we use these options</p>
+<div class="table-wrap">
+    <table class="confluenceTable">
+        <tbody>
+            <tr>
+                <th class="confluenceTh"> Option </th>
+                <th class="confluenceTh"> value </th>
+                <th class="confluenceTh"> Description </th>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -genkey </td>
+                <td class="confluenceTd">&nbsp;</td>
+                <td class="confluenceTd"> command to generate a key pair </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -keyalg </td>
+                <td class="confluenceTd"> "RSA" </td>
+                <td class="confluenceTd"> algorithm to be used to generate the key pair,  in our case, default is "DSA" </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -dname </td>
+                <td class="confluenceTd"> "cn=zanzibar, ou=ApacheDS, o=ASF, c=US" </td>
+                <td class="confluenceTd"> the X.500 Distinguished Name to be associated with alias, used as the issuer and subject fields in the self-signed certificate </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -alias </td>
+                <td class="confluenceTd"> zanzibar </td>
+                <td class="confluenceTd"> name to refer the entry within the keystore  </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -keystore </td>
+                <td class="confluenceTd"> zanzibar.ks </td>
+                <td class="confluenceTd">  keystore file location </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -storepass </td>
+                <td class="confluenceTd"> secret </td>
+                <td class="confluenceTd">  password used to protect the integrity of the keystore </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> -validity </td>
+                <td class="confluenceTd"> 730 </td>
+                <td class="confluenceTd"> number of days for which the certificate should be considered valid, default is 90 </td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+
+<p>Learn more about keytool at the <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html">manpage</a>.</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">keytool</span> <span class="o">-</span><span class="n">genkey</span> <span class="o">-</span><span class="n">keyalg</span> <span class="s">&quot;RSA&quot;</span> <span class="o">-</span><span class="n">dname</span> <span class="s">&quot;cn=zanzibar, ou=ApacheDS, o=ASF, c=US&quot;</span> <span class="o">\\</span>
+    <span class="o">-</span><span class="n">alias</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">keystore</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">storepass</span> <span class="n">secret</span> <span class="o">-</span><span class="n">validity</span> <span class="mi">730</span>
+<span class="n">Enter</span> <span class="n">key</span> <span class="n">password</span> <span class="k">for</span> <span class="sr">&lt;zanzibar&gt;</span>
+    <span class="p">(</span><span class="n">RETURN</span> <span class="k">if</span> <span class="n">same</span> <span class="n">as</span> <span class="n">keystore</span> <span class="n">password</span><span class="p">):</span>
+<span class="nv">$</span> <span class="nv">ls</span> <span class="o">-</span><span class="n">l</span>
+<span class="n">total</span> <span class="mi">4</span>
+<span class="o">-</span><span class="n">rw</span><span class="o">-</span><span class="n">r</span><span class="o">--</span><span class="n">r</span><span class="o">--</span>   <span class="mi">1</span> <span class="n">stefan</span>   <span class="n">users</span>       <span class="mi">1275</span> <span class="n">Jun</span> <span class="mi">10</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">ks</span>
+<span class="nv">$</span> <span class="nv">keytool</span> <span class="o">-</span><span class="n">list</span> <span class="o">-</span><span class="n">keystore</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">ks</span>
+<span class="n">Enter</span> <span class="n">keystore</span> <span class="n">password:</span>  <span class="n">secret</span>
+
+<span class="n">Keystore</span> <span class="n">type:</span> <span class="n">jks</span>
+<span class="n">Keystore</span> <span class="n">provider:</span> <span class="n">SUN</span>
+
+<span class="n">Your</span> <span class="n">keystore</span> <span class="n">contains</span> <span class="mi">1</span> <span class="n">entry</span>
+
+<span class="n">zanzibar</span><span class="p">,</span> <span class="n">Jun</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">2007</span><span class="p">,</span> <span class="n">keyEntry</span><span class="p">,</span>
+<span class="n">Certificate</span> <span class="n">fingerprint</span> <span class="p">(</span><span class="n">MD5</span><span class="p">):</span> <span class="mi">95</span><span class="p">:</span><span class="mi">4</span><span class="n">A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C</span>
+<span class="nv">$</span>
+</pre></div>
+
+
+<p>Another option is to use graphical tools for key creation like <a href="http://portecle.sourceforge.net/">Portecle</a>, which is basically a user-friendly front-end for keytool with comparable functionality. For a first impression see a screen shot below.</p>
+<p><img alt="Portecle Keystore" src="images/portecle-with-keystore.png" /></p>
+<h4 id="configuring-apacheds-to-use-this-external-keystore">Configuring ApacheDS to use this external keystore</h4>
+<p>Enabling SSL in Apache Directory Server and using the key pair created as above is quite easy. Simply put the keystore file in the <em>conf</em> directory of ApacheDS, and enable ldaps. </p>
+<p>TODO : Studio screen capture</p>
+<p>The following properties were used :</p>
+<div class="table-wrap">
+    <table class="confluenceTable">
+        <tbody>
+            <tr>
+                <th class="confluenceTh"> Property</th>
+                <th class="confluenceTh"> default value </th>
+                <th class="confluenceTh"> Description </th>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> keystoreFile </td>
+                <td class="confluenceTd"> none </td>
+                <td class="confluenceTd"> path of the X509 (or JKS) certificate file for LDAPS </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> certificatePassword </td>
+                <td class="confluenceTd"> changeit</td>
+                <td class="confluenceTd"> password which is used to load the LDAPS certificate file </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> port </td>
+                <td class="confluenceTd"> 10636 </td>
+                <td class="confluenceTd"> LDAPS TCP/IP port number to listen to </td>
+            </tr>
+            <tr>
+                <td class="confluenceTd"> enableSSL </td>
+                <td class="confluenceTd"> true </td>
+                <td class="confluenceTd"> sets if SSL is enabled or not </td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+
+<p>After modification of the configuration, the server has to be restarted in order to take effect.</p>
+<h2 id="verification-clients">Verification, Clients</h2>
+<p>After restarting the server, you should have a server offering both ldap and ldaps. How to verify whether it works?</p>
+<h3 id="using-apache-directory-studio-to-connect">Using Apache Directory Studio to connect</h3>
+<p>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:</p>
+<p><img alt="Studio SSL" src="images/studio-ssl.png" /></p>
+<p>Afterwards the connection behaves like LDAP does. No difference in functionality, but the transmission is secured by SSL. </p>
+<p>Because our self-signed certificate is not trustworthy, many tools will present a warning (as Studio). 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.</p>
+<h3 id="other-clients-java-programs-using-jndi">Other clients, Java programs using JNDI</h3>
+<p>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.<br />
+</p>
+<p>The following simple Java program tries to connect via JNDI/JSSE (Java Secure Socket Extension) and LDAPS to <em>ldaps://zanzibar:10636</em></p>
+<div class="codehilite"><pre><span class="nb">import</span> <span class="n">java</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">Hashtable</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">javax</span><span class="o">.</span><span class="n">naming</span><span class="o">.*</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">javax</span><span class="o">.</span><span class="n">naming</span><span class="o">.</span><span class="n">directory</span><span class="o">.*</span><span class="p">;</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">ConnectWithLdaps</span> <span class="p">{</span>
+
+    <span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="p">)</span> <span class="n">throws</span> <span class="n">NamingException</span> <span class="p">{</span>
+
+        <span class="n">Hashtable</span> <span class="n">env</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="p">();</span>
+
+        <span class="sr">//</span> <span class="n">Simple</span> <span class="nb">bind</span>
+        <span class="n">env</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">SECURITY_AUTHENTICATION</span><span class="p">,</span> <span class="s">&quot;simple&quot;</span><span class="p">);</span>
+        <span class="n">env</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">SECURITY_PRINCIPAL</span><span class="p">,</span>
+                <span class="s">&quot;cn=Horatio Hornblower,ou=people,o=sevenSeas&quot;</span><span class="p">);</span>
+        <span class="n">env</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">SECURITY_CREDENTIALS</span><span class="p">,</span> <span class="s">&quot;pass&quot;</span><span class="p">);</span>
+
+        <span class="n">env</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">INITIAL_CONTEXT_FACTORY</span><span class="p">,</span>
+            <span class="s">&quot;com.sun.jndi.ldap.LdapCtxFactory&quot;</span><span class="p">);</span>
+        <span class="n">env</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">PROVIDER_URL</span><span class="p">,</span> <span class="s">&quot;ldaps://zanzibar:636/o=sevenSeas&quot;</span><span class="p">);</span>
+
+        <span class="n">DirContext</span> <span class="n">ctx</span> <span class="o">=</span> <span class="k">new</span> <span class="n">InitialDirContext</span><span class="p">(</span><span class="n">env</span><span class="p">);</span>
+        <span class="n">NamingEnumeration</span> <span class="n">enm</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="p">);</span>
+
+        <span class="k">while</span> <span class="p">(</span><span class="n">enm</span><span class="o">.</span><span class="n">hasMore</span><span class="p">())</span> <span class="p">{</span>
+            <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="n">enm</span><span class="o">.</span><span class="k">next</span><span class="p">());</span>
+        <span class="p">}</span>
+
+        <span class="n">enm</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+        <span class="n">ctx</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>It causes a <em>CommunicationException</em>, if the certificate is not trusted:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">java</span> <span class="n">ConnectWithLdaps</span>
+<span class="n">Exception</span> <span class="n">in</span> <span class="n">thread</span> <span class="s">&quot;main&quot;</span> <span class="n">javax</span><span class="o">.</span><span class="n">naming</span><span class="o">.</span><span class="n">CommunicationException:</span> 
+  <span class="n">simple</span> <span class="nb">bind</span> <span class="n">failed:</span> <span class="n">zanzibar:636</span> 
+    <span class="p">[</span><span class="n">Root</span> <span class="n">exception</span> <span class="n">is</span> <span class="n">javax</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">SSLHandshakeException:</span> 
+       <span class="n">sun</span><span class="o">.</span><span class="n">security</span><span class="o">.</span><span class="n">validator</span><span class="o">.</span><span class="n">ValidatorException:</span> <span class="n">PKIX</span> <span class="n">path</span> <span class="n">building</span> <span class="n">failed:</span>    
+       <span class="n">sun</span><span class="o">.</span><span class="n">security</span><span class="o">.</span><span class="n">provider</span><span class="o">.</span><span class="n">certpath</span><span class="o">.</span><span class="n">SunCertPathBuilderException:</span> 
+       <span class="n">unable</span> <span class="n">to</span> <span class="n">find</span> <span class="n">valid</span> <span class="n">certification</span> <span class="n">path</span> <span class="n">to</span> <span class="n">requested</span> <span class="n">target</span><span class="p">]</span>
+       <span class="n">at</span> <span class="n">com</span><span class="o">.</span><span class="n">sun</span><span class="o">.</span><span class="n">jndi</span><span class="o">.</span><span class="n">ldap</span><span class="o">.</span><span class="n">LdapClient</span><span class="o">.</span><span class="n">authenticate</span><span class="p">(</span><span class="n">Unknown</span> <span class="n">Source</span><span class="p">)</span>
+       <span class="o">...</span>
+</pre></div>
+
+
+<p>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:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">keytool</span> <span class="o">-</span><span class="n">export</span> <span class="o">-</span><span class="n">keystore</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">alias</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">file</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">cer</span>
+<span class="n">Enter</span> <span class="n">keystore</span> <span class="n">password:</span>  <span class="n">secret</span>
+<span class="n">Certificate</span> <span class="n">stored</span> <span class="n">in</span> <span class="n">file</span> <span class="sr">&lt;zanzibar.cer&gt;</span>
+<span class="nv">$</span> <span class="nv">ls</span> <span class="o">-</span><span class="n">l</span>
+<span class="n">total</span> <span class="mi">6</span>
+<span class="o">-</span><span class="n">rw</span><span class="o">-</span><span class="n">r</span><span class="o">--</span><span class="n">r</span><span class="o">--</span>   <span class="mi">1</span> <span class="n">stefan</span>   <span class="n">users</span>        <span class="mi">504</span> <span class="n">Jun</span> <span class="mi">10</span> <span class="mi">21</span><span class="p">:</span><span class="mi">51</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">cer</span>
+<span class="o">-</span><span class="n">rw</span><span class="o">-</span><span class="n">r</span><span class="o">--</span><span class="n">r</span><span class="o">--</span>   <span class="mi">1</span> <span class="n">stefan</span>   <span class="n">users</span>       <span class="mi">1275</span> <span class="n">Jun</span> <span class="mi">10</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">ks</span>
+<span class="nv">$</span>
+</pre></div>
+
+
+<p>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 <em>trusted.ks</em> with the help of <em>keytool</em>. We import the certificate <em>zanzibar.cer</em> like this:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">keytool</span> <span class="o">-</span><span class="nb">import</span> <span class="o">-</span><span class="n">file</span> <span class="n">zanzibar</span><span class="o">.</span><span class="n">cer</span> <span class="o">-</span><span class="n">alias</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">keystore</span> <span class="n">trusted</span><span class="o">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">storepass</span> <span class="n">secret</span>
+<span class="n">Owner:</span> <span class="n">CN</span><span class="o">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="o">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="o">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="o">=</span><span class="n">US</span>
+<span class="n">Issuer:</span> <span class="n">CN</span><span class="o">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="o">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="o">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="o">=</span><span class="n">US</span>
+<span class="n">Serial</span> <span class="n">number:</span> <span class="mi">466</span><span class="n">c4611</span>
+<span class="n">Valid</span> <span class="n">from:</span> <span class="n">Sun</span> <span class="n">Jun</span> <span class="mi">10</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span><span class="p">:</span><span class="mi">25</span> <span class="n">CEST</span> <span class="mi">2007</span> <span class="k">until</span><span class="p">:</span> <span class="n">Tue</span> <span class="n">Jun</span> <span class="mi">09</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span><span class="p">:</span><span class="mi">25</span> <span class="n">CEST</span> <span class="mi">2009</span>
+<span class="n">Certificate</span> <span class="n">fingerprints:</span>
+     <span class="n">MD5:</span>  <span class="mi">95</span><span class="p">:</span><span class="mi">4</span><span class="n">A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C</span>
+     <span class="n">SHA1:</span> <span class="n">C5:63:E0:DA:BB:C8:0E:E8:27:D0:91:1D:28:DD:11:BB:93:21:13:C9</span>
+<span class="n">Trust</span> <span class="n">this</span> <span class="n">certificate</span><span class="p">?</span> <span class="p">[</span><span class="nb">no</span><span class="p">]:</span>  <span class="n">yes</span>
+<span class="n">Certificate</span> <span class="n">was</span> <span class="n">added</span> <span class="n">to</span> <span class="n">keystore</span>
+<span class="nv">$</span> <span class="nv">keytool</span> <span class="o">-</span><span class="n">list</span> <span class="o">-</span><span class="n">keystore</span> <span class="n">trusted</span><span class="o">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">storepass</span> <span class="n">secret</span>                
+<span class="n">Keystore</span> <span class="n">type:</span> <span class="n">jks</span>
+<span class="n">Keystore</span> <span class="n">provider:</span> <span class="n">SUN</span>
+
+<span class="n">Your</span> <span class="n">keystore</span> <span class="n">contains</span> <span class="mi">1</span> <span class="n">entry</span>
+
+<span class="n">zanzibar</span><span class="p">,</span> <span class="n">Jun</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">2007</span><span class="p">,</span> <span class="n">trustedCertEntry</span><span class="p">,</span>
+<span class="n">Certificate</span> <span class="n">fingerprint</span> <span class="p">(</span><span class="n">MD5</span><span class="p">):</span> <span class="mi">95</span><span class="p">:</span><span class="mi">4</span><span class="n">A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C</span>
+<span class="nv">$</span>
+</pre></div>
+
+
+<p>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 <em>trusted.ks</em> files with the imported certificate looks like in Portecle.<br />
+</p>
+<p><img alt="Portecle with certificate" src="images/portecle-with-certificate.png" /></p>
+<p>Clients may use this keystore in order to connect to the server. Therefore they can configure <em>trusted.ks</em> as the trusted store via the environment like this:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">java</span> <span class="o">-</span><span class="n">Djavax</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">trustStore</span><span class="o">=</span><span class="n">trusted</span><span class="o">.</span><span class="n">ks</span> <span class="n">ConnectWithLdaps</span>
+<span class="n">ou</span><span class="o">=</span><span class="n">people:</span> <span class="n">javax</span><span class="o">.</span><span class="n">naming</span><span class="o">.</span><span class="n">directory</span><span class="o">.</span><span class="n">DirContext</span>
+<span class="n">ou</span><span class="o">=</span><span class="n">groups:</span> <span class="n">javax</span><span class="o">.</span><span class="n">naming</span><span class="o">.</span><span class="n">directory</span><span class="o">.</span><span class="n">DirContext</span>
+</pre></div>
+
+
+<p>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.</p>
+<h4 id="troubleshooting">Troubleshooting</h4>
+<p>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 <em>javax.net.debug</em> 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):</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">java</span> <span class="o">-</span><span class="n">Djavax</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">trustStore</span><span class="o">=</span><span class="n">trusted</span><span class="o">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">Djavax</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">debug</span><span class="o">=</span><span class="n">ssl</span> <span class="n">ConnectWithLdaps</span>
+<span class="n">setting</span> <span class="n">up</span> <span class="n">default</span> <span class="n">SSLSocketFactory</span>
+<span class="k">use</span> <span class="n">default</span> <span class="n">SunJSSE</span> <span class="n">impl</span> <span class="n">class:</span> <span class="n">com</span><span class="o">.</span><span class="n">sun</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">internal</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">SSLSocketFactoryImpl</span>
+<span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">sun</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">internal</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">SSLSocketFactoryImpl</span> <span class="n">is</span> <span class="n">loaded</span>
+<span class="n">keyStore</span> <span class="n">is</span> <span class="p">:</span> 
+<span class="n">keyStore</span> <span class="n">type</span> <span class="n">is</span> <span class="p">:</span> <span class="n">jks</span>
+<span class="n">keyStore</span> <span class="n">provider</span> <span class="n">is</span> <span class="p">:</span> 
+<span class="n">init</span> <span class="n">keystore</span>
+<span class="n">init</span> <span class="n">keymanager</span> <span class="n">of</span> <span class="n">type</span> <span class="n">SunX509</span>
+<span class="n">trustStore</span> <span class="n">is:</span> <span class="n">trusted</span><span class="o">.</span><span class="n">ks</span>
+<span class="n">trustStore</span> <span class="n">type</span> <span class="n">is</span> <span class="p">:</span> <span class="n">jks</span>
+<span class="n">trustStore</span> <span class="n">provider</span> <span class="n">is</span> <span class="p">:</span> 
+<span class="n">init</span> <span class="n">truststore</span>
+<span class="n">adding</span> <span class="n">as</span> <span class="n">trusted</span> <span class="n">cert:</span>
+  <span class="n">Subject:</span> <span class="n">CN</span><span class="o">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="o">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="o">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="o">=</span><span class="n">US</span>
+  <span class="n">Issuer:</span>  <span class="n">CN</span><span class="o">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="o">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="o">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="o">=</span><span class="n">US</span>
+  <span class="n">Algorithm:</span> <span class="n">RSA</span><span class="p">;</span> <span class="n">Serial</span> <span class="n">number:</span> <span class="mh">0x466c4611</span>
+  <span class="n">Valid</span> <span class="n">from</span> <span class="n">Sun</span> <span class="n">Jun</span> <span class="mi">10</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span><span class="p">:</span><span class="mi">25</span> <span class="n">CEST</span> <span class="mi">2007</span> <span class="k">until</span> <span class="n">Tue</span> <span class="n">Jun</span> <span class="mi">09</span> <span class="mi">20</span><span class="p">:</span><span class="mi">42</span><span class="p">:</span><span class="mi">25</span> <span class="n">CEST</span> <span class="mi">2009</span>
+
+<span class="n">init</span> <span class="n">context</span>
+<span class="n">trigger</span> <span class="n">seeding</span> <span class="n">of</span> <span class="n">SecureRandom</span>
+<span class="n">done</span> <span class="n">seeding</span> <span class="n">SecureRandom</span>
+<span class="n">instantiated</span> <span class="n">an</span> <span class="n">instance</span> <span class="n">of</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">sun</span><span class="o">.</span><span class="n">net</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">internal</span><span class="o">.</span><span class="n">ssl</span><span class="o">.</span><span class="n">SSLSocketFactoryImpl</span>
+<span class="nv">%%</span> <span class="nv">No</span> <span class="n">cached</span> <span class="n">client</span> <span class="n">session</span>
+<span class="o">***</span> <span class="n">ClientHello</span><span class="p">,</span> <span class="n">TLSv1</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>You should be able to determine any SSL-related configuration problem with the help of this log.</p>
+<h2 id="resources">Resources</h2>
+<ul>
+<li><a href="http://java.sun.com/products/jsse/">Java Secure Socket Extension (JSSE)</a></li>
+<li><a href="http://portecle.sourceforge.net">Portecle</a> a free UI application for creating, managing and examining keystores</li>
+<li><a href="http://wp.netscape.com/eng/ssl3/">SSL 3.0 Specification (Netscape)</a></li>
+</ul>
 
 
     <div class="nav">

Added: websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-certificate.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-certificate.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-keystore.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/apacheds/basic-ug/images/portecle-with-keystore.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-apacheds-configuration-ldaps.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-apacheds-configuration-ldaps.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-ssl.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/apacheds/basic-ug/images/studio-ssl.png
------------------------------------------------------------------------------
    svn:mime-type = image/png



Mime
View raw message