Section for admin guide on DIGEST-MD5

[Andrew Findlay <andrew.findlay@skills-1st.co.uk>]

I append a suggested section for sasl.sdf in the OpenLDAP 2.1 admin guide.
I would suggest moving the sections on mapping IDs up above the mechanism
sections, as they are useful for all mechanisms and it might be easier to
read in that order.

I have not been able to test the markup used here, as the site holding
the SDF tools seems to be down.

Andrew
-- 
-----------------------------------------------------------------------
|                 From Andrew Findlay, Skills 1st Ltd                 |
| Consultant in large-scale systems, networks, and directory services |
|        Andrew.Findlay@skills-1st.co.uk       +44 1628 782565        |
-----------------------------------------------------------------------


H3: DIGEST-MD5

This section describes the use of the SASL DIGEST-MD5 mechanism using
secrets stored either in the directory itself or in sasldb2.  DIGEST-MD5
relies on the client and the server sharing a "secret", usually a
password. The server generates a challenge and the client a response
proving that it knows the shared secret. This is much more secure than
simply sending the secret over the wire.

Cyrus SASL supports several shared-secret mechanisms. To do this, it needs
access to the plaintext password (unlike mechanisms which pass plaintext
passwords over the wire, where the server can store a hashed version of
the password). The secret passwords can either be stored in Cyrus SASL's
own database or (if OpenLDAP has been compiled with Cyrus SASL 2.1)
in the LDAP directory itself. In either case it is very
important to apply file access controls and LDAP access controls to
prevent exposure of the passwords.

To use secrets stored in {{sasldb2,}} simply add users with the
{{saslpasswd2}} command:

>	saslpasswd2 -c <username>

The passwords for such users must be managed with the {{saslpasswd2}} command.

To use secrets stored in the LDAP directory, place plaintext passwords
in the {{EX:userPassword}} attribute. It will be necessary to add an option
to {{EX:slapd.conf}} to make sure that passwords changed through LDAP
are stored in plaintext:

>	password-hash   {CLEARTEXT}

Passwords stored in this way can be managed either with {{EX:ldappasswd}}
or by simply modifying the {{EX:userPassword}} attribute.

Wherever the passwords are stored, a mapping will be needed from SASL
IDs to DNs. This can be done with a {{EX:slapd.conf}} entry of the form:

>	saslRegexp
>		uid=(.*),cn=digest-md5,cn=auth
>		ldap:///dc=example,dc=com??sub?uid=$1

(Note that DIGEST-MD5 does not need a realm.)

Now, users can specify SASL IDs when performing LDAP operations, and the
password stored in {{sasldb2}} or in the directory itself will be used
to verify the authentication. A suitable directory entry would be:

>	dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
>	objectclass: inetOrgPerson
>	objectclass: person
>	sn: Findlay
>	uid: u000997
>	userPassword: secret

and a command using the entry:

>	ldapsearch -U u000997 -b dc=example,dc=org 'cn=andrew*'