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 2015/07/06 00:34:38 UTC
svn commit: r957126 [5/18] - in /websites/staging/directory/trunk/content:
./ apacheds/ apacheds/advanced-ug/ apacheds/basic-ug/
apacheds/configuration/ apacheds/kerberos-ug/ api/ api/download/
api/groovy-api/ api/user-guide/ escimo/ fortress/ fortress...
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/2.3.1-adding-schema-elements.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/2.3.1-adding-schema-elements.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/2.3.1-adding-schema-elements.html Sun Jul 5 22:34:35 2015
@@ -169,8 +169,19 @@
</div>
-<h1 id="231-adding-schema-elements">2.3.1 - Adding Schema Elements</h1>
-<h2 id="motivation">Motivation</h2>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="231-adding-schema-elements">2.3.1 - Adding Schema Elements<a class="headerlink" href="#231-adding-schema-elements" title="Permanent link">¶</a></h1>
+<h2 id="motivation">Motivation<a class="headerlink" href="#motivation" title="Permanent link">¶</a></h2>
<p>The schema of an LDAP server is comprised of object classes, attributes, syntaxes and matching rules. Basically it defines which entries are allowed within the server and how the server should handle them</p>
<DIV class="info" markdown="1">
**Is it always necessary to define my own schema elements?**
@@ -178,7 +189,7 @@ No. ApacheDS comes with a comprehensive
</DIV>
<p>In the following text the addition of user defined schema elements to the schema is described in tutorial style. </p>
-<h2 id="browsing-apacheds-schemas">Browsing ApacheDS schemas</h2>
+<h2 id="browsing-apacheds-schemas">Browsing ApacheDS schemas<a class="headerlink" href="#browsing-apacheds-schemas" title="Permanent link">¶</a></h2>
<p>LDAPv3 servers publish their schema via LDAP. Thus it is possible to list the schema elements with standard LDAP tools. For instance it is possible to use the ldapsearch command line tool to list all object classes</p>
<div class="codehilite"><pre>$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w ****** \
-b "cn=schema" -s base "(objectclass=subschema)" objectclasses
@@ -196,14 +207,14 @@ objectClasses: ( 2.5.6.6 NAME 'perso
<p>The schema subsystem of ApacheDS 1.5 stores the schema elements as entries in the DIT. You can find them within a special partition with suffix ou=schema; simply browse the content with your favorite LDAP Browser. With Apache Directory Studio, it looks like this:</p>
<p><img alt="ApacheDS Schemas" src="images/schema-browser-tree.png" /></p>
<p>Browsing the schema like this gives a good impression of the ApacheDS implementation of the schema subsystem and an even better way to analyze effects during schema updates. But keep in mind that the storage scheme is server dependent; not all LDAP server implementations store the schema elements in the DIT.</p>
-<h2 id="which-oids-should-you-use">Which OIDs should you use?</h2>
+<h2 id="which-oids-should-you-use">Which OIDs should you use?<a class="headerlink" href="#which-oids-should-you-use" title="Permanent link">¶</a></h2>
<p>If you plan to add custom schema elements, you need numerical OIDs (object identifiers) for them. If you implement schema elements defined somewhere else (like eduPerson), you can use the OIDs which are are part of their descriptions. But what if you plan to design your own?</p>
-<h3 id="some-oid-background-information">Some OID background information</h3>
+<h3 id="some-oid-background-information">Some OID background information<a class="headerlink" href="#some-oid-background-information" title="Permanent link">¶</a></h3>
<p>An OID is a string formed by a series of numbers which are separated by a dot (like "12.4.1971.0.1"). Many elements in directory world use OIDs: Controls, extended operations and schema elements (like "2.5.6.6" for object class person). They identify these objects in a unique fashion and therefore avoid name clashes.</p>
<p>How is this accomplished? OIDs are assigned hierarchically: The owner of an OID is allowed to create new IDs by simply appending numbers. S/he is also allowed to delegate ownership of newly created OIDs to someone else. This way every person or organization is able to allocate an arbitrary number of new OIDs after obtaining one from "higher command", and they are still unique world-wide.</p>
-<h3 id="oids-in-the-example">OIDs in the example</h3>
+<h3 id="oids-in-the-example">OIDs in the example<a class="headerlink" href="#oids-in-the-example" title="Permanent link">¶</a></h3>
<p>OIDs starting with <strong>1.3.6.1.4.1</strong> represent IANA-registered private enterprises, Apache Software Foundation for instance owns the OID <strong>1.3.6.1.4.1.18060</strong>. The <strong>1.3.6.1.4.1.18060.0</strong> has been assigned to the Apache Directory project by the ASF, and we have decided to use the branch "1.3.6.1.4.1.18060.0.4.3" for schema elements used as examples in the documentation. </p>
-<h3 id="oids-for-your-own-custom-schema-elements">OIDs for your own custom schema elements</h3>
+<h3 id="oids-for-your-own-custom-schema-elements">OIDs for your own custom schema elements<a class="headerlink" href="#oids-for-your-own-custom-schema-elements" title="Permanent link">¶</a></h3>
<p>If you just want to play around with the schema subsystem, want to explore the capabilities, or learn about LDAP in general, you will probably not mind about unique OIDs. This is comparable to using self-signed certificates for SSL experiments. But it is nevertheless necessary that you use OIDs which are not used in the schema yet (otherwise addition will fail).</p>
<p>But if you plan to use your schema elements in a production environment (an object class for instance which describes employees with company specific attributes), or to ship your schema elements with a product (e.g. a CRM or portal solution), you should definitely use unique OIDs. In order to do this you have to obtain OIDs from a branch assigned to your company or organization (your network administrators will be helpful here, do not invent OIDs without asking or obtaining a branch from someone who owns the prefix OID). If your company or organization does not own on OID, there are several option to obtain one, one is the IANA (Internet Assigned Numbers Authority). It is also possible to get an OID branch as an individual.</p>
<DIV class="info" markdown="1">
@@ -212,7 +223,7 @@ You can ask for your own PEN (Private En
It takes a few weeks to have a private OID assigned to you, so be patient, or do it early !
</DIV>
-<h2 id="a-simple-example">A simple example</h2>
+<h2 id="a-simple-example">A simple example<a class="headerlink" href="#a-simple-example" title="Permanent link">¶</a></h2>
<p>The goal is to store ship entries in our directory, backing the "Seven Seas" example used throughout the Basic User's Guide. There are no schema elements shipped with ApacheDS covering our naval requirements. So we add some.</p>
<p>Here is a sample entry for a ship in LDIF:</p>
<div class="codehilite"><pre>dn: cn=HMS Victory,ou=ships,o=sevenSeas
@@ -226,7 +237,7 @@ description: built between 1759 and 1765
<p>A ship entry is comprised of a mandatory value for common name (cn) of the ship, description values and the number of guns (numberOfGuns). Thus a new object class ship and a new attribute type numberOfGuns have to be added to the schema. There are different ways to accomplish the task. In any case, we have to add the attribute type first, because the object class refers to it.</p>
-<h4 id="attribute-type-numberofguns">attribute type numberOfGuns</h4>
+<h4 id="attribute-type-numberofguns">attribute type numberOfGuns<a class="headerlink" href="#attribute-type-numberofguns" title="Permanent link">¶</a></h4>
<p>Here is the definition of our custom attribute type numberOfGuns formatted according to RFC 4512.</p>
<div class="codehilite"><pre>( 1.3.6.1.4.1.18060.0.4.3.2.1
NAME 'numberOfGuns' DESC 'Number of guns of a ship'
@@ -236,7 +247,7 @@ description: built between 1759 and 1765
</pre></div>
-<h4 id="object-class-ship">object class ship</h4>
+<h4 id="object-class-ship">object class ship<a class="headerlink" href="#object-class-ship" title="Permanent link">¶</a></h4>
<p>Custom object class ship is defined as follows</p>
<div class="codehilite"><pre>( 1.3.6.1.4.1.18060.0.4.3.3.1
NAME 'ship' DESC 'An entry which represents a ship'
@@ -246,7 +257,7 @@ description: built between 1759 and 1765
</pre></div>
-<h2 id="using-apache-directory-studio-schema-editor-to-load-the-new-schema-elements">Using Apache Directory Studio Schema Editor to load the new schema elements</h2>
+<h2 id="using-apache-directory-studio-schema-editor-to-load-the-new-schema-elements">Using Apache Directory Studio Schema Editor to load the new schema elements<a class="headerlink" href="#using-apache-directory-studio-schema-editor-to-load-the-new-schema-elements" title="Permanent link">¶</a></h2>
<p>A very convenient way to add your own schema elements to Apache Directory Server is to use the Schema Editor of Apache Directory Studio. It is even possible to define/design them within the UI, but we opt here use a prepared file in OpenLDAP format and import it using Studio. This is a good choice if you have the schema to add already described that way.</p>
<p>Our file sevenSeas.schema looks like this:</p>
<div class="codehilite"><pre>attributetype ( 1.3.6.1.4.1.18060.0.4.3.2.1
@@ -273,14 +284,14 @@ objectclass ( 1.3.6.1.4.1.18060.0.4.3.3.
<p>Now, create a new schema project. Here, you have a choice :
* either you create a offline schema project
* or you create a project that will pull the schema from an existing ApacheDS server (it must be running, and a connection must have been created in Studio)</p>
-<h3 id="offline-schema-project">Offline schema project</h3>
+<h3 id="offline-schema-project">Offline schema project<a class="headerlink" href="#offline-schema-project" title="Permanent link">¶</a></h3>
<p>You need to create a new schema project, and to select the targeted server (either ApacheDS or OpenLDAP) :</p>
<p><img alt="Select target server" src="images/select-target-server.png" /></p>
<p>Then select all the schema you want to use this is necessary if you are to extend an AttributeType or an ObjectClass in your own schema)</p>
-<h3 id="connected-schema-project">Connected schema project</h3>
+<h3 id="connected-schema-project">Connected schema project<a class="headerlink" href="#connected-schema-project" title="Permanent link">¶</a></h3>
<p>In this case, you will see all the existing schema in the ApacheDS server you are connected to :</p>
<p><img alt="Connected Schema Project" src="images/connected-schema-project.png" /></p>
-<h3 id="creating-the-new-schema">Creating the new schema</h3>
+<h3 id="creating-the-new-schema">Creating the new schema<a class="headerlink" href="#creating-the-new-schema" title="Permanent link">¶</a></h3>
<p>Create the new schema you want to add by clicking on the 'schema creation' icon, as shown in the following picture :</p>
<p><img alt="Create Schema" src="images/create-schema.png" /></p>
<p>Now, you can add the Attribute Type or ObjectClasses you need in this added schema (see how to create schema elements in Apache Directory Studio documentation).</p>
@@ -292,7 +303,7 @@ In order to inject the modified schema,
<p>Once this is done, you hav to export the modifications in a format that will fit what is expected by ApacheDS. Right click on the schemas windows, select 'export-> Schemas for ApacheDS', and in the popup, select the schema you have added :</p>
<p><img alt="Export Schema" src="images/export-schema.png" /></p>
-<h3 id="importing-the-schema">Importing the schema</h3>
+<h3 id="importing-the-schema">Importing the schema<a class="headerlink" href="#importing-the-schema" title="Permanent link">¶</a></h3>
<p>The last step is to import the newly created LDIF into your ApacheDS instance. Just import it as any other LDIF, it will create a new element in your server schema :
<img alt="Import Schema" src="images/import-schema.png" /></p>
<p>You should see your schema into the list of supported schemas.</p>
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/3-basic-security.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/3-basic-security.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/3-basic-security.html Sun Jul 5 22:34:35 2015
@@ -169,9 +169,20 @@
</div>
-<h1 id="3-basic-security">3 - Basic Security</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="3-basic-security">3 - Basic Security<a class="headerlink" href="#3-basic-security" title="Permanent link">¶</a></h1>
<p>This chapter expose the basic security configuration you can setup. It covers simple authentication, authorization and SSL.</p>
-<h2 id="table-of-content">Table of content</h2>
+<h2 id="table-of-content">Table of content<a class="headerlink" href="#table-of-content" title="Permanent link">¶</a></h2>
<ul>
<li><a href="3.1-authentication-options.html">3.1 - Authentication options</a></li>
<li><a href="3.2-basic-authorization.html">3.2 - Basic authorization</a></li>
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/3.1-authentication-options.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/3.1-authentication-options.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/3.1-authentication-options.html Sun Jul 5 22:34:35 2015
@@ -169,7 +169,18 @@
</div>
-<h1 id="31-authentication-options">3.1 - Authentication options</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="31-authentication-options">3.1 - Authentication options<a class="headerlink" href="#31-authentication-options" title="Permanent link">¶</a></h1>
<p>This section describes the authentication options of ApacheDS 2.0. Anonymous and simple binds are supported, as well as SASL mechanisms. Configuring and using the first two of them is described below with the help of examples.</p>
<div class="toc">
<ul>
@@ -207,14 +218,14 @@
</li>
</ul>
</div>
-<h2 id="what-is-authentication">What is authentication?</h2>
+<h2 id="what-is-authentication">What is authentication?<a class="headerlink" href="#what-is-authentication" title="Permanent link">¶</a></h2>
<p><em>Authentication</em> is the process of determining whether someone (or something) in fact is what he/she/it asserts to be. </p>
<p>Within ApacheDS you will likely want to authenticate clients in order to check whether they are allowed to read, add or manipulate certain data stored within the directory. The latter, i.e. whether an authenticated client is permitted to do something, is deduced during <em>authorization</em>.</p>
<p>Quite often, the process of authentication is delegated to a directory service by other software components. Because in doing so, authentication data (e.g. username, password) and authorization data (e.g. group relationships) are stored and managed centrally in the directory, and all connected software solutions benefit from it. The integration sections of this guide provide examples for Apache Tomcat, Apache HTTP servers, and others.</p>
<p>ApacheDS 2.0 supports simple authentication and anonymous binds while storing passwords within <em>userPassword</em> attributes in user entries. Passwords can be stored in clear text or one-way encrypted with a hash algorithm like MD5 or SHA1. Since version 1.5.1, SASL mechanism are supported as well. We start with anonymous binds. </p>
-<h2 id="simple-binds">Simple binds</h2>
+<h2 id="simple-binds">Simple binds<a class="headerlink" href="#simple-binds" title="Permanent link">¶</a></h2>
<p>Authentication via simple bind is widely used. The method is supported by ApacheDS 2.0 for all person entries stored within any partition, if they contain a password attribute. How does it work? An LDAP client provides the DN of a user entry and a password to the server, the parameters of the bind operation. ApacheDS checks whether the given password is the same as the one stored in the <em>userpassword</em> attribute of the given entry. If not, the bind operation fails (LDAP error code 49, LDAP_INVALID_CREDENTIALS), and the user is not authenticated.</p>
-<h3 id="using-command-line-tools">Using command line tools</h3>
+<h3 id="using-command-line-tools">Using command line tools<a class="headerlink" href="#using-command-line-tools" title="Permanent link">¶</a></h3>
<p>Assume this entry from the Seven Seas partition is stored within the directory (only a fragment with the relevant attributes is shown).</p>
<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">cn</span><span class="o">=</span><span class="n">Horatio</span> <span class="n">Hornblower</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">people</span><span class="o">,</span><span class="n">o</span><span class="o">=</span><span class="n">sevenSeas</span>
<span class="n">objectclass</span><span class="o">:</span> <span class="n">person</span>
@@ -246,7 +257,7 @@
</pre></div>
-<h3 id="binds-from-java-components-using-jndi">Binds from Java components using JNDI</h3>
+<h3 id="binds-from-java-components-using-jndi">Binds from Java components using JNDI<a class="headerlink" href="#binds-from-java-components-using-jndi" title="Permanent link">¶</a></h3>
<p>Using JNDI, authentication via simple binds is accomplished by appropriate configuration. One option is to provide the parameters in a Hashtable object like this</p>
<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.util.Hashtable</span><span class="o">;</span>
@@ -304,13 +315,13 @@
<p>In real life, you obviously want to separate most of the configuration data from the source code, for instance with the help of the <em>jndi.properties</em> file.</p>
-<h2 id="passwords-stored-one-way-encrypted">Passwords stored one-way encrypted</h2>
+<h2 id="passwords-stored-one-way-encrypted">Passwords stored one-way encrypted<a class="headerlink" href="#passwords-stored-one-way-encrypted" title="Permanent link">¶</a></h2>
<p>If passwords are stored in the directory in clear like above, the administrator (<em>uid=admin,ou=system</em>) is able to read them. This holds true even if authorization is enabled. The passwords would also be visible in exported LDIF files. This is often unacceptable.</p>
<DIV class="warning" markdown="1">
Not only the administrator will be able to read your password, or be visible in LDIF files, but if one does not use SSL, the password is transmitted in clear text above the wire...
</DIV>
-<h3 id="passwords-not-stored-in-clear-text">Passwords not stored in clear text</h3>
+<h3 id="passwords-not-stored-in-clear-text">Passwords not stored in clear text<a class="headerlink" href="#passwords-not-stored-in-clear-text" title="Permanent link">¶</a></h3>
<p>ApacheDS does also support simple binds, if user passwords are stored one-way encrypted. An LDAP client, which creates user entries, applies a hash-function (SHA for instance) to the user passwords beforehand, and stores the users with these fingerprints as <em>userpassword</em> values (instead of the clear text values), for instance:</p>
<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">cn</span><span class="o">=</span><span class="n">Horatio</span> <span class="n">Hornblower</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">people</span><span class="o">,</span><span class="n">o</span><span class="o">=</span><span class="n">sevenSeas</span>
<span class="n">objectclass</span><span class="o">:</span> <span class="n">person</span>
@@ -323,7 +334,7 @@ Not only the administrator will be able
<p>The value "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=" means that <em>SHA</em> (Secure Hash Algorithm) was applied to the password, and "nU4eI71bcnBGqeO0t9tXvY1u5oQ=" was the result (Base-64 encoded). Please note that it is not possible to calculate the source ("pass" in our case) back from the result. This is why it is called one-way encrypted -- it is rather difficult to decrypt it. One may guess many times, calculate the hash values (the algorithms are public) and compare the result. But this would take a long time, especially if you choose a more complex password than we did ("pass"). </p>
-<h3 id="but-how-to-obtain-the-hash-value-for-a-password">But how to obtain the hash value for a password?</h3>
+<h3 id="but-how-to-obtain-the-hash-value-for-a-password">But how to obtain the hash value for a password?<a class="headerlink" href="#but-how-to-obtain-the-hash-value-for-a-password" title="Permanent link">¶</a></h3>
<p>With some lines of code, it is quite easy to accomplish this task programatically in Java:</p>
<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.security.MessageDigest</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">java.security.NoSuchAlgorithmException</span><span class="o">;</span>
@@ -351,7 +362,7 @@ Not only the administrator will be able
<p>The output is "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=".</p>
<p>Another option is to use command line tools to calculate the hash value; the <a href="http://www.openssl.org">OpenSSL</a> project provides such stuff. Furthermore many UI LDAP tools allow you to store passwords automatically encrypted with the hash algorithm of your choice. See below <a href="http://directory.apache.org/studio/">Apache Directory Studio</a> as an example. The dialog automatically shows up if a <em>userPassword</em> attribute is to be manipulated (added, changed).</p>
<p><img alt="Password Edit" src="images/password-edit-ls.png" /></p>
-<h3 id="from-an-ldap-client-point-of-view">From an LDAP client point of view</h3>
+<h3 id="from-an-ldap-client-point-of-view">From an LDAP client point of view<a class="headerlink" href="#from-an-ldap-client-point-of-view" title="Permanent link">¶</a></h3>
<p>From an LDAP client point of view, the behavior during authentication is the same as with passwords stored in clear. During a simple bind, a client sends DN and password (unencrypted, i.e. no hash algorithm applied) to the server. If ApacheDS detects, that the user password for the given DN is stored in the directory with a hash function applied, it calculates the hash value of the given password with the appropriate algorithm (this is why the algorithm is stored together with the hashed password). Afterwards it compares the result with the stored attribute value. In case of a match, the bind operation ends successfully:</p>
<div class="codehilite"><pre>$ <span class="n">ldapsearch</span> <span class="o">-</span><span class="n">h</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">p</span> 10389 <span class="o">-</span><span class="n">D</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="o">\\</span>
<span class="o">-</span><span class="n">w</span> <span class="n">pass</span> <span class="o">-</span><span class="n">b</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="o">-</span><span class="n">s</span> <span class="n">base</span> "<span class="p">(</span><span class="n">objectclass</span><span class="p">=</span><span class="o">*</span><span class="p">)</span>"
@@ -381,11 +392,11 @@ Please note that storing user passwords
Furthermore, if someone gets an LDIF file with userpassword values digested with SHA etc., s/he may be able to determine some of the passwords with brute force. Calculation of hash functions can be done very fast, and the attacker can attempt millions of values with ease, without you getting notice of it. Therefore protect your data, even if one-way encryption is applied to the passwords!
</DIV>
-<h2 id="anonymous-binds">Anonymous binds</h2>
+<h2 id="anonymous-binds">Anonymous binds<a class="headerlink" href="#anonymous-binds" title="Permanent link">¶</a></h2>
<p>In some occasions it is appropriate to allow LDAP clients to permit operations without authentication. If data managed by the directory service is well known by all clients, it is not uncommon to allow search operations (not manipulation) within this data to all clients -- without providing credentials. An example for this are enterprise wide telephone books, if clients access the directory service from the intranet.</p>
-<h3 id="enabledisable-anonymous-binds">Enable/disable anonymous binds</h3>
+<h3 id="enabledisable-anonymous-binds">Enable/disable anonymous binds<a class="headerlink" href="#enabledisable-anonymous-binds" title="Permanent link">¶</a></h3>
<p>Anonymous access is enabled by default. Changing this is one of the basic configuration tasks (see <a href="1.4.5-anonymous-access.html">1.4.5 - Enable and disable anonymous access</a>).</p>
-<h3 id="example-server-behavior-with-anonymous-binds-disabled">Example: Server behavior with anonymous binds disabled</h3>
+<h3 id="example-server-behavior-with-anonymous-binds-disabled">Example: Server behavior with anonymous binds disabled<a class="headerlink" href="#example-server-behavior-with-anonymous-binds-disabled" title="Permanent link">¶</a></h3>
<p>Assume anonymous binds are disabled and our sample partition <em>Seven Seas</em> present in the server. Here is an example with a search operation performed by a command line tool as a client. It tries to connect anonymously (no DN and password given, i.e. options -D and -w missing) to the server. Afterwards the entry <em>ou=people,o=sevenSeas</em> should be displayed.</p>
<p>See the command and the resulting error message provided by the server below </p>
<div class="codehilite"><pre>$ <span class="n">ldapsearch</span> <span class="o">-</span><span class="n">h</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">p</span> 10389 <span class="o">-</span><span class="n">b</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="o">-</span><span class="n">s</span> <span class="n">one</span> "<span class="p">(</span><span class="n">objectclass</span><span class="p">=</span><span class="o">*</span><span class="p">)</span>"
@@ -394,7 +405,7 @@ Furthermore, if someone gets an LDIF fil
</pre></div>
-<h3 id="example-server-behavior-with-anonymous-binds-enabled">Example: Server behavior with anonymous binds enabled</h3>
+<h3 id="example-server-behavior-with-anonymous-binds-enabled">Example: Server behavior with anonymous binds enabled<a class="headerlink" href="#example-server-behavior-with-anonymous-binds-enabled" title="Permanent link">¶</a></h3>
<p>Now the same command performed against ApacheDS 1.5 with anonymous access enabled as described above. The behavior is different -- the entry is visible. </p>
<div class="codehilite"><pre>$ <span class="n">ldapsearch</span> <span class="o">-</span><span class="n">h</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">p</span> 10389 <span class="o">-</span><span class="n">b</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="o">-</span><span class="n">s</span> <span class="n">base</span> "<span class="p">(</span><span class="n">objectclass</span><span class="p">=</span><span class="o">*</span><span class="p">)</span>"
<span class="n">version</span><span class="p">:</span> 1
@@ -406,7 +417,7 @@ Furthermore, if someone gets an LDIF fil
</pre></div>
-<h3 id="other-clients">Other clients</h3>
+<h3 id="other-clients">Other clients<a class="headerlink" href="#other-clients" title="Permanent link">¶</a></h3>
<p>The examples above have used a command line tool. Of course graphical tools and programmatical access (JNDI etc.) allow anonymous binds as well. Below is a screen shot from the configuration dialog of <a href="http://directory.apache.org/studio/">Apache Directory Studio</a> as an example. During configuration of the connection data ("New LDAP Connection", for instance), the option <em>Anonymous Authentication</em> leads to anonymous binds. Other UI tools offer this feature as well.</p>
<p><img alt="Authentication options" src="images/authentication-options-ls.png" /></p>
<DIV class="note" markdown="1">
@@ -415,7 +426,7 @@ Furthermore, if someone gets an LDIF fil
With anonymous access enabled it is not only possible to search the directory without providing username and password. With autorization disabled, anonymous users may also be able to modify data. It is therefore highly recommended to enable and configure the authorization subsystem as well. Learn more about authorization in the [3.2. Basic authorization] section.
</DIV>
-<h2 id="how-to-authenticate-a-user-by-uid-and-password">How to authenticate a user by uid and password?</h2>
+<h2 id="how-to-authenticate-a-user-by-uid-and-password">How to authenticate a user by uid and password?<a class="headerlink" href="#how-to-authenticate-a-user-by-uid-and-password" title="Permanent link">¶</a></h2>
<p>If you want to use simple binds with user DN and password within a Java component, in order to authenticate users programatically, in practice one problem arises: Most users do not know their DN. Therefore they will not be able to enter it. And even if they know it, it would be frequently very laborious due to the length of the DN. It would be easier for a user if s/he only has to probvide a short, unique <em>ID</em> and the password, like in this web form</p>
<p><img alt="Confluence Logon" src="images/confluence-logon.png" /></p>
<p>Usually the ID is an attribute within the user's entry. In our sample data (Seven Seas), each user entry contains the <em>uid</em> attribute, for instance uid=hhornblo for Captain Hornblower:</p>
@@ -435,14 +446,14 @@ With anonymous access enabled it is not
<p>But how to authenticate a user who provides "hhornblo"/"pass" instead of "cn=Horatio Hornblower,ou=people,o=sevenSeas"/"pass" with the help of ApacheDS?</p>
-<h3 id="an-algorithm">An algorithm</h3>
+<h3 id="an-algorithm">An algorithm<a class="headerlink" href="#an-algorithm" title="Permanent link">¶</a></h3>
<p>In order to accomplish this task programmatically, one option is to perform the following steps</p>
-<h4 id="arguments">Arguments</h4>
+<h4 id="arguments">Arguments<a class="headerlink" href="#arguments" title="Permanent link">¶</a></h4>
<ul>
<li><em>uid</em> of a user (e.g. "hhornblo")</li>
<li><em>password</em> proclaimed to be correct for the user</li>
</ul>
-<h4 id="steps">Steps</h4>
+<h4 id="steps">Steps<a class="headerlink" href="#steps" title="Permanent link">¶</a></h4>
<ul>
<li>Bind to ApacheDS anonymously, or with the DN of a technical user. In both cases it must be possible to search the directory afterwards (authorization has to be configured that way)</li>
<li>Perform a search operation with an appropriate filter to find the user entry for the given ID, in our case "(&(objectClass=inetorgperson)(uid=hhornblo))"<ul>
@@ -456,7 +467,7 @@ With anonymous access enabled it is not
</ul>
</li>
</ul>
-<h3 id="sample-code-with-jndi">Sample code with JNDI</h3>
+<h3 id="sample-code-with-jndi">Sample code with JNDI<a class="headerlink" href="#sample-code-with-jndi" title="Permanent link">¶</a></h3>
<p>The algorithm described above is implemented by many software solutions which are able to integrate LDAP directories. You will learn more about some of them and their configuration options within a later section of this guide.</p>
<p>For illustration purposes, here is a simple Java program which performs the steps with the help of JNDI. It uses anonymous bind for the first step, hence it must be enabled (replace with a technical user, if it better meets your requirements). </p>
<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.util.Hashtable</span><span class="o">;</span>
@@ -547,7 +558,7 @@ $ <span class="n">java</span> <span clas
<p>The examples consist of an unknown user (an <em>inetOrgPerson</em> entry with uid=unknown does not exist), a successful authenttication, and an attempt with an existing uid but a wrong password. </p>
-<h2 id="resources">Resources</h2>
+<h2 id="resources">Resources<a class="headerlink" href="#resources" title="Permanent link">¶</a></h2>
<ul>
<li><a href="http://www.faqs.org/rfcs/rfc2829.html">RFC 2829</a> Authentication Methods for LDAP </li>
<li><a href="http://www.secure-hash-algorithm-md5-sha-1.co.uk/">The Secure Hash Algorithm Directory</a> MD5, SHA-1 and HMAC Resources</li>
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/3.2-basic-authorization.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/3.2-basic-authorization.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/3.2-basic-authorization.html Sun Jul 5 22:34:35 2015
@@ -169,7 +169,18 @@
</div>
-<h1 id="32-basic-authorization">3.2 - Basic authorization</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="32-basic-authorization">3.2 - Basic authorization<a class="headerlink" href="#32-basic-authorization" title="Permanent link">¶</a></h1>
<p>This section describes the default authorization functionality of ApacheDS 1.5, which is very simple. On the other hand, it is inadequate for most serious deployments. Therefore a basic example to the "real" authorization subsystem is provided as well.</p>
<div class="toc">
<ul>
@@ -206,10 +217,10 @@
</li>
</ul>
</div>
-<h2 id="what-is-authorization">What is authorization?</h2>
+<h2 id="what-is-authorization">What is authorization?<a class="headerlink" href="#what-is-authorization" title="Permanent link">¶</a></h2>
<p>After authentication of a user or an application (or more generally an LDAP client) against the directory server (or attaining anonymous access respectively), certain LDAP operations will be granted or rejected, according to configuration and certain rules. This process of granting access is called authorization.</p>
<p>Authorization for directory operations is not strictly standardized in the LDAP world, <a href="http://www.faqs.org/rfcs/rfc2829.html">RFC 2829 - Authentication Methods for LDAP</a> describes various scenarios and concepts, but does not enforce a concrete implementation. Thus each product comes with its own authorization feature. So does ApacheDS. A powerful authorization subsystem is provided since version 0.9.3, but disabled as a default.</p>
-<h3 id="authorization-for-directory-operations-vs-group-membership">Authorization for directory operations vs. group membership</h3>
+<h3 id="authorization-for-directory-operations-vs-group-membership">Authorization for directory operations vs. group membership<a class="headerlink" href="#authorization-for-directory-operations-vs-group-membership" title="Permanent link">¶</a></h3>
<p>In order to accomplish their authorization functionality, software components often take advantage of LDAP groups stored within the directory. <em>groupOfNames</em> and <em>groupOfUniqueNames</em> are common object classes for groups entries; they contain the DNs of their members (users, other groups) as attribute values. </p>
<p>In order to illustrate this, the "Seven Seas" example partition contains such group entries below "ou=groups,o=sevenSeas". Here the entry of a group describing the HMS Bounty crew (before the mutiny) in LDIF format.</p>
<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">cn</span><span class="o">=</span><span class="n">HMS</span> <span class="n">Bounty</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">crews</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">groups</span><span class="o">,</span><span class="n">o</span><span class="o">=</span><span class="n">sevenSeas</span>
@@ -224,9 +235,9 @@
<p>In such a scenario, a user, who is directly or indirectly member of a certain group is permitted to do something. The software component acts as a normal LDAP client and determines group belonging with the help of ordinary search operations. This is widely used but has nothing to do with the authorization for directory operations as described in this section (except that the client needs the permission to search the data). Learn more about best practices in this area in the article <a href="http://middleware.internet2.edu/dir/groups/docs/internet2-mace-dir-groups-best-practices-200210.htm">Practices in Directory Groups</a>. Further examples in this guide are the Tomcat and Apache HTTPD integration sections.</p>
-<h2 id="default-authorization-behavior-for-directory-operations">Default authorization behavior for directory operations</h2>
+<h2 id="default-authorization-behavior-for-directory-operations">Default authorization behavior for directory operations<a class="headerlink" href="#default-authorization-behavior-for-directory-operations" title="Permanent link">¶</a></h2>
<p>Without access controls enabled all entries are accessible and alterable by all: even anonymous users. There are however some minimal built-in rules for protecting users and groups within the server without having to turn on the ACI subsystem.</p>
-<h3 id="sample-data-within-ouusersousystem">Sample data within "ou=users,ou=system"</h3>
+<h3 id="sample-data-within-ouusersousystem">Sample data within "ou=users,ou=system"<a class="headerlink" href="#sample-data-within-ouusersousystem" title="Permanent link">¶</a></h3>
<p>In addition to our brave sailors below <em>ou=people,o=sevenSeas</em>, assume the following to entries present within <em>ou=users,ou=system</em>:</p>
<p><img alt="Authorization Sample Entries" src="images/authorization-sample-entries.png" /></p>
<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">cn</span><span class="o">=</span><span class="n">Tori</span> <span class="n">Amos</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">users</span><span class="o">,</span><span class="n">ou</span><span class="o">=</span><span class="n">system</span>
@@ -246,7 +257,7 @@
<p>They are used in the following examples, in conjunction with <em>o=sevenSeas</em>, to describe the default authorization rules.</p>
-<h3 id="rules-and-sample-operations">Rules and sample operations</h3>
+<h3 id="rules-and-sample-operations">Rules and sample operations<a class="headerlink" href="#rules-and-sample-operations" title="Permanent link">¶</a></h3>
<p>Without ACIs the server automatically protects, hides, the admin user from everyone but the admin user. Here a sample search operation in order to demonstrate this protection. The same command is submitted three times with different users.</p>
<div class="codehilite"><pre>$ <span class="n">ldapsearch</span> <span class="o">-</span><span class="n">h</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">p</span> 10389 <span class="o">-</span><span class="n">D</span> "<span class="n">uid</span><span class="p">=</span><span class="n">admin</span><span class="p">,</span><span class="n">ou</span><span class="p">=</span><span class="n">system</span>" <span class="o">-</span><span class="n">w</span> <span class="n">secret</span> <span class="o">\\</span>
<span class="o">-</span><span class="n">b</span> "<span class="n">ou</span><span class="p">=</span><span class="n">system</span>" <span class="o">-</span><span class="n">s</span> <span class="n">one</span> "<span class="p">(</span><span class="n">uid</span><span class="p">=</span><span class="n">admin</span><span class="p">)</span>" <span class="n">dn</span>
@@ -297,22 +308,22 @@ $
<p>Groups defined using <em>groupOfNames</em> or <em>groupOfUniqueNames</em> under the 'ou=groups,ou=system' are also protected from access or alteration by anyone other than the admin user. Again this protection is not allowed anywhere else but under these entries.</p>
-<h3 id="is-this-sufficient">Is this sufficient?</h3>
+<h3 id="is-this-sufficient">Is this sufficient?<a class="headerlink" href="#is-this-sufficient" title="Permanent link">¶</a></h3>
<p>For simple configurations the described rules should provide adequate protection but it lacks flexibility. For advanced configurations users should enable the ACI subsystem. This however shuts down access to everything by everyone except the admin user which bypasses the ACI subsystem. Directory administrators should look at the documentation on how to specify access control information in the Advanced User's Guide.</p>
-<h2 id="simple-example-for-the-aci-subsystem">Simple example for the ACI subsystem</h2>
+<h2 id="simple-example-for-the-aci-subsystem">Simple example for the ACI subsystem<a class="headerlink" href="#simple-example-for-the-aci-subsystem" title="Permanent link">¶</a></h2>
<p>As an appetizer for the stunning ACI subsystem (ACI = access control item) within ApacheDS, we provide a simple yet realistic example. It manifests the following requirements</p>
-<h3 id="requirements-met">Requirements met</h3>
+<h3 id="requirements-met">Requirements met<a class="headerlink" href="#requirements-met" title="Permanent link">¶</a></h3>
<ul>
<li>Suffix "o=sevenSeas" used as Access Control Specific Area</li>
<li>User "cn=Horatio Nelson,ou=people,o=sevenSeas" should be able to perform all operations (delete, add, ...) below the base "o=sevenSeas"</li>
<li>Other users and anonymous users should only be able to search and compare (no add, modify etc.)</li>
<li>Other users and anonymous users should not be able to read the userPassword attribute</li>
</ul>
-<h3 id="enable-the-aci-subsystem">Enable the ACI Subsystem</h3>
+<h3 id="enable-the-aci-subsystem">Enable the ACI Subsystem<a class="headerlink" href="#enable-the-aci-subsystem" title="Permanent link">¶</a></h3>
<p>The authorization (ACI) subsystem is disabled by default. You have to enable it using the <em>Apache Directory Studio</em> configuration editor :</p>
<p><img alt="Enable access control" src="images/enable-access-control.png" /></p>
<p>A restart of the server is necessary for this change to take effect. </p>
-<h3 id="further-configuration-tasks-to-perform-afterwards">Further configuration tasks to perform afterwards</h3>
+<h3 id="further-configuration-tasks-to-perform-afterwards">Further configuration tasks to perform afterwards<a class="headerlink" href="#further-configuration-tasks-to-perform-afterwards" title="Permanent link">¶</a></h3>
<ol>
<li>Create an operational attribute <em>administrativeRole</em> with value "accessControlSpecificArea" in the entry "o=sevenSeas".</li>
<li>Create a subentry subordinate to "o=sevenSeas" to grant all operations' permissions to "cn=Horatio Nelson,ou=people,o=sevenSeas", who acts as directory manager </li>
@@ -444,7 +455,7 @@ $
</pre></div>
-<h3 id="ldif-for-this-configuration">LDIF for this configuration</h3>
+<h3 id="ldif-for-this-configuration">LDIF for this configuration<a class="headerlink" href="#ldif-for-this-configuration" title="Permanent link">¶</a></h3>
<p>The following LDIF file ([^authz_sevenSeas.ldif]) provides a set of changes made to directory entries in the "Seven Seas" data. In total it performs the steps described above. </p>
<div class="codehilite"><pre><span class="c"># File authz_sevenSeas.ldif</span>
<span class="c">#</span>
@@ -532,9 +543,9 @@ $
<p>It is also possible to use graphical tools; some of them offer the feature to perform operations given in LDIF.</p>
-<h2 id="verification-that-it-works">Verification, that it works</h2>
+<h2 id="verification-that-it-works">Verification, that it works<a class="headerlink" href="#verification-that-it-works" title="Permanent link">¶</a></h2>
<p>After successfully applying the changes to the sample partition, one may ask how to check whether it works. We therefore perform some operations with the help of command line tools. Some will be permitted, some will not (and cause an appropriate error message). It would also be able to check this with the help of graphical tools (you might like to do this instead). But it is easier to document the parameters used with the help command line arguments. </p>
-<h3 id="performing-some-search-operations-in-order-to-read-data">Performing some search operations in order to read data</h3>
+<h3 id="performing-some-search-operations-in-order-to-read-data">Performing some search operations in order to read data<a class="headerlink" href="#performing-some-search-operations-in-order-to-read-data" title="Permanent link">¶</a></h3>
<p>Bind as user "William Bush" and search for entries which match "(uid=hhornblo)". Expected behavior: We are able to read the attributes of entry "cn=Horatio Hornblower,ou=people,o=sevenSeas" (the only entry which matches the filter). The password attribute should not be visible. It works as desired: </p>
<div class="codehilite"><pre>$ <span class="n">ldapsearch</span> <span class="o">-</span><span class="n">h</span> <span class="n">zanzibar</span> <span class="o">-</span><span class="n">p</span> 10389 <span class="o">-</span><span class="n">D</span> "<span class="n">cn</span><span class="p">=</span><span class="n">William</span> <span class="n">Bush</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="o">-</span><span class="n">w</span> <span class="n">pass</span> <span class="o">\\</span>
<span class="o">-</span><span class="n">b</span> "<span class="n">o</span><span class="p">=</span><span class="n">sevenSeas</span>" <span class="o">-</span><span class="n">s</span> <span class="n">sub</span> "<span class="p">(</span><span class="n">uid</span><span class="p">=</span><span class="n">hhornblo</span><span class="p">)</span>"
@@ -600,9 +611,9 @@ $ <span class="n">ldapsearch</span> <spa
</pre></div>
-<h3 id="trying-to-manipulate-data">Trying to manipulate data</h3>
+<h3 id="trying-to-manipulate-data">Trying to manipulate data<a class="headerlink" href="#trying-to-manipulate-data" title="Permanent link">¶</a></h3>
<p>Until now the authorization only hided data (entries, attributes) from users with insufficient access rights. Let's perform some operations which try to manipulate the directory data! </p>
-<h4 id="adding-an-entry">Adding an entry</h4>
+<h4 id="adding-an-entry">Adding an entry<a class="headerlink" href="#adding-an-entry" title="Permanent link">¶</a></h4>
<p>First we try to add a new user to the "Seven Seas" partition. The data for the entry is inspired by "Peter Pan" and provided by this LDIF file (<a href="resources/captain-hook.ldif">Captain hook</a>): </p>
<div class="codehilite"><pre><span class="c"># File captain_hook.ldif</span>
<span class="n">dn</span><span class="p">:</span> <span class="n">cn</span><span class="p">=</span><span class="n">James</span> <span class="n">Hook</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>
@@ -651,7 +662,7 @@ $
</pre></div>
-<h4 id="modifying-an-entry">Modifying an entry</h4>
+<h4 id="modifying-an-entry">Modifying an entry<a class="headerlink" href="#modifying-an-entry" title="Permanent link">¶</a></h4>
<p>As a further example which tries to write to the directory, we add a new value to the description attribute of the freshly created entry for Captain Hook. With a change entry in an LDIF file, it looks like this (file <a href="resources/captain-hook-modify.ldif">Captain Hook</a>):</p>
<div class="codehilite"><pre><span class="c"># File captain_hook_modify.ldif</span>
<span class="n">dn</span><span class="p">:</span> <span class="n">cn</span><span class="p">=</span><span class="n">James</span> <span class="n">Hook</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>
@@ -680,7 +691,7 @@ $ <span class="n">ldapmodify</span> <spa
</pre></div>
-<h4 id="deleting-an-entry">Deleting an entry</h4>
+<h4 id="deleting-an-entry">Deleting an entry<a class="headerlink" href="#deleting-an-entry" title="Permanent link">¶</a></h4>
<p>Now it is finale time. A demonstration on how to delete the villain's entry from the directory. With an LDIF file (<a href="resources/captain-hook-delete.ldif">Captain hook delete</a>) with an appropriate change entry, this can easily be accomplished, if the bind user is allowed to do so. </p>
<div class="codehilite"><pre><span class="c"># File captain_hook_delete.ldif</span>
<span class="n">dn</span><span class="p">:</span> <span class="n">cn</span><span class="p">=</span><span class="n">James</span> <span class="n">Hook</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>
@@ -708,7 +719,7 @@ $
<p>The entry "cn=James Hook,ou=people,o=sevenSeas" has been successfully deleted from the partition. Our little demonstration on how the ACI subsystem with a realistic configuration behaves end here. Learn more about it in the Advanced User's Guide.</p>
-<h2 id="resources">Resources</h2>
+<h2 id="resources">Resources<a class="headerlink" href="#resources" title="Permanent link">¶</a></h2>
<ul>
<li><a href="http://middleware.internet2.edu/dir/groups/docs/internet2-mace-dir-groups-best-practices-200210.htm">Practices in Directory Groups</a> describes how to use groups within LDAP directories. Highly recommended.</li>
<li>The <a href="../advanced-users-guide.html">ApacheDS v1.0 Advanced User's Guide</a> provides a detailed authorization chapter</li>
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 Sun Jul 5 22:34:35 2015
@@ -169,7 +169,18 @@
</div>
-<h1 id="33-how-to-enable-ssl">3.3 - How to enable SSL</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="33-how-to-enable-ssl">3.3 - How to enable SSL<a class="headerlink" href="#33-how-to-enable-ssl" title="Permanent link">¶</a></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>
@@ -197,7 +208,7 @@
</li>
</ul>
</div>
-<h2 id="transport-layer-security-and-ldap">Transport layer security and LDAP</h2>
+<h2 id="transport-layer-security-and-ldap">Transport layer security and LDAP<a class="headerlink" href="#transport-layer-security-and-ldap" title="Permanent link">¶</a></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>
@@ -211,7 +222,7 @@
**LDAPS** is considered as deprecated. You should always favor startTLS instead.
</DIV>
-<h2 id="server-configuration">Server configuration</h2>
+<h2 id="server-configuration">Server configuration<a class="headerlink" href="#server-configuration" title="Permanent link">¶</a></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>
<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.
@@ -219,18 +230,18 @@ In order to keep it simple for beginners
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>
+<h3 id="in-case-you-want-ads-to-generate-the-certificate">In case you want ADS to generate the certificate<a class="headerlink" href="#in-case-you-want-ads-to-generate-the-certificate" title="Permanent link">¶</a></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>
+<h3 id="in-case-you-want-to-use-an-external-keystore">In case you want to use an external keystore<a class="headerlink" href="#in-case-you-want-to-use-an-external-keystore" title="Permanent link">¶</a></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>
+<h4 id="key-creation">Key creation<a class="headerlink" href="#key-creation" title="Permanent link">¶</a></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>
<table>
<thead>
@@ -302,7 +313,7 @@ $
<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>
+<h4 id="configuring-apacheds-to-use-this-external-keystore">Configuring ApacheDS to use this external keystore<a class="headerlink" href="#configuring-apacheds-to-use-this-external-keystore" title="Permanent link">¶</a></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. Then you just have to setup the configuration using <em>Apache Directory Studio</em>, feeling the required input boxes, as shown on the following picture :</p>
<p><img alt="Keystore Configuration" src="images/keystore-configuration.png" /></p>
<p>The following properties were used :</p>
@@ -338,14 +349,14 @@ $
</tbody>
</table>
<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>
+<h2 id="verification-clients">Verification, Clients<a class="headerlink" href="#verification-clients" title="Permanent link">¶</a></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>
+<h3 id="using-apache-directory-studio-to-connect">Using Apache Directory Studio to connect<a class="headerlink" href="#using-apache-directory-studio-to-connect" title="Permanent link">¶</a></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>
+<h3 id="other-clients-java-programs-using-jndi">Other clients, Java programs using JNDI<a class="headerlink" href="#other-clients-java-programs-using-jndi" title="Permanent link">¶</a></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. </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="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>
@@ -441,7 +452,7 @@ $
<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>
+<h4 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">¶</a></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="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>
@@ -473,7 +484,7 @@ $
<p>You should be able to determine any SSL-related configuration problem with the help of this log.</p>
-<h2 id="resources">Resources</h2>
+<h2 id="resources">Resources<a class="headerlink" href="#resources" title="Permanent link">¶</a></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>
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/4-integrating-apacheds.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/4-integrating-apacheds.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/4-integrating-apacheds.html Sun Jul 5 22:34:35 2015
@@ -169,9 +169,20 @@
</div>
-<h1 id="4-integrating-apacheds-with-other-programs">4 - Integrating ApacheDS with other programs</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="4-integrating-apacheds-with-other-programs">4 - Integrating ApacheDS with other programs<a class="headerlink" href="#4-integrating-apacheds-with-other-programs" title="Permanent link">¶</a></h1>
<p>In this chapter, we expose various environments that are depending on <em>Apache Directory Server</em>, and how to set those environments. As <em>Apache Directory Server</em> is an <strong>LDAP</strong> server, it can be used to manage messaging users, web servers like <strong>Tomcat</strong>, users in a <strong>Unix</strong> environment, etc.</p>
-<h2 id="table-of-content">Table of content</h2>
+<h2 id="table-of-content">Table of content<a class="headerlink" href="#table-of-content" title="Permanent link">¶</a></h2>
<ul>
<li><a href="4.1-mozilla-thunderbird.html">4.1 - Mozilla Thunderbird Integration</a></li>
</ul>
Modified: websites/staging/directory/trunk/content/apacheds/basic-ug/4.1-mozilla-thunderbird.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-ug/4.1-mozilla-thunderbird.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-ug/4.1-mozilla-thunderbird.html Sun Jul 5 22:34:35 2015
@@ -169,7 +169,18 @@
</div>
-<h1 id="41-mozilla-thunderbird-integration">4.1 - Mozilla Thunderbird Integration</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="41-mozilla-thunderbird-integration">4.1 - Mozilla Thunderbird Integration<a class="headerlink" href="#41-mozilla-thunderbird-integration" title="Permanent link">¶</a></h1>
<p>In this section you will learn how to integrate Apache Directory Server into a mail client in order to use the data as an address book. Mozilla Thunderbird is used as an example.</p>
<div class="toc">
<ul>
@@ -191,32 +202,32 @@
</li>
</ul>
</div>
-<h2 id="e-mail-clients-and-mozilla-thunderbird">E-Mail clients and Mozilla Thunderbird</h2>
+<h2 id="e-mail-clients-and-mozilla-thunderbird">E-Mail clients and Mozilla Thunderbird<a class="headerlink" href="#e-mail-clients-and-mozilla-thunderbird" title="Permanent link">¶</a></h2>
<p>Integrating an LDAP server in an E-Mail client is a very traditionally task, because directories are commonly used as user repositories within companies and organizations. Contact data is stored for all users of the enterprise, and it is quite common to build the companies online phone/address book on this directory. These address books are often web based application within the intranet. But many E-Mail clients allow to connect to an LDAP based directory directly and use its data as an address book. This seamless integration provides better user experience. One of these clients is Mozilla Thunderbird. Other E-Mail clients that support LDAP integration for address books include <a href="http://www.microsoft.com/windows/oe/">Microsoft Outlook Expess</a>, <a href="http://www.eudora.com/">Eudora Email</a> and <a href="http://www.ibm.com/software/lotus/">IBM Lotus Notes</a>.</p>
<p>Technically, a mail program acts as a normal LDAP client, as described in earlier sections (i.e. the client connects to the server and performs LDAP search operations). Therefore the parameters you have to specify are the same. Main difference between searches with E-Mail clients and searches with LDAP Browsers like Softerra or JXplorer is that most of the complexity of the LDAP search is hidden to the user. Hence these tools are easier to use, but less powerful.</p>
-<h3 id="mozilla-thunderbird">Mozilla Thunderbird</h3>
+<h3 id="mozilla-thunderbird">Mozilla Thunderbird<a class="headerlink" href="#mozilla-thunderbird" title="Permanent link">¶</a></h3>
<p>Mozilla Thunderbird is a popular open source E-Mail client which supports many platforms. Actually it is more than just an E-Mail client (e.g. a news client as well). Features include junk mail control and RSS reading. Learn more about this software at the projects Homepage: <a href="http://www.mozilla.org/products/thunderbird/">Mozilla Thunderbird</a>.</p>
<p>Within this lesson we use Thunderbird primarily because of its broad support for different operation systems and hardware platforms (and because it allows the integration of LDAP servers as address books, of course). You may use other E-Mail clients as well. It is likely that that allow the integration of LDAP directories as well, and even that the configuration is similar to Thunderbird. Check your product documentation for details.</p>
-<h2 id="prerequisites">Prerequisites</h2>
+<h2 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites" title="Permanent link">¶</a></h2>
<p>We assume that you have Mozilla Thunderbird installed on your system (or you use another E-Mail client and are willing to assimilate the instructions to your situation). You may wish to download the software at the homepage (<a href="http://www.mozilla.org/products/thunderbird/">Mozilla Thunderbird</a>) and install it, before proceed with this lesson.
Furthermore you need an LDAP server up and running, which address data should be used as an address book within your E-Mail client. For the instructions it is assumed that you have installed Apache Directory Server as described in the first trail and loaded our sample data. To sum it up the following is assumed for the environment:
<em> Apache Directory runs on host </em>zanzibar<em>. LDAP and listens to port </em>10389<em>
</em> Anonymous access to the directory is allowed
<em> Data is imported as described in section 2, Base DN is </em>o=sevenSeas*</p>
<p>You may use this lesson as a blueprint to integrate other directory servers as well. At least you need the data given above in <em>bold</em>.</p>
-<h2 id="define-apache-directory-server-as-an-address-book">Define Apache Directory Server as an address book</h2>
-<h3 id="open-the-address-book">Open the address book</h3>
+<h2 id="define-apache-directory-server-as-an-address-book">Define Apache Directory Server as an address book<a class="headerlink" href="#define-apache-directory-server-as-an-address-book" title="Permanent link">¶</a></h2>
+<h3 id="open-the-address-book">Open the address book<a class="headerlink" href="#open-the-address-book" title="Permanent link">¶</a></h3>
<p>After starting Mozilla Thunderbird on your workstation, go to the address book by
<em> clicking the adress book icon or
</em> activation of the corresponding menu item ("Tools" -- "Address Book") or
* pressing Ctrl+2</p>
<p><img alt="Thunderbirs open addressbook" src="images/thunderbird-open-adressbook.png" /></p>
-<h3 id="define-a-new-ldap-directory">Define a new LDAP directory</h3>
+<h3 id="define-a-new-ldap-directory">Define a new LDAP directory<a class="headerlink" href="#define-a-new-ldap-directory" title="Permanent link">¶</a></h3>
<p>Within the adress book window open the dialog to define a new LDAP directory by
* activation of the corresponding menu item ("File" -- "New" -- "LDAP Directory...")</p>
<p><img alt="thunderbird new ldap directory" src="images/thunderbird-new-ldap-directory-menu.png" /></p>
<p>Thunderbird opens a dialog with three tabbed panes to provide the data of the directory.</p>
-<h3 id="provide-connection-data">Provide connection data</h3>
+<h3 id="provide-connection-data">Provide connection data<a class="headerlink" href="#provide-connection-data" title="Permanent link">¶</a></h3>
<p>Within the "General" tab, enter basic connection data to your directory:
<em> Name: A name which is used by Thunderbird within the UI, e.g. "Seven Seas"
</em> Hostname: the hostname or IP address of the server, "zanzibar" in our case
@@ -227,9 +238,9 @@ Furthermore you need an LDAP server up a
<p>The advance tab of the dialog provides input fields for result set limits, search scope and search filter. In our example we perform a search with subtree scope and a maximum number of 100 entries within the result set. The search filter restricts the results to person entries only.</p>
<p><img alt="Thunderbird new ldap" src="images/thunderbird-new-ldap-2.png" /></p>
<p>You probably have noticed that the input fields in the two tabbed panes corresponds exactly to the parameters for an LDAP search operation as described in lesson [Search the directory] of this trail.</p>
-<h2 id="searching-your-new-address-book">Searching your new address book</h2>
+<h2 id="searching-your-new-address-book">Searching your new address book<a class="headerlink" href="#searching-your-new-address-book" title="Permanent link">¶</a></h2>
<p><img alt="Thunderbird new ldap" src="images/thunderbird-adressbook.png" /></p>
-<h2 id="resources">Resources</h2>
+<h2 id="resources">Resources<a class="headerlink" href="#resources" title="Permanent link">¶</a></h2>
<ul>
<li><a href="http://opensourcearticles.com/articles/introduction_to_thunderbird">An introduction to Thunderbird</a>, Open Source Articles</li>
<li><a href="http://www.mozilla.org/projects/thunderbird/specs/ldap.html">LDAP Attribute Mapping</a> for Mozilla Thunderbird</li>
Modified: websites/staging/directory/trunk/content/apacheds/basic-user-guide.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/basic-user-guide.html (original)
+++ websites/staging/directory/trunk/content/apacheds/basic-user-guide.html Sun Jul 5 22:34:35 2015
@@ -150,12 +150,23 @@
-<h1 id="apacheds-v20-basic-users-guide">ApacheDS v2.0 Basic User's Guide</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="apacheds-v20-basic-users-guide">ApacheDS v2.0 Basic User's Guide<a class="headerlink" href="#apacheds-v20-basic-users-guide" title="Permanent link">¶</a></h1>
<p>This guide is primarily for people new to ApacheDS 2.0. If you plan to use the server as is, maybe even for your first LDAP experience, you'll (hopefully) find all information necessary to do so. Only basic configuration tasks are covered. Learn more about the options you have (and many other things) in the <a href="advanced-user-guide.html">ApacheDS v2.0 Advanced User's Guide</a>.</p>
<p><strong>LDAP</strong> is a complex set of technology, <em>Apache Directory Server</em> is offering more than just <strong>LDAP</strong>, so it's good to get a quick grip on the server.</p>
-<h2 id="about-this-guide">About this guide</h2>
+<h2 id="about-this-guide">About this guide<a class="headerlink" href="#about-this-guide" title="Permanent link">¶</a></h2>
<p>Getting started. Learn how to download and install ApacheDS 2.0 on different platforms, connect to it with various clients (graphical tools among others), manipulate the data within your directory and integrate ApacheDS with other software. The same sample data, provided as a download, is used through the whole guide.</p>
-<h2 id="table-of-contents">Table of contents</h2>
+<h2 id="table-of-contents">Table of contents<a class="headerlink" href="#table-of-contents" title="Permanent link">¶</a></h2>
<ul>
<li><a href="basic-ug/1-how-to-begin.html">1 - How to begin</a><ul>
<li><a href="basic-ug/1.1-what-apacheds-is.html">1.1 - What Apache Directory Server is</a></li>
@@ -200,7 +211,7 @@
</ul>
</li>
</ul>
-<h3 id="feedback-welcome">Feedback welcome!</h3>
+<h3 id="feedback-welcome">Feedback welcome!<a class="headerlink" href="#feedback-welcome" title="Permanent link">¶</a></h3>
<p>We are quite interested to improve the content of this guide. Feel free to provide us feedback:</p>
<p><img alt="email" src="../images/email.png" /> <a href="mailto:users@directory.apache.org">mailto:users@directory.apache.org</a> </p>
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 Sun Jul 5 22:34:35 2015
@@ -150,14 +150,25 @@
-<h1 id="coding-standards">Coding Standards</h1>
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="coding-standards">Coding Standards<a class="headerlink" href="#coding-standards" title="Permanent link">¶</a></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><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></p>
<p><strong>IDEA IDE</strong></p>
<p>IDEA users can import <a href="settings.jar">this file</a> to enfore the code formating.</p>
-<h2 id="headers">Headers</h2>
+<h2 id="headers">Headers<a class="headerlink" href="#headers" title="Permanent link">¶</a></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>
<span class="cm"> * Licensed to the Apache Software Foundation (ASF) under one</span>
@@ -181,13 +192,11 @@
</pre></div>
-<h3 id="classinterface-headers">Class/Interface headers</h3>
+<h3 id="classinterface-headers">Class/Interface headers<a class="headerlink" href="#classinterface-headers" title="Permanent link">¶</a></h3>
<p>Each <strong>Class</strong> or <em>Interface</em> should have an header which must contains :</p>
<ul>
<li>A descrption of this class/interface</li>
-<li>
-<p>an <em>author</em> tag which should be :</p>
-<div class="codehilite"><pre><span class="nd">@author</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s">"mailto:dev@directory.apache.org"</span><span class="o">></span><span class="n">Apache</span> <span class="n">Directory</span> <span class="n">Project</span><span class="o"></</span><span class="n">a</span><span class="o">></span>
+<li>an <em>author</em> tag which should be :<div class="codehilite"><pre><span class="nd">@author</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s">"mailto:dev@directory.apache.org"</span><span class="o">></span><span class="n">Apache</span> <span class="n">Directory</span> <span class="n">Project</span><span class="o"></</span><span class="n">a</span><span class="o">></span>
</pre></div>
@@ -198,12 +207,12 @@ Thanks to avoid to put your name. The co
</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>
+<h3 id="static-members-and-other-members">Static members and other members<a class="headerlink" href="#static-members-and-other-members" title="Permanent link">¶</a></h3>
<p>Just add a single line javadoc comment like : <em>/*<em> blah ... </em>/</em> before each member</p>
-<h3 id="methods">Methods</h3>
+<h3 id="methods">Methods<a class="headerlink" href="#methods" title="Permanent link">¶</a></h3>
<p>Follow the standard <strong>javadoc</strong> rules : Description, <strong>@param</strong>, <strong>@exception</strong> and <strong>@return</strong>. It should be enough. Avoid <strong>@tags</strong>, <strong>@todo</strong> tags, etc...</p>
<p>Escape <strong>html</strong> characters</p>
-<h2 id="comments">Comments</h2>
+<h2 id="comments">Comments<a class="headerlink" href="#comments" title="Permanent link">¶</a></h2>
<p>No special rules, except that you should avoid :</p>
<ul>
<li>Useless comments like : i++; /* Increment i */</li>
@@ -212,7 +221,7 @@ Thanks to avoid to put your name. The co
<li>Dead code commented. If it's dead, then put it in a cuffin. We use SVN, the Ressuscitator !</li>
</ul>
<p>Basically, use your common sense :-)</p>
-<h2 id="naming">Naming</h2>
+<h2 id="naming">Naming<a class="headerlink" href="#naming" title="Permanent link">¶</a></h2>
<p>Naming ! Sounds like Blaming :-). Ok. We use <strong>Sun(tm/c/r)</strong> style :</p>
<ul>
<li>Constants are in UPPER CASE with accepted '_'</li>
@@ -226,13 +235,13 @@ Thanks to avoid to put your name. The co
</ul>
<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>
+<h2 id="spaces-vs-tabs">Spaces vs tabs<a class="headerlink" href="#spaces-vs-tabs" title="Permanent link">¶</a></h2>
<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>
+<h2 id="formatting">Formatting<a class="headerlink" href="#formatting" title="Permanent link">¶</a></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>
@@ -263,9 +272,9 @@ Thanks to avoid to put your name. The co
</pre></div>
-<h2 id="imports">Imports</h2>
+<h2 id="imports">Imports<a class="headerlink" href="#imports" title="Permanent link">¶</a></h2>
<p>Always declare all the classes you import, do not use <strong>x.y.*</strong></p>
-<h2 id="what-else">What else ?</h2>
+<h2 id="what-else">What else ?<a class="headerlink" href="#what-else" title="Permanent link">¶</a></h2>
<p>Well, this was a very short introduction about coding rules. Use commen sense, look at what you see around you when adding some code, ask people about format, if you have a question.</p>
<p>That's it ! (I wait your comments, guys :-)</p>