Re: Section for admin guide on DIGEST-MD5

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

On Fri, Jul 12, 2002 at 10:53:42AM -0700, Howard Chu wrote:
> 
> Note that OpenLDAP 2.1 still supports Cyrus SASL 1.5, and this information
> is not quite applicable to Cyrus 1.5.
> 
> Also, DIGEST-MD5 does use realms. However, when a username is used in the
> "default"
> realm, the realm name is not returned from the SASL library.

OK - I had only covered the simple case. I have generalised that
section a bit and added caveats on Cyrus SASL versions. Not sure
whether I have adequately covered the differences though.

New version appended.

> This is documented in the SASL docs. You are expected to have read the SASL
> docs
> and know how SASL works before you attempt to use it with OpenLDAP.

Indeed, but much of the Cyrus SASL doc is aimed at software developers
rather than system admins so it can be hard to find some of these
details. In any case, I cannot find the bit that talks about not
returning the default realm.

While testing the effect of realms, I came across a problem in regex
processing, which is now documented in ITS#1951: this would prevent
the use of a regex of the form:

	cn=[^,]*,cn=digest-md5,cn=auth

where the intention is to assign everything up to the first comma to a
UID search. The example from the existing admin guide uses a regex:

	uid=(.*),.*cn=auth

which risks assigning more than just the uid to the search. Debugging
such an error is hard, as the necessary information does not appear in
the logs unless trace logging is on.


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.

The configuration and commands discussed in this section assume the
use of Cyrus SASL 2.1. If you are using version 1.5 then certain features
will not be available, and the commands do not have the trailing `2'.

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. If you are running a single machine using the default realm,
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

If other realms are in use, you will need two or more entries
due to the fact that the Cyrus SASL libraries remove the realm from the
ID string entirely if it matches the default realm. In the example below,
the first {{saslRegexp}} matches IDs using the realm {{myrealm}} while
the second one matches IDs using the default realm:

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

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*'

This example specifies a realm explicitly:

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