You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2013/06/21 12:04:40 UTC
svn commit: r866770 [5/9] - in /websites/staging/directory/trunk/content: ./
apacheds/ apacheds/advanced-ug/ apacheds/basic-ug/ apacheds/configuration/
apacheds/kerberos-ug/ api/ api/gen-docs/ api/gen-docs/latest/
api/groovy-api/ api/user-guide/ studio/
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 Fri Jun 21 10:04:38 2013
@@ -175,15 +175,18 @@
<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>
+<DIV class="warning" markdown="1">
+**LDAPS** is considered as deprecated. You should always favor startTLS instead.
+</DIV>
+
<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>
+<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.
+
+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>
+
<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>
@@ -244,24 +247,24 @@ In order to keep it simple for beginners
</tbody>
</table>
<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">"RSA"</span> <span class="o">-</span><span class="n">dname</span> <span class="s">"cn=zanzibar, ou=ApacheDS, o=ASF, c=US"</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"><zanzibar></span>
+<div class="codehilite"><pre>$ <span class="n">keytool</span> <span class="o">-</span><span class="n">genkey</span> <span class="o">-</span><span class="n">keyalg</span> "<span class="n">RSA</span>" <span class="o">-</span><span class="n">dname</span> "<span class="n">cn</span><span class="p">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">ou</span><span class="p">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">o</span><span class="p">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">c</span><span class="p">=</span><span class="n">US</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="p">.</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> 730
+<span class="n">Enter</span> <span class="n">key</span> <span class="n">password</span> <span class="k">for</span> <span class="o"><</span><span class="n">zanzibar</span><span class="o">></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>
+$ <span class="n">ls</span> <span class="o">-</span><span class="n">l</span>
+<span class="n">total</span> 4
+<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> 1 <span class="n">stefan</span> <span class="n">users</span> 1275 <span class="n">Jun</span> 10 20<span class="p">:</span>42 <span class="n">zanzibar</span><span class="p">.</span><span class="n">ks</span>
+$ <span class="n">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="p">.</span><span class="n">ks</span>
+<span class="n">Enter</span> <span class="n">keystore</span> <span class="n">password</span><span class="p">:</span> <span class="n">secret</span>
+
+<span class="n">Keystore</span> <span class="n">type</span><span class="p">:</span> <span class="n">jks</span>
+<span class="n">Keystore</span> <span class="n">provider</span><span class="p">:</span> <span class="n">SUN</span>
+
+<span class="n">Your</span> <span class="n">keystore</span> <span class="n">contains</span> 1 <span class="n">entry</span>
+
+<span class="n">zanzibar</span><span class="p">,</span> <span class="n">Jun</span> 10<span class="p">,</span> 2007<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> 95<span class="p">:</span>4<span class="n">A</span><span class="p">:</span>90<span class="p">:</span>3<span class="n">D</span><span class="p">:</span>69<span class="p">:</span>09<span class="p">:</span>64<span class="p">:</span>84<span class="p">:</span><span class="n">C7</span><span class="p">:</span>21<span class="p">:</span><span class="n">FD</span><span class="p">:</span><span class="n">F7</span><span class="p">:</span><span class="n">B8</span><span class="p">:</span>82<span class="p">:</span>11<span class="p">:</span>8<span class="n">C</span>
+$
</pre></div>
@@ -311,131 +314,129 @@ In order to keep it simple for beginners
<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>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. </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>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">Hashtable</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">javax</span><span class="p">.</span><span class="n">naming</span><span class="o">.*</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">javax</span><span class="p">.</span><span class="n">naming</span><span class="p">.</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">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="p">[]</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="n">Hashtable</span> <span class="n">env</span> <span class="p">=</span> <span class="n">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">"simple"</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">"cn=Horatio Hornblower,ou=people,o=sevenSeas"</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">"pass"</span><span class="p">);</span>
+ <span class="o">//</span> <span class="n">Simple</span> <span class="n">bind</span>
+ <span class="n">env</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">SECURITY_AUTHENTICATION</span><span class="p">,</span> "<span class="n">simple</span>"<span class="p">);</span>
+ <span class="n">env</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">SECURITY_PRINCIPAL</span><span class="p">,</span>
+ "<span class="n">cn</span><span class="p">=</span><span class="n">Horatio</span> <span class="n">Hornblower</span><span class="p">,</span><span class="n">ou</span><span class="p">=</span><span class="n">people</span><span class="p">,</span><span class="n">o</span><span class="p">=</span><span class="n">sevenSeas</span>"<span class="p">);</span>
+ <span class="n">env</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">SECURITY_CREDENTIALS</span><span class="p">,</span> "<span class="n">pass</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">"com.sun.jndi.ldap.LdapCtxFactory"</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">"ldaps://zanzibar:636/o=sevenSeas"</span><span class="p">);</span>
+ <span class="n">env</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">INITIAL_CONTEXT_FACTORY</span><span class="p">,</span>
+ "<span class="n">com</span><span class="p">.</span><span class="n">sun</span><span class="p">.</span><span class="n">jndi</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">LdapCtxFactory</span>"<span class="p">);</span>
+ <span class="n">env</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">PROVIDER_URL</span><span class="p">,</span> "<span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">zanzibar</span><span class="p">:</span>636<span class="o">/</span><span class="n">o</span><span class="p">=</span><span class="n">sevenSeas</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">""</span><span class="p">);</span>
+ <span class="n">DirContext</span> <span class="n">ctx</span> <span class="p">=</span> <span class="n">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="p">=</span> <span class="n">ctx</span><span class="p">.</span><span class="n">list</span><span class="p">(</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="k">while</span> <span class="p">(</span><span class="n">enm</span><span class="p">.</span><span class="n">hasMore</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">System</span><span class="p">.</span><span class="n">out</span><span class="p">.</span><span class="n">println</span><span class="p">(</span><span class="n">enm</span><span class="p">.</span><span class="n">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="n">enm</span><span class="p">.</span><span class="n">close</span><span class="p">();</span>
+ <span class="n">ctx</span><span class="p">.</span><span class="n">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">"main"</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>
+<div class="codehilite"><pre>$ <span class="n">java</span> <span class="n">ConnectWithLdaps</span>
+<span class="n">Exception</span> <span class="n">in</span> <span class="n">thread</span> "<span class="n">main</span>" <span class="n">javax</span><span class="p">.</span><span class="n">naming</span><span class="p">.</span><span class="n">CommunicationException</span><span class="p">:</span>
+ <span class="n">simple</span> <span class="n">bind</span> <span class="n">failed</span><span class="p">:</span> <span class="n">zanzibar</span><span class="p">:</span>636
+ <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="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">SSLHandshakeException</span><span class="p">:</span>
+ <span class="n">sun</span><span class="p">.</span><span class="n">security</span><span class="p">.</span><span class="n">validator</span><span class="p">.</span><span class="n">ValidatorException</span><span class="p">:</span> <span class="n">PKIX</span> <span class="n">path</span> <span class="n">building</span> <span class="n">failed</span><span class="p">:</span>
+ <span class="n">sun</span><span class="p">.</span><span class="n">security</span><span class="p">.</span><span class="n">provider</span><span class="p">.</span><span class="n">certpath</span><span class="p">.</span><span class="n">SunCertPathBuilderException</span><span class="p">:</span>
+ <span class="n">unable</span> <span class="n">to</span> <span class="nb">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="p">.</span><span class="n">sun</span><span class="p">.</span><span class="n">jndi</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">LdapClient</span><span class="p">.</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="p">...</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"><zanzibar.cer></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>
+<div class="codehilite"><pre>$ <span class="n">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="p">.</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="p">.</span><span class="n">cer</span>
+<span class="n">Enter</span> <span class="n">keystore</span> <span class="n">password</span><span class="p">:</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="o"><</span><span class="n">zanzibar</span><span class="p">.</span><span class="n">cer</span><span class="o">></span>
+$ <span class="n">ls</span> <span class="o">-</span><span class="n">l</span>
+<span class="n">total</span> 6
+<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> 1 <span class="n">stefan</span> <span class="n">users</span> 504 <span class="n">Jun</span> 10 21<span class="p">:</span>51 <span class="n">zanzibar</span><span class="p">.</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> 1 <span class="n">stefan</span> <span class="n">users</span> 1275 <span class="n">Jun</span> 10 20<span class="p">:</span>42 <span class="n">zanzibar</span><span class="p">.</span><span class="n">ks</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>
+<div class="codehilite"><pre>$ <span class="n">keytool</span> <span class="o">-</span><span class="n">import</span> <span class="o">-</span><span class="n">file</span> <span class="n">zanzibar</span><span class="p">.</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="p">.</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="p">:</span> <span class="n">CN</span><span class="p">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="p">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="p">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="p">=</span><span class="n">US</span>
+<span class="n">Issuer</span><span class="p">:</span> <span class="n">CN</span><span class="p">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="p">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="p">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="p">=</span><span class="n">US</span>
+<span class="n">Serial</span> <span class="n">number</span><span class="p">:</span> 466<span class="n">c4611</span>
+<span class="n">Valid</span> <span class="n">from</span><span class="p">:</span> <span class="n">Sun</span> <span class="n">Jun</span> 10 20<span class="p">:</span>42<span class="p">:</span>25 <span class="n">CEST</span> 2007 <span class="n">until</span><span class="p">:</span> <span class="n">Tue</span> <span class="n">Jun</span> 09 20<span class="p">:</span>42<span class="p">:</span>25 <span class="n">CEST</span> 2009
+<span class="n">Certificate</span> <span class="n">fingerprints</span><span class="p">:</span>
+ <span class="n">MD5</span><span class="p">:</span> 95<span class="p">:</span>4<span class="n">A</span><span class="p">:</span>90<span class="p">:</span>3<span class="n">D</span><span class="p">:</span>69<span class="p">:</span>09<span class="p">:</span>64<span class="p">:</span>84<span class="p">:</span><span class="n">C7</span><span class="p">:</span>21<span class="p">:</span><span class="n">FD</span><span class="p">:</span><span class="n">F7</span><span class="p">:</span><span class="n">B8</span><span class="p">:</span>82<span class="p">:</span>11<span class="p">:</span>8<span class="n">C</span>
+ <span class="n">SHA1</span><span class="p">:</span> <span class="n">C5</span><span class="p">:</span>63<span class="p">:</span><span class="n">E0</span><span class="p">:</span><span class="n">DA</span><span class="p">:</span><span class="n">BB</span><span class="p">:</span><span class="n">C8</span><span class="p">:</span>0<span class="n">E</span><span class="p">:</span><span class="n">E8</span><span class="p">:</span>27<span class="p">:</span><span class="n">D0</span><span class="p">:</span>91<span class="p">:</span>1<span class="n">D</span><span class="p">:</span>28<span class="p">:</span><span class="n">DD</span><span class="p">:</span>11<span class="p">:</span><span class="n">BB</span><span class="p">:</span>93<span class="p">:</span>21<span class="p">:</span>13<span class="p">:</span><span class="n">C9</span>
+<span class="n">Trust</span> <span class="n">this</span> <span class="n">certificate</span>? <span class="p">[</span><span class="n">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>
+$ <span class="n">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="p">.</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="p">:</span> <span class="n">jks</span>
+<span class="n">Keystore</span> <span class="n">provider</span><span class="p">:</span> <span class="n">SUN</span>
+
+<span class="n">Your</span> <span class="n">keystore</span> <span class="n">contains</span> 1 <span class="n">entry</span>
+
+<span class="n">zanzibar</span><span class="p">,</span> <span class="n">Jun</span> 11<span class="p">,</span> 2007<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> 95<span class="p">:</span>4<span class="n">A</span><span class="p">:</span>90<span class="p">:</span>3<span class="n">D</span><span class="p">:</span>69<span class="p">:</span>09<span class="p">:</span>64<span class="p">:</span>84<span class="p">:</span><span class="n">C7</span><span class="p">:</span>21<span class="p">:</span><span class="n">FD</span><span class="p">:</span><span class="n">F7</span><span class="p">:</span><span class="n">B8</span><span class="p">:</span>82<span class="p">:</span>11<span class="p">:</span>8<span class="n">C</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>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. </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>
+<div class="codehilite"><pre>$ <span class="n">java</span> <span class="o">-</span><span class="n">Djavax</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">trustStore</span><span class="p">=</span><span class="n">trusted</span><span class="p">.</span><span class="n">ks</span> <span class="n">ConnectWithLdaps</span>
+<span class="n">ou</span><span class="p">=</span><span class="n">people</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">naming</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">DirContext</span>
+<span class="n">ou</span><span class="p">=</span><span class="n">groups</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">naming</span><span class="p">.</span><span class="n">directory</span><span class="p">.</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>
+<div class="codehilite"><pre>$ <span class="n">java</span> <span class="o">-</span><span class="n">Djavax</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">trustStore</span><span class="p">=</span><span class="n">trusted</span><span class="p">.</span><span class="n">ks</span> <span class="o">-</span><span class="n">Djavax</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">debug</span><span class="p">=</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">use</span> <span class="n">default</span> <span class="n">SunJSSE</span> <span class="n">impl</span> <span class="n">class</span><span class="p">:</span> <span class="n">com</span><span class="p">.</span><span class="n">sun</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">internal</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">SSLSocketFactoryImpl</span>
+<span class="n">class</span> <span class="n">com</span><span class="p">.</span><span class="n">sun</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">internal</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</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">is</span><span class="p">:</span> <span class="n">trusted</span><span class="p">.</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">adding</span> <span class="n">as</span> <span class="n">trusted</span> <span class="n">cert</span><span class="p">:</span>
+ <span class="n">Subject</span><span class="p">:</span> <span class="n">CN</span><span class="p">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="p">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="p">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="p">=</span><span class="n">US</span>
+ <span class="n">Issuer</span><span class="p">:</span> <span class="n">CN</span><span class="p">=</span><span class="n">zanzibar</span><span class="p">,</span> <span class="n">OU</span><span class="p">=</span><span class="n">ApacheDS</span><span class="p">,</span> <span class="n">O</span><span class="p">=</span><span class="n">ASF</span><span class="p">,</span> <span class="n">C</span><span class="p">=</span><span class="n">US</span>
+ <span class="n">Algorithm</span><span class="p">:</span> <span class="n">RSA</span><span class="p">;</span> <span class="n">Serial</span> <span class="n">number</span><span class="p">:</span> 0<span class="n">x466c4611</span>
+ <span class="n">Valid</span> <span class="n">from</span> <span class="n">Sun</span> <span class="n">Jun</span> 10 20<span class="p">:</span>42<span class="p">:</span>25 <span class="n">CEST</span> 2007 <span class="n">until</span> <span class="n">Tue</span> <span class="n">Jun</span> 09 20<span class="p">:</span>42<span class="p">:</span>25 <span class="n">CEST</span> 2009
<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="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="p">.</span><span class="n">sun</span><span class="p">.</span><span class="n">net</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">internal</span><span class="p">.</span><span class="n">ssl</span><span class="p">.</span><span class="n">SSLSocketFactoryImpl</span>
+<span class="c">%% No cached client session</span>
<span class="o">***</span> <span class="n">ClientHello</span><span class="p">,</span> <span class="n">TLSv1</span>
-<span class="o">...</span>
+<span class="p">...</span>
</pre></div>
Modified: websites/staging/directory/trunk/content/apacheds/coding-standards.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/coding-standards.html (original)
+++ websites/staging/directory/trunk/content/apacheds/coding-standards.html Fri Jun 21 10:04:38 2013
@@ -121,14 +121,18 @@
<h1 id="coding-standards">Coding Standards</h1>
<p>Welcome to you, developper ! You have been elected committer on the project, or you want to contribute some code or some patch? This is great news. However, in order to be able to share your 'vision' and your code, some rules must be followed.</p>
<p>Hey, remember that those rules are not the best nor the worst, they are pretty much what they are for historical reasons, or for technical reasons, however, please, accept them as they are, and avoid religious war (please, oh please, no mail to say "WTF ? You are using spaces instead of tab ??? How stupid is this rule etc etc.) Rules are <em><em>alway</em>s</em> stupid, but smart people follow them ;)</p>
-<p><DIV class="note" markdown="1">
-<strong>eclipse IDE</strong></p>
-<p>Eclipse users can import those two files to enfore the code formating : <a href="http://svn.apache.org/repos/asf/directory/project/trunk/resources/formatting.xml">formatting.xml</a> and <a href="http://svn.apache.org/repos/asf/directory/project/trunk/resources/codetemplates.xml">codetemplates.xml</a>
-</DIV></p>
-<p><DIV class="note" markdown="1">
-<strong>IDEA IDE</strong></p>
-<p>IDEA users can import <a href="settings.jar">this file</a> to enfore the code formating.
-</DIV></p>
+<DIV class="note" markdown="1">
+**eclipse IDE**
+
+Eclipse users can import those two files to enfore the code formating : [formatting.xml](http://svn.apache.org/repos/asf/directory/project/trunk/resources/formatting.xml) and [codetemplates.xml](http://svn.apache.org/repos/asf/directory/project/trunk/resources/codetemplates.xml)
+</DIV>
+
+<DIV class="note" markdown="1">
+**IDEA IDE**
+
+IDEA users can import [this file](settings.jar) to enfore the code formating.
+</DIV>
+
<h2 id="headers">Headers</h2>
<p>First, you <strong>must</strong> (and this rule accept no exception) use this header in top of all source file, or each file in which you can have comments :</p>
<div class="codehilite"><pre><span class="cm">/*</span>
@@ -165,9 +169,10 @@
</li>
</ul>
-<p><DIV class="note" markdown="1">
-Thanks to avoid to put your name. The code is not yours, and much more important, but putting ypur name and e-mail, you will intimidate other developper ("Oh, no, I won't mess with this code, it has been developped by XXXX !") and second, you will receive mail in three years even if you have stopped all commitment on the project (and those who have sent you an e-mail will think that the project's memeber are not responsive...)
-</DIV></p>
+<DIV class="note" markdown="1">
+Thanks to avoid to put your name. The code is not yours, and much more important, but putting ypur name and e-mail, you will intimidate other developper ("Oh, no, I won't mess with this code, it has been developped by XXXX \!") and second, you will receive mail in three years even if you have stopped all commitment on the project (and those who have sent you an e-mail will think that the project's memeber are not responsive...)
+</DIV>
+
<p>If you use <strong>html</strong> tags, remember to escape '<' and '>' characters...</p>
<h3 id="static-members-and-other-members">Static members and other members</h3>
<p>Just add a single line javadoc comment like : <em>/*<em> blah ... </em>/</em> before each member</p>
@@ -198,17 +203,19 @@ Thanks to avoid to put your name. The co
<p>If you browse the code, you will see that many classes does not respect those rules. That's life ! Don't fix it if you don't touch a class. If you are fixing a method in a class, then you can change the code to respect the rules. Little by little, we may reach a stable state where all the code respect the rules ;)</p>
<p>Naming is really important for <strong>APIs</strong>. Be smart. If you are not sure, ask.</p>
<h2 id="spaces-vs-tabs">Spaces vs tabs</h2>
-<p><DIV class="warning" markdown="1">
-<strong>FOUR SPACES, NO TAB. Final.</strong>
-</DIV></p>
+<DIV class="warning" markdown="1">
+**FOUR SPACES, NO TAB. Final.**
+</DIV>
+
<p>No discussion. Using tabs break diffs. Modify your <strong>IDE</strong> to insert spaces when you use tabs, before it saves the file.</p>
<h2 id="formatting">Formatting</h2>
<p>Use the <strong>formatting.xml</strong> file which can be found in the <strong>resources</strong> directory in the root of the project. This is for <em>Eclipse</em>. If you don't use eclipse, then translate the formating to your favorite <strong>IDE</strong>.</p>
<p>Use the <strong>codetemplates.xml</strong> file if you are using <em>Eclipse</em> too. You will find it at the same location. It brings you some standard headers for new classes, nex methods, etc.</p>
<p>Use <strong>UTF-8</strong> as a default for your files (except for properties, thanks to <strong>java</strong>, which should be in <strong>ISO-8859-1</strong>). Forget about exotic encoding...</p>
-<p><DIV class="warning" markdown="1">
-<strong>DO NOT USE AN AUTOMATIC FORMATER FOR COMMENTS!!!</strong>
-</DIV></p>
+<DIV class="warning" markdown="1">
+**DO NOT USE AN AUTOMATIC FORMATER FOR COMMENTS!!!**
+</DIV>
+
<p>People spend a lot of time making their comment looks like pretty, so if you just format them, you will have to recover the previous comments...</p>
<p>Some general rules :</p>
<ul>