include Luke Howard of PADL.COM ldap hdb documentation

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@13545 ec53bebd-3082-4978-b11e-865c3cabbd6b

doc/setup.texi

@@ -699,7 +699,99 @@ _kerberos.srv		TXT     "EXAMPLE.COM"
 @section Using LDAP to store the database
 @cindex Using the LDAP backend
 
-See @url{http://www.padl.com/Research/Heimdal.html} for more information.
+This document describes how to install the LDAP backend for
+Heimdal. Note that, before attempting to configure such an
+installation, you should be aware of the implications of storing
+private information (such as users' keys) in a directory service
+primarily designed for public information. Nonetheless, with a
+suitable authorization policy, it is possible to set this up in a
+secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to
+install this backend. The HDB schema was devised by Leif Johansson.
+
+Requirements
+
+@itemize @bullet
+
+@item
+A current release of Heimdal, configured with
+@code{--with-openldap=/usr/local} (adjust according to where you have
+installed OpenLDAP).
+
+@item
+OpenLDAP 2.0.x. Configure OpenLDAP with --enable-local to enable the
+local transport. (A patch to support SASL EXTERNAL authentication is
+necessary in order to use OpenLDAP 2.1.x.)
+
+@item
+The KDC LDAP schema, which is distributed with OpenLDAP
+@end itemize
+
+Configure the LDAP server ACLs to accept writes from clients over the
+local transport. For example:
+
+@example
+access to *
+        by sockurl="^ldapi:///$" write
+@end example
+
+Make sure you include the schema:
+
+@example
+include /usr/local/etc/openldap/schema/krb5-kdc.schema
+@end example
+
+
+Start the slapd with the local listener (as well as the default TCP/IP
+listener on port 389) as follows:
+
+@example
+    slapd -h "ldapi:/// ldap:///"
+@end example
+
+Note: These is a bug in slapd where it appears to corrupt the krb5Key
+binary attribute on shutdown. This may be related to our use of the V3
+schema definition syntax instead of the old UMich-style, V2 syntax.
+
+You should specify a the distinguished name under which your
+principals will be stored in @file{krb5.conf}:
+
+@example
+[kdc]
+        database = @{
+                dbname = ldap:ou=KerberosPrincpals,dc=padl,dc=com
+                mkey_file = /path/to/mkey
+        @}
+@end example
+
+Once you have built Heimdal and started the LDAP server, run kadmin
+(as usual) to initialize the database. Note that the instructions for
+stashing a master key are as per any Heimdal installation; you are
+encouraged to read the Heimdal documentation for further information.
+
+@example
+kdc# kadmin -l
+kadmin> init PADL.COM
+Realm max ticket life [unlimited]:
+Realm max renewable ticket life [unlimited]:
+kadmin> ank lukeh
+Max ticket life [1 day]:
+Max renewable life [1 week]:
+Principal expiration time [never]:
+Password expiration time [never]:
+Attributes []:
+lukeh@@PADL.COM's Password:
+Verifying password - lukeh@@PADL.COM's Password:
+kadmin> exit
+@end example
+
+Verify that the principal database has indeed been stored at the
+directory with the following command:
+
+@example
+kdc# ldapsearch -L -h localhost -D cn=manager \
+ -w secret -b ou=KerberosPrincipals,dc=padl,dc=com \
+ 'objectclass=krb5KDCEntry' 
+@end example
 
 @node Using Samba LDAP password database, , Using LDAP to store the database, Setting up a realm
 @section Using Samba LDAP password database