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 progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (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 [RFC1321]. 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 } ) hash-a1 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 attribute. 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 passwd The plaintext password in UTF-8. username-value This is currently restricted to an entry in the server's database, where the entry contains a hd-value in the userpassword attribute. normalized-dn 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. service-name The name of the server, for example a product name. host 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 brio.austin.innosoft.com: Coulbeck, Wahl INTERNET DRAFT [Page 2] draft-wahl-ldap-digest-example-00.txt Exp. June 2000 username-value = "dn:CN=JAMES SMITH,DC=AUSTIN,DC=INNOSOFT,DC=COM" realm-value = "idds@brio.austin.innosoft.com" 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. [Client] 30 18 (LDAPMessage) 02 01 (messageID) 01 60 13 (bindRequest) 02 01 (version) 03 04 00 (name) a3 0c (sasl) 04 0a (mechanism) DIGEST-MD5 [Server] 30 6b (LDAPMessage) 02 01 (messageID) 01 61 66 (bindResponse) 0a 01 (resultCode) 0e (saslBindInProgress) 04 00 (matchedDN) 04 08 (errorMessage) continue 87 55 (serverSaslCreds) realm="idds@brio.austin.innosoft.com", nonce="N8SAX3jAE/6bqt",qop="auth",charset=utf-8 [Client] 30 82 01 2f (LDAPMessage) 02 01 (messageID) 02 60 82 01 28 (bindRequest) 02 01 (version) 03 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) DIGEST-MD5 04 81 e3 (credentials) charset=utf-8, username="dn:CN=JAMES SMITH,DC=AUSTIN,DC=INNOSOFT,DC=COM", realm="idds@brio.austin.innosoft.com",nonce="N8SAX3jAE/6bqt", nc=00000001,cnonce="37c4805fac7d9b3c56a7", response="9a8cac7d0f582e57cbfd6c19d10ac329",qop=auth [Server] 30 0c (LDAPMessage) 02 01 (messageID) 02 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 See [DIGEST-MD5]. 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 challenge Server challenge string as returned in server credentials. username UTF-8 encoded username. passwd 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 ldap_digest_md5_encode(): 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("brio.austin.innosoft.com", 389); if (ld == NULL) return -1; ldap_set_option(ld,LDAP_OPT_PROTOCOL_VERSION,&ldap_version); 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) { free(normdn); return -1; } sprintf(username, "dn:%s", normdn); free(normdn); /* compute a response */ resp = ldap_digest_md5_encode(servercredp->bv_val, username, pass); free(username); 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); free(resp); 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 USA Mark Wahl (Internet Draft editor) Innosoft International, Inc. 8911 Capital of Texas Hwy, Suite 4140 Austin, TX 78759 USA Phone: +1 512 231 1600 EMail: Mark.Wahl@innosoft.com 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]