Internet DRAFT - draft-wahl-ldap-digest-example


Network Working Group                            A. Coulbeck and M. Wahl
INTERNET-DRAFT                              Innosoft International, Inc.
Expires in                                                     June 2000

     An Example of DIGEST-MD5 Authentication within an LDAP server

1. Status of this Memo

   This document is an Internet-Draft and is in full conformance
   with all provisions of Section 10 of RFC2026 except that the 
   right to produce derivative works is not granted.

   Internet-Drafts are working documents of the Internet Engineering 
   Task Force (IETF), its areas, and its working groups.  Note that 
   other groups may also distribute working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six 
   months and may be updated, replaced, or obsoleted by other 
   documents at any time.  It is inappropriate to use Internet-Drafts 
   as reference material or to cite them other than as "work in 

     The list of current Internet-Drafts can be accessed at

     The list of Internet-Draft Shadow Directories can be accessed at

   To view the entire list of current Internet-Drafts, please check
   the "1id-abstracts.txt" listing contained in the Internet-Drafts
   Shadow Directories on (Africa),
   (Northern Europe), (Southern Europe),
   (Pacific Rim), (US East Coast), or
   (US West Coast).

2. Abstract

HTTP Digest Authentication as a SASL mechanism [DIGEST-MD5] is
required to be supported in LDAP servers for password-based
authentication (see Authentication Methods for LDAP [AUTHMETH]).
This specification describes one approach to implement DIGEST-MD5
authentication in an LDAP server.  It does not specify a standard 
of any kind.

3. Representation of the DIGEST-MD5 hash in an LDAP attribute

Let { a, b, ... } be the concatenation of the strings a, b, ...

Let H(s) be the 16 octet MD5 hash of the string s, as specified in

Let base64(s) be the base64 ASCII encoding of the binary string s, as
specified in [RFC 1521].

Then, the LDAP attribute value of the DIGEST-MD5 hash, which we call
hd-value, is specified as:

Coulbeck, Wahl          INTERNET DRAFT                        [Page 1]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

    hd-value = { "{HD}", base64(hash-a1) }
    hash-a1 = H( { username-value, ":", realm-value, ":", passwd } )

    This is the value used within the calculation of A1 as specified
    in [DIGEST-MD5].

4. Binding using this attribute 

Users are authenticated with the LDAP Bind operation. The user MUST be 
represented by an entry in the DIT. For DIGEST-MD5 authentication, each 
entry representing a user MUST contain a hd-value in its userpassword 

The procedures described in [RFC 2251] and [AUTHMETH] are followed by
the server. 

5. Contents of the hash-a1 value

The username-value, realm-value and passwd are specified as follows:

    username-value       = "dn" ":" normalized-dn
    realm-value          = service-name "@" host

    The plaintext password in UTF-8.

    This is currently restricted to an entry in the server's database,
    where the entry contains a hd-value in the userpassword

    This is a value of distinguishedName as specified in [RFC 2253] in
    which all attributeType names and all attributeValues of
    DirectoryString syntax have been upper-cased, and all
    insignificant spaces have been removed.

    The name of the server, for example a product name.

    The fully-qualified canonical DNS host name of the server.

6. Example

Suppose there is a user represented by the entry cn=James Smith,
dc=austin, dc=innosoft, dc=com and whose plaintext password is
"secret". The hd-value is calculated as follows for a server named
"idds" located on the host

Coulbeck, Wahl          INTERNET DRAFT                        [Page 2]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

    realm-value    = ""
    passwd         = "secret"

    hd-value       = "{HD}HGV7gjTumJR5WisCano8Vw=="

For the server to authenticate this user using DIGEST-MD5, the
entry cn=James Smith, dc=austin, dc=innosoft, dc=com must contain the
following attribute:

    userpassword: {HD}HGV7gjTumJR5WisCano8Vw==

A successful LDAP SASL Bind exchange between the client and server is
given below. BER values are written as strings where possible,
otherwise as hexadecimal. Line breaks and annotations (in parentheses)
have been added for clarity.

30 18 (LDAPMessage)
   02 01 (messageID)
   60 13 (bindRequest)
      02 01 (version)
      04 00 (name)
      a3 0c (sasl)
         04 0a (mechanism)

30 6b (LDAPMessage)
   02 01 (messageID)
   61 66 (bindResponse)
      0a 01 (resultCode)
         0e (saslBindInProgress)
      04 00 (matchedDN)
      04 08 (errorMessage)
      87 55 (serverSaslCreds)

30 82 01 2f (LDAPMessage)
   02 01 (messageID)
   60 82 01 28 (bindRequest)
      02 01 (version)

Coulbeck, Wahl          INTERNET DRAFT                        [Page 3]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

      04 2e (name)
         cn=James Smith, dc=austin, dc=innosoft, dc=com
      a3 81 f2 (sasl)
         04 0a (mechanism)
         04 81 e3 (credentials)
            username="dn:CN=JAMES SMITH,DC=AUSTIN,DC=INNOSOFT,DC=COM",

30 0c (LDAPMessage)
   02 01 (messageID)
   61 07 (bindResponse)
      0a 01 (resultCode)
         00 (success)
      04 00 (matchedDN)
      04 00 (errorMessage)

The client has been authenticated as cn=James Smith, dc=austin,
dc=innosoft, dc=com. The client computed the correct response to the
server challenge thus proving that the client knows the value of the
password. The plaintext password never appeared in the protocol
exchange. The unique "nonce" value sent in the server challenge
ensures that any replay of the client response by an eavesdropper will
not succeed.

7. Security Considerations


The hash of username, realm and password is stored in the server
database in the userpassword attribute. Access to the hash values
gives an attacker immediate access to the server realm, therefore the
database and the userpassword attribute must be protected as if they
contained plaintext passwords.

8. Addition to LDAP SDK API

This function can be used by clients to compute a DIGEST-MD5 response
to a server challenge:

    char *ldap_digest_md5_encode(
        const char *challenge, 
        const char *username,
        const char *passwd

Coulbeck, Wahl          INTERNET DRAFT                        [Page 4]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

    Server challenge string as returned in server credentials.

    UTF-8 encoded username.

    UTF-8 encoded plaintext password.

The ldap_digest_md5_encode() function allocates and returns a response
string. The caller must free this string after use.

The following client code segment illustrates the use of

    int retval, msgid, ldap_version = LDAP_VERSION3;
    LDAP *ld;
    LDAPControl **controls = NULL;
    struct berval ccred, *servercredp = NULL;
    char *name, *username, *normdn, *pass, *resp;

    ld = ldap_init("", 389);
    if (ld == NULL) return -1;

    name = "cn=James Smith, dc=austin, dc=innosoft, dc=com";
    pass = "secret";

    /* get the server challenge */
    retval = ldap_sasl_bind_s(ld, "", "DIGEST-MD5", NULL, 
                              controls, NULL, &servercredp);
    if (retval != LDAP_SUCCESS) return -1;
    if (servercredp == NULL) return -1;

    /* construct a username from the bind DN */
    normdn = dn_normalize_case(name);
    if (normdn == NULL) return -1;

    username = malloc(strlen(normdn)+sizeof("dn:")+1);
    if (username == NULL) {
        return -1;
    sprintf(username, "dn:%s", normdn);

    /* compute a response */
    resp = ldap_digest_md5_encode(servercredp->bv_val, username, pass);

Coulbeck, Wahl          INTERNET DRAFT                        [Page 5]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

    ccred.bv_val = resp;
    ccred.bv_len = strlen(ccred.bv_val);

    /* send the response */
    retval = ldap_sasl_bind(ld, name, "DIGEST-MD5", &ccred, 
                            controls, NULL, &msgid);
    if (retval != LDAP_SUCCESS) return -1;

9. References

[DIGEST-MD5] P. J. Leach, C. Newman, "Digest Authentication as a SASL
  Mechanism", draft-leach-digest-sasl-03.txt, April 1999

[AUTHMETH] M. Wahl, H. Alvestrand, J. Hodges, RL Morgan,
  "Authentication Methods for LDAP",
  draft-ietf-ldapext-authmeth-04.txt, June 1999

[RFC 2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
  Protocol (v3)", December 1997

[RFC 1321] R. Rivest, "The MD5 Message-Digest Algorithm", April 1992

[RFC 1521] N. Borenstein, N. Freed, "Multipurpose Internet Mail
  Extensions (MIME) Part One: Format of Internet Message Bodies",
  November 1996

[RFC 2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
  Protocol (v3): UTF-8 String Representation of Distinguished Names",
  December 1997

10. Authors Address

    Andy Coulbeck (document author)
    Innosoft International, Inc.
    8911 Capital of Texas Hwy, Suite 4140
    Austin, TX 78759 

    Mark Wahl (Internet Draft editor)
    Innosoft International, Inc.
    8911 Capital of Texas Hwy, Suite 4140
    Austin, TX 78759 
    Phone: +1 512 231 1600

Coulbeck, Wahl          INTERNET DRAFT                        [Page 6]
                draft-wahl-ldap-digest-example-00.txt   Exp. June 2000

Full Copyright Statement

   Copyright (c) 1999 Innosoft International, Inc. 

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to Innosoft International, Inc. 
   or other organizations. 

   This document and the information contained herein is provided on an
   "AS IS" basis.

Expires: June 2000

Coulbeck, Wahl          INTERNET DRAFT                        [Page 7]