From: Kurt Zeilenga Date: Thu, 8 Jun 2000 20:38:36 +0000 (+0000) Subject: Replace AuthMeth, StartTLS, and DIGEST-MD5 I-Ds with RFC X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~2699 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=f6529c728f6d0d02b224a1108db6dbbeeb1e90ff;p=openldap Replace AuthMeth, StartTLS, and DIGEST-MD5 I-Ds with RFC --- diff --git a/doc/drafts/draft-ietf-ldapext-authmeth-xx.txt b/doc/drafts/draft-ietf-ldapext-authmeth-xx.txt deleted file mode 100644 index 62102e372b..0000000000 --- a/doc/drafts/draft-ietf-ldapext-authmeth-xx.txt +++ /dev/null @@ -1,784 +0,0 @@ - -Network Working Group M. Wahl -INTERNET-DRAFT Innosoft International, Inc. - H. Alvestrand - MaXware AS - J. Hodges - Stanford University - RL "Bob" Morgan - Stanford University -Expires in six months from June 21, 1999 - - - Authentication Methods for LDAP - - -1. Status of this Memo - - This document is an Internet-Draft. 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." - - 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 - - This document specifies particular combinations of security - mechanisms which are required and recommended in LDAP [1] - implementations. - -3. Introduction - - LDAP version 3 is a powerful access protocol for directories. - - It offers means of searching, fetching and manipulating directory - content, and ways to access a rich set of security functions. - - In order to function for the best of the Internet, it is vital - that these security functions be interoperable; therefore there - has to be a minimum subset of security functions that is common to - all implementations that claim LDAPv3 conformance. - - - -Wahl, Alvestrand, Hodges, Morgan Page 1 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - Basic threats to an LDAP directory service include: - - (1) Unauthorized access to data via data-fetching operations, - - (2) Unauthorized access to reusable client authentication - information by monitoring others' access, - - (3) Unauthorized access to data by monitoring others' access, - - (4) Unauthorized modification of data, - - (5) Unauthorized modification of configuration, - - (6) Unauthorized or excessive use of resources (denial of - service), and - - (7) Spoofing of directory: Tricking a client into believing - that information came from the directory when in fact it - did not, either by modifying data in transit or misdirecting - the client's connection. - - Threats (1), (4), (5) and (6) are due to hostile clients. Threats - (2), (3) and (7) are due to hostile agents on the path between client - and server, or posing as a server. - - The LDAP protocol suite can be protected with the following - security mechanisms: - - (1) Client authentication by means of the SASL [2] mechanism set, - possibly backed by the TLS credentials exchange mechanism, - - (2) Client authorization by means of access control based on - the requestor's authenticated identity, - - (3) Data integrity protection by means of the TLS protocol or - data-integrity SASL mechanisms, - - (4) Protection against snooping by means of the TLS protocol - or data-encrypting SASL mechanisms, - - (5) Resource limitation by means of administrative limits on - service controls, and - - (6) Server authentication by means of the TLS protocol or SASL - mechanism. - - At the moment, imposition of access controls is done by means - outside the scope of the LDAP protocol. - - In this document, the term "user" represents any application which - is an LDAP client using the directory to retrieve or store information. - -Wahl, Alvestrand, Hodges, Morgan Page 2 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in - this document are to be interpreted as described in RFC 2119 [3]. - -4. Example deployment scenarios - - The following scenarios are typical for LDAP directories on the - Internet, and have different security requirements. (In the - following, "sensitive" means data that will cause real damage to - the owner if revealed; there may be data that is protected but - not sensitive). This is not intended to be a comprehensive list, - other scenarios are possible, especially on physically protected - networks. - - (1) A read-only directory, containing no sensitive data, - accessible to "anyone", and TCP connection hijacking - or IP spoofing is not a problem. This directory requires - no security functions except administrative service limits. - - (2) A read-only directory containing no sensitive data; read - access is granted based on identity. TCP connection - hijacking is not currently a problem. This scenario requires - a secure authentication function. - - (3) A read-only directory containing no sensitive data; and - the client needs to ensure that the directory data is - authenticated by the server and not modified while being - returned from the server. - - (4) A read-write directory, containing no sensitive data; read - access is available to "anyone", update access to properly - authorized persons. TCP connection hijacking is not - currently a problem. This scenario requires a secure - authentication function. - - (5) A directory containing sensitive data. This scenario - requires session confidentiality protection AND secure - authentication. - -5. Authentication and Authorization: Definitions and Concepts - - This section defines basic terms, concepts, and interrelationships - regarding authentication, authorization, credentials, and identity. - These concepts are used in describing how various security - approaches are utilized in client authentication and authorization. - - - - - - - -Wahl, Alvestrand, Hodges, Morgan Page 3 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - -5.1. Access Control Policy - - An access control policy is a set of rules defining the protection - of resources, generally in terms of the capabilities of persons or - other entities accessing those resources. A common expression of an - access control policy is an access control list. Security objects - and mechanisms, such as those described here, enable the expression of - access control policies and their enforcement. Access control - policies are typically expressed in terms of access control attributes - as described below. - -5.2. Access Control Factors - - A request, when it is being processed by a server, may be associated - with a wide variety of security-related factors (section 4.2 of [1]). - The server uses these factors to determine whether and how to process - the request. These are called access control factors (ACFs). They - might include source IP address, encryption strength, the type of - operation being requested, time of day, etc. Some factors may be - specific to the request itself, others may be associated with the - connection via which the request is transmitted, others (e.g. time of - day) may be "environmental". - - Access control policies are expressed in terms of access control - factors. E.g., a request having ACFs i,j,k can perform operation Y - on resource Z. The set of ACFs that a server makes available for such - expressions is implementation-specific. - -5.3. Authentication, Credentials, Identity - - Authentication credentials are the evidence supplied by one party to - another, asserting the identity of the supplying party (e.g. a user) - who is attempting to establish an association with the other party - (typically a server). Authentication is the process of generating, - transmitting, and verifying these credentials and thus the identity - they assert. An authentication identity is the name presented in a - credential. - - There are many forms of authentication credentials -- the form used - depends upon the particular authentication mechanism negotiated by the - parties. For example: X.509 certificates, Kerberos tickets, simple - identity and password pairs. Note that an authentication mechanism may - constrain the form of authentication identities used with it. - -5.4. Authorization Identity - - An authorization identity is one kind of access control factor. It is - the name of the user or other entity that requests that operations be - performed. Access control policies are often expressed in terms of - authorization identities; e.g., entity X can perform operation Y on - resource Z. - -Wahl, Alvestrand, Hodges, Morgan Page 4 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - The authorization identity bound to an association is often exactly the - same as the authentication identity presented by the client, but it may - be different. SASL allows clients to specify an authorization identity - distinct from the authentication identity asserted by the client's - credentials. This permits agents such as proxy servers to authenticate - using their own credentials, yet request the access privileges of the - identity for which they are proxying [2]. Also, the form of - authentication identity supplied by a service like TLS may not - correspond to the authorization identities used to express a server's - access control policy, requiring a server-specific mapping to be done. - The method by which a server composes and validates an authorization - identity from the authentication credentials supplied by a client is - implementation-specific. - -6. Required security mechanisms - - It is clear that allowing any implementation, faced with the above - requirements, to pick and choose among the possible alternatives - is not a strategy that is likely to lead to interoperability. In - the absence of mandates, clients will be written that do not - support any security function supported by the server, or worse, - support only mechanisms like cleartext passwords that provide - clearly inadequate security. - - Active intermediary attacks are the most difficult for an attacker - to perform, and for an implementation to protect against. Methods - that protect only against hostile client and passive eavesdropping - attacks are useful in situations where the cost of protection - against active intermediary attacks is not justified based on the - perceived risk of active intermediary attacks. - - Given the presence of the Directory, there is a strong desire to - see mechanisms where identities take the form of a Distinguished - Name and authentication data can be stored in the directory; this - means that either this data is useless for faking authentication - (like the Unix "/etc/passwd" file format used to be), or its - content is never passed across the wire unprotected - that is, - it's either updated outside the protocol or it is only updated in - sessions well protected against snooping. It is also desirable - to allow authentication methods to carry authorization identities - based on existing forms of user identities for backwards compatibility - with non-LDAP-based authentication services. - - Therefore, the following implementation conformance requirements - are in place: - - (1) For a read-only, public directory, anonymous authentication, - described in section 7, can be used. - - - - -Wahl, Alvestrand, Hodges, Morgan Page 5 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - (2) Implementations providing password-based authenticated access - MUST support authentication using Digest, as described in - section 8.1. This provides client authentication with - protection against passive eavesdropping attacks, but does - not provide protection against active intermediary attacks. - - (3) For a directory needing session protection and - authentication, the Start TLS extended operation, and either - the simple authentication choice or the SASL EXTERNAL - mechanism, are to be used together. Implementations SHOULD - support authentication with a password as described in - section 8.2, and SHOULD support authentication with a - certificate as described in section 9.1. Together, these - can provide integrity and disclosure protection of - transmitted data, and authentication of client and server, - including protection against active intermediary attacks. - - If TLS is negotated, the client MUST discard all information about - the server fetched prior to the TLS negotiation. In particular, the - value of supportedSASLMechanisms MAY be different after TLS has been - negotiated (specifically, the EXTERNAL mechanism or the proposed - PLAIN mechanism are likely to only be listed after a TLS negotiation - has been performed). - - If a SASL security layer is negotiated, the client MUST discard all - information about the server fetched prior to SASL. In particular, if - the client is configured to support multiple SASL mechanisms, it SHOULD - fetch supportedSASLMechanisms both before and after the SASL security - layer is negotiated and verify that the value has not changed after the - SASL security layer was negotiated. This detects active attacks which - remove supported SASL mechanisms from the supportedSASLMechanisms list. - -7. Anonymous authentication - - Directory operations which modify entries or access protected - attributes or entries generally require client authentication. - Clients which do not intend to perform any of these operations - typically use anonymous authentication. - - LDAP implementations MUST support anonymous authentication, as - defined in section 7.1. - - LDAP implementations MAY support anonymous authentication with TLS, - as defined in section 7.2. - - While there MAY be access control restrictions to prevent access to - directory entries, an LDAP server SHOULD allow an anonymously-bound - client to retrieve the supportedSASLMechanisms attribute of the root - DSE. - - - -Wahl, Alvestrand, Hodges, Morgan Page 6 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - An LDAP server MAY use other information about the client provided - by the lower layers or external means to grant or deny access even - to anonymously authenticated clients. - -7.1. Anonymous authentication procedure - - An LDAP client which has not successfully completed a bind operation - on a connection is anonymously authenticated. - - An LDAP client MAY also specify anonymous authentication in a bind - request by using a zero-length OCTET STRING with the simple - authentication choice. - -7.2. Anonymous authentication and TLS - - An LDAP client MAY use the Start TLS operation [5] to negotiate the - use of TLS security [6]. If the client has not bound beforehand, - then until the client uses the EXTERNAL SASL mechanism to negotiate - the recognition of the client's certificate, the client is - anonymously authenticated. - - Recommendations on TLS ciphersuites are given in section 12. - - An LDAP server which requests that clients provide their certificate - during TLS negotiation MAY use a local security policy to determine - whether to successfully complete TLS negotiation if the client did not - present a certificate which could be validated. - -8. Password-based authentication - - LDAP implementations MUST support authentication with a password using - the DIGEST-MD5 mechanism for password protection, as defined in section - 8.1. - - LDAP implementations SHOULD support authentication with the "simple" - password choice when the connection is protected against eavesdropping - using TLS, as defined in section 8.2. - -8.1. Digest authentication - - An LDAP client MAY determine whether the server supports this - mechanism by performing a search request on the root DSE, requesting - the supportedSASLMechanisms attribute, and checking whether the - string "DIGEST-MD5" is present as a value of this attribute. - - In the first stage of authentication, when the client is performing - an "initial authentication" as defined in section 2.1 of [4], the - client sends a bind request in which the version number is 3, the - authentication choice is sasl, the sasl mechanism name is "DIGEST-MD5", - and the credentials are absent. The client then waits for a response - from the server to this request. - -Wahl, Alvestrand, Hodges, Morgan Page 7 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - The server will respond with a bind response in which the resultCode - is saslBindInProgress, and the serverSaslCreds field is present. The - contents of this field is a string defined by "digest-challenge" in - section 2.1.1 of [4]. The server SHOULD include a realm indication and - MUST indicate support for UTF-8. - - The client will send a bind request with a distinct mesage id, in which - the version number is 3, the authentication choice is sasl, the sasl - mechanism name is "DIGEST-MD5", and the credentials contain the string - defined by "digest-response" in section 2.1.2 of [4]. The serv-type - is "ldap". - - The server will respond with a bind response in which the resultCode - is either success, or an error indication. If the authentication is - successful and the server does not support subsequent authentication, - then the credentials field is absent. If the authentication is - successful and the server supports subsequent authentication, then - the crendentials field contains the string defined by "response-auth" - in section 2.1.3 of [4]. Support for subsequent authentication is - OPTIONAL in clients and servers. - -8.2. "simple" authentication choice under TLS encryption - - A user who has a directory entry containing a userPassword attribute - MAY authenticate to the directory by performing a simple password - bind sequence following the negotiation of a TLS ciphersuite - providing connection confidentiality [6]. - - The client will use the Start TLS operation [5] to negotiate the - use of TLS security [6] on the connection to the LDAP server. The - client need not have bound to the directory beforehand. - - For this authentication procedure to be successful, the client and - server MUST negotiate a ciphersuite which contains a bulk encryption - algorithm of appropriate strength. Recommendations on cipher - suites are given in section 12. - - Following the successful completion of TLS negotiation, the client - MUST send an LDAP bind request with the version number of 3, the - name field containing the name of the user's entry, and the "simple" - authentication choice, containing a password. - - The server will, for each value of the userPassword attribute in - the named user's entry, compare these for case-sensitive equality - with the client's presented password. If there is a match, then the - server will respond with resultCode success, otherwise the server will - respond with resultCode invalidCredentials. - - - - - -Wahl, Alvestrand, Hodges, Morgan Page 8 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - -8.3. Other authentication choices with TLS - - It is also possible to perform a SASL authentication exchange of - passwords following the negotiation of TLS. In this case the - client and server need not negotiate a ciphersuite which provides - confidentiality if the only service required is data integrity. - -9. Certificate-based authentication - - LDAP implementations SHOULD support authentication via a client - certificate in TLS, as defined in section 9.1. - -9.1. Certificate-based authentication with TLS - - A user who has a public/private key pair in which the public key has - been signed by a Certification Authority may use this key pair to - authenticate to the directory server if the user's certificate is - requested by the server. The user's certificate subject field - SHOULD be the name of the user's directory entry, and the - Certification Authority must be sufficiently trusted by the - directory server to have issued the certificate in order that the - server can process the certificate. The means by which servers - validate certificate paths is outside the scope of this document. - - A server MAY support mappings for certificates in which the subject - field name is different from the name of the user's directory entry. - A server which supports mappings of names MUST be capable of being - configured to support certificates for which no mapping is required. - - The client will use the Start TLS operation [5] to negotiate the - use of TLS security [6] on the connection to the LDAP server. The - client need not have bound to the directory beforehand. - - In the TLS negotiation, the server MUST request a certificate. The - client will provide its certificate to the server, and MUST perform - a private key-based encryption, proving it has it private key - associated with the certificate. - - As deployments will require protection of sensitive data in transit, - the client and server MUST negotiate a ciphersuite which contains a - bulk encryption algorithm of appropriate strength. Recommendations - of cipher suites are given in section 12. - - The server MUST verify that the client's certificate is valid. - The server will normally check that the certificate is issued by a - known CA, and that none of the certificates on the client's - certificate chain are invalid or revoked. There are several - procedures by which the server can perform these checks. - - Following the successful completion of TLS negotiation, the client - will send an LDAP bind request with the SASL "EXTERNAL" mechanism. - -Wahl, Alvestrand, Hodges, Morgan Page 9 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - -10. Other mechanisms - - The LDAP "simple" authentication choice is not suitable for - authentication on the Internet where there is no network or transport - layer confidentiality. - - As LDAP includes a native anonymous and plaintext authentication - methods, the "ANONYMOUS" and "PLAIN" SASL mechanisms are not used - with LDAP. If an authorization identity of a form different from - a DN is requested by the client, a mechanism that protects the - password in transit SHOULD be used. - - The following SASL-based mechanisms are not considered in this - document: KERBEROS_V4, GSSAPI and SKEY. - - The "EXTERNAL" SASL mechanism can be used to request the LDAP server - make use of security credentials exchanged by a lower layer. If a - TLS session has not been established between the client and server - prior to making the SASL EXTERNAL Bind request and there is no other - external source of authentication credentials (e.g. IP-level - security [8]), or if, during the process of establishing the - TLS session, the server did not request the client's authentication - credentials, the SASL EXTERNAL bind MUST fail with a result code of - inappropriateAuthentication. Any authentication identity and - authorization identity, as well as TLS connection, which were in - effect prior to making the Bind request, MUST remain in force. - -11. Authorization Identity - - The authorization identity is carried as part of the SASL credentials - field in the LDAP Bind request and response. - - When the "EXTERNAL" mechanism is being negotiated, if the - credentials field is present, it contains an authorization identity - of the authzId form described below. - - Other mechanisms define the location of the authorization - identity in the credentials field. - - The authorization identity is a string in the UTF-8 character set, - corresponding to the following ABNF [7]: - - ; Specific predefined authorization (authz) id schemes are - ; defined below -- new schemes may be defined in the future. - - authzId = dnAuthzId / uAuthzId - - ; distinguished-name-based authz id. - dnAuthzId = "dn:" dn - dn = utf8string ; with syntax defined in RFC 2253 - - -Wahl, Alvestrand, Hodges, Morgan Page 10 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - ; unspecified userid, UTF-8 encoded. - uAuthzId = "u:" userid - userid = utf8string ; syntax unspecified - - A utf8string is defined to be the UTF-8 encoding of one or more - ISO 10646 characters. - - All servers which support the storage of authentication credentials, - such as passwords or certificates, in the directory MUST support the - dnAuthzId choice. - - The uAuthzId choice allows for compatibility with client applications - which wish to authenticate to a local directory but do not know their - own Distinguished Name or have a directory entry. The format of the - string is defined as only a sequence of UTF-8 encoded ISO 10646 - characters, and further interpretation is subject to prior agreement - between the client and server. - - For example, the userid could identify a user of a specific directory - service, or be a login name or the local-part of an RFC 822 email - address. In general a uAuthzId MUST NOT be assumed to be globally - unique. - - Additional authorization identity schemes MAY be defined in future - versions of this document. - -12. TLS Ciphersuites - - The following ciphersuites defined in [6] MUST NOT be used for - confidentiality protection of passwords or data: - - TLS_NULL_WITH_NULL_NULL - TLS_RSA_WITH_NULL_MD5 - TLS_RSA_WITH_NULL_SHA - - The following ciphersuites defined in [6] can be cracked easily - (less than a week of CPU time on a standard CPU in 1997). The - client and server SHOULD carefully consider the value of the - password or data being protected before using these ciphersuites: - - TLS_RSA_EXPORT_WITH_RC4_40_MD5 - TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 - TLS_RSA_EXPORT_WITH_DES40_CBC_SHA - TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA - TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA - TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA - TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA - TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 - TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA - - - -Wahl, Alvestrand, Hodges, Morgan Page 11 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - The following ciphersuites are vulnerable to man-in-the-middle - attacks, and SHOULD NOT be used to protect passwords or sensitive - data, unless the network configuration is such that the danger of - a man-in-the-middle attack is tolerable: - - TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 - TLS_DH_anon_WITH_RC4_128_MD5 - TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA - TLS_DH_anon_WITH_DES_CBC_SHA - TLS_DH_anon_WITH_3DES_EDE_CBC_SHA - - A client or server that supports TLS MUST support at least - TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA. - -13. SASL service name for LDAP - - For use with SASL [2], a protocol must specify a service name to be - used with various SASL mechanisms, such as GSSAPI. For LDAP, the - service name is "ldap", which has been registered with the IANA - as a GSSAPI service name. - -14. Security Considerations - - Security issues are discussed throughout this memo; the - (unsurprising) conclusion is that mandatory security is important, - and that session encryption is required when snooping is a - problem. - - Servers are encouraged to prevent modifications by anonymous - users. Servers may also wish to minimize denial of service attacks - by timing out idle connections, and returning the unwillingToPerform - result code rather than performing computationally expensive - operations requested by unauthorized clients. - - A connection on which the client has not performed the Start TLS - operation or negotiated a suitable SASL mechanism for connection - integrity and encryption services is subject to man-in-the-middle - attacks to view and modify information in transit. - - Additional security considerations relating to the EXTERNAL - EXTERNAL mechanism to negotiate TLS can be found in [2], [5] - and [6]. - -15. Acknowledgements - - This document is a product of the LDAPEXT Working Group of the - IETF. The contributions of its members is greatly appreciated. - - - - - -Wahl, Alvestrand, Hodges, Morgan Page 12 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - -16. Bibliography - - [1] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access - Protocol (v3)", Dec. 1997, RFC 2251. - - [2] J. Myers, "Simple Authentication and Security Layer (SASL)", - Oct. 1997, RFC 2222. - - [3] S. Bradner, "Key words for use in RFCs to Indicate Requirement - Levels", RFC 2119. - - [4] P. Leach, C. Newman, "Using Digest Authentication as a SASL - Mechanism", INTERNET DRAFT . - - [5] J. Hodges, RL Morgan, M. Wahl, "LDAPv3 Extension for Transport - Layer Security", Oct. 1998, INTERNET DRAFT - . - - [6] T. Diers, C. Allen, "The TLS Protocol Version 1.0", Jan. 1999, - RFC 2246. - - [7] D. Crocker, Ed., P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234. - - [8] S. Kent, R. Atkinson, "Security Architecture for the Internet - Protocol", Nov. 1998, RFC 2401. - -17. Authors Address - - Mark Wahl - Innosoft International, Inc. - 8911 Capital of Texas Hwy, Suite 4140 - Austin, TX 78759 - USA - Phone: +1 512 231 1600 - EMail: Mark.Wahl@innosoft.com - - Harald Tveit Alvestrand - EMail: Harald.Alvestrand@maxware.no - - Jeff Hodges - Computing & Communication Services - Stanford University - Pine Hall - 241 Panama Street - Stanford, CA 94305-4122 - USA - Phone: +1-650-723-2452 - EMail: Jeff.Hodges@Stanford.edu - - - -Wahl, Alvestrand, Hodges, Morgan Page 13 - -INTERNET-DRAFT Authentication Methods for LDAP June 1999 - - RL "Bob" Morgan - Computing & Communication Services - Stanford University - Pine Hall - 241 Panama Street - Stanford, CA 94305-4122 - USA - Phone: +1-650-723-9711 - EMail: Bob.Morgan@Stanford.edu - -Full Copyright Statement - - Copyright (C) The Internet Society (1998). All Rights Reserved. - - 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 the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - -Wahl, Alvestrand, Hodges, Morgan Page 14 - diff --git a/doc/drafts/draft-ietf-ldapext-ldapv3-tls-xx.txt b/doc/drafts/draft-ietf-ldapext-ldapv3-tls-xx.txt deleted file mode 100644 index 34f2b1f76d..0000000000 --- a/doc/drafts/draft-ietf-ldapext-ldapv3-tls-xx.txt +++ /dev/null @@ -1,669 +0,0 @@ -LDAPEXT Working Group Jeff Hodges, Stanford -INTERNET-DRAFT RL "Bob" Morgan, Univ of Washington -Intended Category: Mark Wahl, Innosoft - Standards Track June, 1999 - - - Lightweight Directory Access Protocol (v3): - Extension for Transport Layer Security - - - - - Status of this Document - -This document is an Internet-Draft and is in full conformance with all -provisions of Section 10 of RFC2026. - -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. - -Comments and suggestions on this document are encouraged. Comments on -this document should be sent to the LDAPEXT working group discussion -list: - ietf-ldapext@netscape.com - -This document expires in December 1999. - - -1. Abstract - -This document defines the "Start Transport Layer Security (TLS) Opera- -tion" for LDAP [LDAPv3, TLS]. This operation provides for TLS establish- -ment in an LDAP association and is defined in terms of an LDAP extended -request. - - - - - -Hodges, Morgan, Wahl [Page 1] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -2. Conventions Used in this Document - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in [ReqsKeywords]. - -3. The Start TLS Request - -This section describes the Start TLS extended request and extended -response themselves: how to form the request, the form of the response, -and enumerates the various result codes the client MUST be prepared to -handle. - -The section following this one then describes how to sequence an overall -Start TLS Operation. - -3.1. Requesting TLS Establishment - -A client may perform a Start TLS operation by transmitting an LDAP PDU -containing an ExtendedRequest [LDAPv3] specifying the OID for the Start -TLS operation: - - 1.3.6.1.4.1.1466.20037 - -An LDAP ExtendedRequest is defined as follows: - - ExtendedRequest ::= [APPLICATION 23] SEQUENCE { - requestName [0] LDAPOID, - requestValue [1] OCTET STRING OPTIONAL } - -A Start TLS extended request is formed by setting the requestName field -to the OID string given above. The requestValue field is absent. The -client MUST NOT send any PDUs on this connection following this request -until it receives a Start TLS extended response. - -When a Start TLS extended request is made, the server MUST return an -LDAP PDU containing a Start TLS extended response. An LDAP Exten- -dedResponse is defined as follows: - - ExtendedResponse ::= [APPLICATION 24] SEQUENCE { - COMPONENTS OF LDAPResult, - responseName [10] LDAPOID OPTIONAL, - response [11] OCTET STRING OPTIONAL } - -A Start TLS extended response MUST contain a responseName field which -MUST be set to the same string as that in the responseName field present -in the Start TLS extended request. The response field is absent. The -server MUST set the resultCode field to either success or one of the - - - -Hodges, Morgan, Wahl [Page 2] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -other values outlined in section 3.3. - -3.2. "Success" Response - -If the ExtendedResponse contains a resultCode of success, this indicates -that the server is willing and able to negotiate TLS. Refer to section -4, below, for details. - -3.3. Response other than "success" - -If the ExtendedResponse contains a resultCode other than success, this -indicates that the server is unwilling or unable to negotiate TLS. - -If the Start TLS extended request was not successful, the resultCode -will be one of: - - operationsError (operations sequencing incorrect; e.g. TLS already - established) - - protocolError (TLS not supported or incorrect PDU structure) - - referral (this server doesn't do TLS, try this one) - - unavailable (e.g. some major problem with TLS, or server is - shutting down) - -The server MUST return operationsError if the client violates any of the -Start TLS extended operation sequencing requirements described in sec- -tion 4, below. - -If the server does not support TLS (whether by design or by current con- -figuration), it MUST set the resultCode to protocolError (see section -4.1.1 of [LDAPv3]), or to referral. The server MUST include an actual -referral value in the LDAP Result if it returns a resultCode of refer- -ral. The client's current session is unaffected if the server does not -support TLS. The client MAY proceed with any LDAP operation, or it MAY -close the connection. - -The server MUST return unavailable if it supports TLS but cannot estab- -lish a TLS connection for some reason, e.g. the certificate server not -responding, it cannot contact its TLS implementation, or if the server -is in process of shutting down. The client MAY retry the StartTLS opera- -tion, or it MAY proceed with any other LDAP operation, or it MAY close -the connection. - -4. Sequencing of the Start TLS Operation - -This section describes the overall procedures clients and servers MUST - - - -Hodges, Morgan, Wahl [Page 3] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -follow for TLS establishment. These procedures take into consideration -various aspects of the overall security of the LDAP association includ- -ing discovery of resultant security level and assertion of the client's -authorization identity. - -Note that the precise effects, on a client's authorzation identity, of -establishing TLS on an LDAP association are described in detail in sec- -tion 7. - -4.1. Requesting to Start TLS on an LDAP Association - -The client MAY send the Start TLS extended request at any time after -establishing an LDAP association, except that in the following cases the -client MUST NOT send a Start TLS extended request: - - - if TLS is currently established on the connection, or - - during a multi-stage SASL negotiation, or - - if there are any LDAP operations outstanding on the connection. - -The result of violating any of these requirements is a resultCode of -operationsError, as described above in section 3.3. - -The client MAY have already perfomed a Bind operation when it sends a -Start TLS request, or the client might have not yet bound. - -If the client did not establish a TLS connection before sending any -other requests, and the server requires the client to establish a TLS -connection before performing a particular request, the server MUST -reject that request with a confidentialityRequired or strongAuthRequired -result. The client MAY send a Start TLS extended request, or it MAY -choose to close the connection. - -4.2. Starting TLS - -The server will return an extended response with the resultCode of suc- -cess if it is willing and able to negotiate TLS. It will return other -resultCodes, documented above, if it is unable. - -In the successful case, the client, which has ceased to transfer LDAP -requests on the connection, MUST either begin a TLS negotiation or close -the connection. The client will send PDUs in the TLS Record Protocol -directly over the underlying transport connection to the server to ini- -tiate TLS negotiation [TLS]. - -4.3. TLS Version Negotiation - -Negotiating the version of TLS or SSL to be used is a part of the TLS -Handshake Protocol, as documented in [TLS]. Please refer to that - - - -Hodges, Morgan, Wahl [Page 4] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -document for details. - -4.4. Discovery of Resultant Security Level - -After a TLS connection is established on an LDAP association, both par- -ties MUST individually decide whether or not to continue based on the -privacy level achieved. Ascertaining the TLS connection's privacy level -is implementation dependent, and accomplished by communicating with -one's respective local TLS implementation. - -If the client or server decides that the level of authentication or -privacy is not high enough for it to continue, it SHOULD gracefully -close the TLS connection immediately after the TLS negotiation has com- -pleted (see sections 5 and 7.2, below). - -The client MAY attempt to Start TLS again, or MAY send an unbind -request, or send any other LDAP request. - -4.5. Assertion of Client's Authorization Identity - -The client MAY, upon receipt of a Start TLS extended response indicating -success, assert that a specific authorization identity be utilized in -determining the client's authorization status. The client accomplishes -this via an LDAP Bind request specifying a SASL mechanism of "EXTERNAL" -[SASL]. See section 7, below. - -4.6. Server Identity Check - -The client MUST check its understanding of the server's hostname against -the server's identity as presented in the server's Certificate message, -in order to prevent man-in-the-middle attacks. - -If a subjectAltName extension of type dNSName is present, it SHOULD be -used as the source of the server's identity. - -Matching is performed according to these rules: - - - The client MUST use the server hostname it used to open - the LDAP connection as the value to compare against the - server name as expressed in the server's certificate. - The client MUST NOT use the server's canonical DNS name or - any other derived form of name. - - - If a subjectAltName extension of type dNSName is present - in the certificate, it SHOULD be used as the source of the - server's identity. - - - Matching is case-insensitive. - - - -Hodges, Morgan, Wahl [Page 5] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - - - The "*" wildcard character is allowed. - - If present, it applies only to the left-most name component. - -E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com. -If more than one identity of a given type is present in the certificate -(e.g. more than one dNSName name), a match in any one of the set is con- -sidered acceptable. - -If the hostname does not match the dNSName-based identity in the certi- -ficate per the above check, user-oriented clients SHOULD either notify -the user (clients MAY give the user the opportunity to continue with the -connection in any case) or terminate the connection and indicate that -the server's identity is suspect. Automated clients SHOULD close the -connection, returning and/or logging an error indicating hat the -server's identity is suspect. - -4.7. Refresh of Server Capabilities Information - -The client MUST refresh any cached server capabilities information (e.g. -from the server's root DSE; see section 3.4 of [LDAPv3]) upon TLS ses- -sion establishment. This is necessary to protect against active- -intermediary attacks which may have altered any server capabilities -information retrieved prior to TLS establishment. The server MAY adver- -tise different capabilities after TLS establishment. - -5. Closing a TLS Connection - -5.1. Graceful Closure - -Either the client or server MAY terminate the TLS connection on an LDAP -association by sending a TLS closure alert. This will leave the LDAP -association intact. - -Before closing a TLS connection, the client MUST either wait for any -outstanding LDAP operations to complete, or explicitly abandon them -[LDAPv3]. - -After the initiator of a close has sent a closure alert, it MUST discard -any TLS messages until it has received an alert from the other party. -It will cease to send TLS Record Protocol PDUs, and following the -reciept of the alert, MAY send and receive LDAP PDUs. - -The other party, if it receives a closure alert, MUST immediately -transmit a TLS closure alert. It will subequently cease to send TLS -Record Protocol PDUs, and MAY send and receive LDAP PDUs. - - - - - - -Hodges, Morgan, Wahl [Page 6] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -5.2. Abrupt Closure - -Either the client or server MAY abruptly close the entire LDAP associa- -tion and any TLS connection established on it by dropping the underlying -TCP connection. A server MAY beforehand send the client a Notice of -Disconnection [LDAPv3] in this case. - -6. Authentication and Authorization: Definitions and Concepts - -This section defines basic terms, concepts, and interrelationships -regarding authentication, authorization, credentials, and identity. -These concepts are used in describing how various security approaches -are utilized in client authentication and authorization. - -6.1. Access Control Policy - -An access control policy is a set of rules defining the protection of -resources, generally in terms of the capabilities of persons or other -entities accessing those resources. A common expression of an access -control policy is an access control list. Security objects and mechan- -isms, such as those described here, enable the expression of access con- -trol policies and their enforcement. Access control policies are typi- -cally expressed in terms of access control attributes as described -below. - -7. Effects of TLS on a Client's Authorization Identity - -This section describes the effects on a client's authorization identity -brought about by establishing TLS on an LDAP association. The default -effects are described first, and next the facilities for client asser- -tion of authorization identity are discussed including error conditions. -Lastly, the effects of closing the TLS connection are described. - -Authorization identities and related concepts are defined in [AuthMeth]. - -7.1. TLS Connection Establishment Effects - -7.1.1. Default Effects - -Upon establishment of the TLS connection onto the LDAP association, any -previously established authentication and authorization identities MUST -remain in force, including anonymous state. This holds even in the case -where the server requests client authentication via TLS -- e.g. requests -the client to supply its certificate during TLS negotiation (see [TLS]). - -7.1.2. Client Assertion of Authorization Identity - -A client MAY either implicitly request that its LDAP authorization - - - -Hodges, Morgan, Wahl [Page 7] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -identity be derived from its authenticated TLS credentials or it MAY -explicitly provide an authorization identity and assert that it be used -in combination with its authenticated TLS credentials. The former is -known as an implicit assertion, and the latter as an explicit assertion. - -7.1.2.1. Implicit Assertion - -An implicit authorization identity assertion is accomplished after TLS -establishment by invoking a Bind request of the SASL form using the -"EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL NOT include the -optional credentials octet string (found within the SaslCredentials -sequence in the Bind Request). The server will derive the client's -authorization identity from the authentication identity supplied in the -client's TLS credentials (typically a public key certificate) according -to local policy. The underlying mechanics of how this is accomplished -are implementation specific. - -7.1.2.2. Explicit Assertion - -An explicit authorization identity assertion is accomplished after TLS -establishment by invoking a Bind request of the SASL form using the -"EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL include the creden- -tials octet string. This string MUST be constructed as documented in -section 11 of [AuthMeth]. - -7.1.2.3. Error Conditions - -For either form of assertion, the server MUST verify that the client's -authentication identity as supplied in its TLS credentials is permitted -to be mapped to the asserted authorization identity. The server MUST -reject the Bind operation with an invalidCredentials resultCode in the -Bind response if the client is not so authorized. The LDAP association's -authentication identity and authorization identity (if any) which were -in effect after TLS establishment but prior to making the Bind request, -MUST remain in force. - -Additionally, with either form of assertion, if a TLS session has not -been established between the client and server prior to making the SASL -EXTERNAL Bind request and there is no other external source of authenti- -cation credentials (e.g. IP-level security RFC 1825), or if, during the -process of establishing the TLS session, the server did not request the -client's authentication credentials, the SASL EXTERNAL bind MUST fail -with a result code of inappropriateAuthentication. Any authentication -identity and authorization identity, as well as TLS connection, which -were in effect prior to making the Bind request, MUST remain in force. - - - - - - -Hodges, Morgan, Wahl [Page 8] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -7.2. TLS Connection Closure Effects - -Closure of the TLS connection MUST cause the LDAP association to move to -an anonymous authentication and authorization state regardless of the -state established over TLS and regardless of the authentication and -authorization state prior to TLS connection establishment. - -8. Security Considerations - -The goals of using the TLS protocol with LDAP are to ensure connection -confidentiality and integrity, and to optionally provide for authentica- -tion. TLS expressly provides these capabilities, as described in [TLS]. - -All security gained via use of the Start TLS operation is gained by the -use of TLS itself. The Start TLS operation, on its own, does not provide -any additional security. - -The use of TLS does not provide or ensure for confidentiality and/or -non-repudiation of the data housed by an LDAP-based directory server. -Nor does it secure the data from inspection by the server administra- -tors. Once established, TLS only provides for and ensures confidential- -ity and integrity of the operations and data in transit over the LDAP -association, and only if the implementations on the client and server -support and negotiate it. - -The level of security provided though the use of TLS depends directly on -both the quality of the TLS implementation used and the style of usage -of that implementation. Additionally, an active-intermediary attacker -can remove the Start TLS extended operation from the supportedExtension -attribute of the root DSE. Therefore, both parties SHOULD independently -ascertain and consent to the security level achieved once TLS is esta- -blished and before begining use of the TLS connection. For example, the -security level of the TLS connection might have been negotiated down to -plaintext. - -Clients SHOULD either warn the user when the security level achieved -does not provide confidentiality and/or integrity protection, or be con- -figurable to refuse to proceed without an acceptable level of security. - -Client and server implementors SHOULD take measures to ensure proper -protection of credentials and other confidential data where such meas- -ures are not otherwise provided by the TLS implementation. - -Server implementors SHOULD allow for server administrators to elect -whether and when connection confidentiality and/or integrity is -required, as well as elect whether and when client authentication via -TLS is required. - - - - -Hodges, Morgan, Wahl [Page 9] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - -9. Acknowledgements - -The authors thank Tim Howes, Paul Hoffman, John Kristian, Shirish Rai, -Jonathan Trostle, and Harald Alvestrand for their contributions to this -document. - -10. References - -[AuthMeth] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan. "Authenti- - cation Methods for LDAP". INTERNET-DRAFT, Work In Pro- - gress. draft-ietf-ldapext-authmeth-04.txt - -[LDAPv3] M. Wahl, S. Kille and T. Howes. "Lightweight Directory - Access Protocol (v3)". RFC 2251. - -[ReqsKeywords] Scott Bradner. "Key Words for use in RFCs to Indicate - Requirement Levels". RFC 2119. - -[SASL] J. Myers. "Simple Authentication and Security Layer - (SASL)". RFC 2222. - -[TLS] Tim Dierks, C. Allen. "The TLS Protocol Version 1.0". RFC - 2246. - -11. Authors' Addresses - - Jeff Hodges - Computing & Communication Services - Stanford University - Pine Hall - 241 Panama Street - Stanford, CA 94305-4122 - USA - - Phone: +1-650-723-2452 - EMail: Jeff.Hodges@Stanford.edu - - - RL "Bob" Morgan - Networks and Distributed Computing - University of Washington - Seattle, WA - USA - - Phone: +1-206-221-3307 - EMail: rlmorgan@cac.washington.edu - - - - - -Hodges, Morgan, Wahl [Page 10] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - - Mark Wahl - Innosoft International, Inc. - 8911 Capital of Texas Hwy, Suite 4140 - Austin, TX 78759 - USA - - Phone: +1 626 919 3600 - EMail: Mark.Wahl@innosoft.com - ----------------------------------- - -12. Intellectual Property Rights Notices - -The IETF takes no position regarding the validity or scope of any intel- -lectual property or other rights that might be claimed to pertain to -the implementation or use of the technology described in this document -or the extent to which any license under such rights might or might not -be available; neither does it represent that it has made any effort to -identify any such rights. Information on the IETF's procedures with -respect to rights in standards-track and standards-related documentation -can be found in BCP-11. Copies of claims of rights made available for -publication and any assurances of licenses to be made available, or the -result of an attempt made to obtain a general license or permission for -the use of such proprietary rights by implementors or users of this -specification can be obtained from the IETF Secretariat. - -The IETF invites any interested party to bring to its attention any -copyrights, patents or patent applications, or other proprietary rights -which may cover technology that may be required to practice this stan- -dard. Please address the information to the IETF Executive Director. - -13. Copyright Notice and Disclaimer - - Copyright (C) The Internet Society (1998). All Rights Reserved. - - 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 the Internet Society or other - Internet organizations, except as needed for the purpose of develop- - ing Internet standards in which case the procedures for copyrights - defined in the Internet Standards process must be followed, or as - required to translate it into languages other than English. - - The limited permissions granted above are perpetual and will not be - - - -Hodges, Morgan, Wahl [Page 11] - -I-D LDAPv3: Extension for Transport Layer Security June 1999 - - - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MER- - CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hodges, Morgan, Wahl [Page 12] - diff --git a/doc/drafts/draft-leach-digest-sasl-xx.txt b/doc/drafts/draft-leach-digest-sasl-xx.txt deleted file mode 100644 index 863aee0f84..0000000000 --- a/doc/drafts/draft-leach-digest-sasl-xx.txt +++ /dev/null @@ -1,1622 +0,0 @@ - Digest SASL Mechanism September, 1999 - - - - -Network Working Group Paul J. Leach, Microsoft -INTERNET-DRAFT Chris Newman, Innosoft -draft-leach-digest-sasl-05.txt -Category: Standards Track -Expires April 21, 2000 October 21, 1999 - - - - Using Digest Authentication as a SASL Mechanism - - Author's draft: 16 - - - - -STATUS OF THIS MEMO - -This document is an Internet-Draft and is in full conformance with all -provisions of Section 10 of RFC2026. - -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. - -Distribution of this document is unlimited. Please send comments to the -authors or the SASL mailing list, ietf-sasl@imc.org. - -Copyright Notice: Copyright (C) The Internet Society (1998). All Rights -Reserved. See section 8 for the full copyright notice. - - -ABSTRACT - -This specification defines how HTTP Digest Authentication [Digest] can -be used as a SASL [RFC 2222] mechanism for any protocol that has a SASL -profile. It is intended both as an improvement over CRAM-MD5 [RFC2195] -and as a convenient way to support a single authentication mechanism for -web, mail, LDAP, and other protocols. - - - - -Leach, Newman Standards Track [Page 1] - - - Digest SASL Mechanism September, 1999 - - - - -Table of Contents - -1 INTRODUCTION........................................................3 - 1.1 CONVENTIONS AND NOTATION..........................................3 - - 1.2 REQUIREMENTS......................................................4 - -2 AUTHENTICATION......................................................4 - 2.1 INITIAL AUTHENTICATION............................................4 - - 2.1.1 Step One......................................................4 - - 2.1.2 Step Two......................................................7 - - 2.1.3 Step Three...................................................12 - - 2.2 SUBSEQUENT AUTHENTICATION........................................13 - - 2.2.1 Step one.....................................................13 - - 2.2.2 Step Two.....................................................13 - - 2.3 INTEGRITY PROTECTION.............................................14 - - 2.4 CONFIDENTIALITY PROTECTION.......................................14 - -3 SECURITY CONSIDERATIONS............................................15 - 3.1 AUTHENTICATION OF CLIENTS USING DIGEST AUTHENTICATION............15 - - 3.2 COMPARISON OF DIGEST WITH PLAINTEXT PASSWORDS....................16 - - 3.3 REPLAY ATTACKS...................................................16 - - 3.4 ONLINE DICTIONARY ATTACKS........................................16 - - 3.5 OFFLINE DICTIONARY ATTACKS.......................................16 - - 3.6 MAN IN THE MIDDLE................................................17 - - 3.7 CHOSEN PLAINTEXT ATTACKS.........................................17 - - 3.8 SPOOFING BY COUNTERFEIT SERVERS..................................17 - - 3.9 STORING PASSWORDS................................................17 - - 3.10 MULTIPLE REALMS................................................18 - - - - -Leach, Newman Standards Track [Page 2] - - - Digest SASL Mechanism September, 1999 - - - - - 3.11 SUMMARY........................................................18 - -4 EXAMPLE............................................................18 - -5 REFERENCES.........................................................20 - -6 AUTHORS' ADDRESSES.................................................21 - -7 ABNF...............................................................21 - 7.1 AUGMENTED BNF....................................................22 - - 7.2 BASIC RULES......................................................23 - -8 SAMPLE CODE........................................................25 - -9 FULL COPYRIGHT STATEMENT...........................................26 - - - -1 Introduction - -This specification describes the use of HTTP Digest Access -Authentication as a SASL mechanism. The authentication type associated -with the Digest SASL mechanism is "DIGEST-MD5". - -This specification is intended to be upward compatible with the "md5- -sess" algorithm of HTTP/1.1 Digest Access Authentication specified in -[Digest]. The only difference in the "md5-sess" algorithm is that some -directives not needed in a SASL mechanism have had their values -defaulted. - -There is one new feature for use as a SASL mechanism: integrity -protection on application protocol messages after an authentication -exchange. - -Also, compared to CRAM-MD5, DIGEST-MD5 prevents chosen plaintext -attacks, and permits the use of third party authentication servers, -mutual authentication, and optimized reauthentication if a client has -recently authenticated to a server. - -1.1 Conventions and Notation - -This specification uses the same ABNF notation and lexical conventions -as HTTP/1.1 specification; see appendix A. - -Let { a, b, ... } be the concatenation of the octet strings a, b, ... - -Let H(s) be the 16 octet MD5 hash [RFC 1321] of the octet string s. - - - -Leach, Newman Standards Track [Page 3] - - - Digest SASL Mechanism September, 1999 - - - - -Let KD(k, s) be H({k, ":", s}), i.e., the 16 octet hash of the string k, -a colon and the string s. - -Let HEX(n) be the representation of the 16 octet MD5 hash n as a string -of 32 hex digits (with alphabetic characters always in lower case, since -MD5 is case sensitive). - -Let HMAC(k, s) be the 16 octet HMAC-MD5 [RFC 2104] of the octet string s -using the octet string k as a key. - -The value of a quoted string constant as an octet string does not -include any terminating null character. - -1.2 Requirements - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in RFC 2119 [RFC 2119]. - -An implementation is not compliant if it fails to satisfy one or more of -the MUST level requirements for the protocols it implements. An -implementation that satisfies all the MUST level and all the SHOULD -level requirements for its protocols is said to be "unconditionally -compliant"; one that satisfies all the MUST level requirements but not -all the SHOULD level requirements for its protocols is said to be -"conditionally compliant." - - -2 Authentication - -The following sections describe how to use Digest as a SASL -authentication mechanism. - -2.1 Initial Authentication - -If the client has not recently authenticated to the server, then it must -perform "initial authentication", as defined in this section. If it has -recently authenticated, then a more efficient form is available, defined -in the next section. - -2.1.1Step One - -The server starts by sending a challenge. The data encoded in the -challenge contains a string formatted according to the rules for a -"digest-challenge" defined as follows: - -digest-challenge = - 1#( realm | nonce | qop-options | stale | maxbuf | charset - algorithm | cipher-opts | auth-param ) - - - - -Leach, Newman Standards Track [Page 4] - - - Digest SASL Mechanism September, 1999 - - - - - - realm = "realm" "=" <"> realm-value <"> - realm-value = qdstr-val - nonce = "nonce" "=" <"> nonce-value <"> - nonce-value = qdstr-val - qop-options = "qop" "=" <"> qop-list <"> - qop-list = 1#qop-value - qop-value = "auth" | "auth-int" | "auth-conf" | - token - stale = "stale" "=" "true" - maxbuf = "maxbuf" "=" maxbuf-value - maxbuf-value = 1*DIGIT - charset = "charset" "=" "utf-8" - algorithm = "algorithm" "=" "md5-sess" - cipher-opts = "cipher" "=" <"> 1#cipher-value <"> - cipher-value = "3des" | "des" | "rc4-40" | "rc4" | - "rc4-56" | token - auth-param = token "=" ( token | quoted-string ) - -The meanings of the values of the directives used above are as follows: - -realm - Mechanistically, a string which can enable users to know which - username and password to use, in case they might have different ones - for different servers. Conceptually, it is the name of a collection - of accounts that might include the user's account. This string should - contain at least the name of the host performing the authentication - and might additionally indicate the collection of users who might - have access. An example might be - "registered_users@gotham.news.example.com". This directive is - optional; if not present, the client SHOULD solicit it from the user - or be able to compute a default; a plausible default might be the - realm supplied by the user when they logged in to the client system. - Multiple realm directives are allowed, in which case the user or - client must choose one as the realm for which to supply to username - and password. - -nonce - A server-specified data string which MUST be different each time a - digest-challenge is sent as part of initial authentication. It is - recommended that this string be base64 or hexadecimal data. Note that - since the string is passed as a quoted string, the double-quote - character is not allowed unless escaped (see section 7.2). The - contents of the nonce are implementation dependent. The security of - the implementation depends on a good choice. It is RECOMMENDED that - it contain at least 64 bits of entropy. The nonce is opaque to the - client. This directive is required and MUST appear exactly once; if - not present, or if multiple instances are present, the client should - abort the authentication exchange. - - - -Leach, Newman Standards Track [Page 5] - - - Digest SASL Mechanism September, 1999 - - - - -qop-options - A quoted string of one or more tokens indicating the "quality of - protection" values supported by the server. The value "auth" - indicates authentication; the value "auth-int" indicates - authentication with integrity protection; the value "auth-conf" - indicates authentication with integrity protection and encryption. - This directive is optional; if not present it defaults to "auth". The - client MUST ignore unrecognized options; if the client recognizes no - option, it should abort the authentication exchange. - -stale - The "stale" directive is not used in initial authentication. See the - next section for its use in subsequent authentications. This - directive may appear at most once; if multiple instances are present, - the client should abort the authentication exchange. - -maxbuf - A number indicating the size of the largest buffer the server is able - to receive when using "auth-int" or "auth-conf". If this directive is - missing, the default value is 65536. This directive may appear at - most once; if multiple instances are present, the client should abort - the authentication exchange. - -charset - This directive, if present, specifies that the server supports UTF-8 - encoding for the username and password. If not present, the username - and password must be encoded in ISO 8859-1 (of which US-ASCII is a - subset). The directive is needed for backwards compatibility with - HTTP Digest, which only supports ISO 8859-1. This directive may - appear at most once; if multiple instances are present, the client - should abort the authentication exchange. - -algorithm - This directive is required for backwards compatibility with HTTP - Digest., which supports other algorithms. . This directive is - required and MUST appear exactly once; if not present, or if multiple - instances are present, the client should abort the authentication - exchange. - -cipher-opts - A list of ciphers that the server supports. This directive must be - present exactly once if "auth-conf" is offered in the "qop-options" - directive, in which case the "3des" and "des" modes are mandatory-to- - implement. The client MUST ignore unrecognized options; if the client - recognizes no option, it should abort the authentication exchange. - - - - - - -Leach, Newman Standards Track [Page 6] - - - Digest SASL Mechanism September, 1999 - - - - - des - the Data Encryption Standard (DES) cipher [FIPS] in cipher block - chaining (CBC) mode with a 56 bit key. - - 3des - the "triple DES" cipher in CBC mode with EDE with the same key for - each E stage (aka "two keys mode") for a total key length of 112 - bits. - - rc4, rc4-40, rc4-56 - the RC4 cipher with a 128 bit, 40 bit, and 56 bit key, - respectively. - -auth-param - This construct allows for future extensions; it may appear more than - once. The client MUST ignore any unrecognized directives. - -For use as a SASL mechanism, note that the following changes are made to -"digest-challenge" from HTTP: the following Digest options (called -"directives" in HTTP terminology) are unused (i.e., MUST NOT be sent, -and MUST be ignored if received): - - opaque - domain - -The size of a digest-challenge MUST be less than 2048 bytes. - -2.1.2Step Two - -The client makes note of the "digest-challenge" and then responds with a -string formatted and computed according to the rules for a "digest- -response" defined as follows: - -digest-response = 1#( username | realm | nonce | cnonce | - nonce-count | qop | digest-uri | response | - maxbuf | charset | cipher | authzid | - auth-param ) - - username = "username" "=" <"> username-value <"> - username-value = qdstr-val - cnonce = "cnonce" "=" <"> cnonce-value <"> - cnonce-value = qdstr-val - nonce-count = "nc" "=" nc-value - nc-value = 8LHEX - qop = "qop" "=" qop-value - digest-uri = "digest-uri" "=" <"> digest-uri-value <"> - digest-uri-value = serv-type "/" host [ "/" serv-name ] - serv-type = 1*ALPHA - host = 1*( ALPHA | DIGIT | "-" | "." ) - - - -Leach, Newman Standards Track [Page 7] - - - Digest SASL Mechanism September, 1999 - - - - - serv-name = host - response = "response" "=" response-value - response-value = 32LHEX - LHEX = "0" | "1" | "2" | "3" | - "4" | "5" | "6" | "7" | - "8" | "9" | "a" | "b" | - "c" | "d" | "e" | "f" - cipher = "cipher" "=" cipher-value - authzid = "authzid" "=" <"> authzid-value <"> - authzid-value = qdstr-val - - - -username - The user's name in the specified realm, encoded according to the - value of the "charset" directive. This directive is required and MUST - be present exactly once; otherwise, authentication fails. - -realm - The realm containing the user's account. This directive is required - if the server provided any realms in the "digest-challenge", in which - case it may appear exactly once and its value SHOULD be one of those - realms. If the directive is missing, "realm-value" will set to the - empty string when computing A1 (see below for details). - -nonce - The server-specified data string received in the preceding digest- - challenge. This directive is required and MUST be present exactly - once; otherwise, authentication fails. - -cnonce - A client-specified data string which MUST be different each time a - digest-response is sent as part of initial authentication. The - cnonce-value is an opaque quoted string value provided by the client - and used by both client and server to avoid chosen plaintext attacks, - and to provide mutual authentication. The security of the - implementation depends on a good choice. It is RECOMMENDED that it - contain at least 64 bits of entropy. This directive is required and - MUST be present exactly once; otherwise, authentication fails. - -nonce-count - The nc-value is the hexadecimal count of the number of requests - (including the current request) that the client has sent with the - nonce value in this request. For example, in the first request sent - in response to a given nonce value, the client sends "nc=00000001". - The purpose of this directive is to allow the server to detect - request replays by maintaining its own copy of this count - if the - same nc-value is seen twice, then the request is a replay. See the - - - -Leach, Newman Standards Track [Page 8] - - - Digest SASL Mechanism September, 1999 - - - - - description below of the construction of the response value. This - directive may appear at most once; if multiple instances are present, - the client should abort the authentication exchange. - -qop - Indicates what "quality of protection" the client accepted. If - present, it may appear exactly once and its value MUST be one of the - alternatives in qop-options. If not present, it defaults to "auth". - These values affect the computation of the response. Note that this - is a single token, not a quoted list of alternatives. - -serv-type - Indicates the type of service, such as "www" for web service, "ftp" - for FTP service, "smtp" for mail delivery service, etc. The service - name as defined in the SASL profile for the protocol see section 4 of - [RFC 2222], registered in the IANA registry of "service" elements for - the GSSAPI host-based service name form [RFC 2078]. Regardless of - case, they are lower cased when used in hash computations. - -host - The DNS host name or IP address for the service requested. The DNS - host name must be the fully-qualified canonical name of the host. - The DNS host name is the preferred form; see notes on server - processing of the digest-uri. - -serv-name - Indicates the name of the service if it is replicated. The service is - considered to be replicated if the client's service-location process - involves resolution using standard DNS lookup operations, and if - these operations involve DNS records (such as SRV, or MX) which - resolve one DNS name into a set of other DNS names. In this case, the - initial name used by the client is the "serv-name", and the final - name is the "host" component. For example, the incoming mail service - for "example.com" may be replicated through the use of MX records - stored in the DNS, one of which points at an SMTP server called - "mail3.example.com"; it's "serv-name" would be "example.com", it's - "host" would be "mail3.example.com". If the service is not - replicated, or the serv-name is identical to the host, then the serv- - name component MUST be omitted. - -digest-uri - Indicates the principal name of the service with which the client - wishes to connect, formed from the serv-type, host, and serv-name. - For example, the FTP service on "ftp.example.com" would have a - "digest-uri" value of "ftp/ftp.example.com"; the SMTP server from the - example above would have a "digest-uri" value of - "smtp/mail3.example.com/example.com". - - - - -Leach, Newman Standards Track [Page 9] - - - Digest SASL Mechanism September, 1999 - - - - - Servers SHOULD check that the supplied value is correct. This will - detect accidental connection to the incorrect server. It is also so - that clients will be trained to provide values that will work with - implementations that use a shared back-end authentication service - that can provide server authentication. - - The serv-type component should match the service being offered. The - host component should match one of the host names of the host on - which the service is running, or it's IP address. Servers SHOULD NOT - normally support the IP address form, because server authentication - by IP address is not very useful; they should only do so if the DNS - is unavailable or unreliable. The serv-name component should match - one of the service's configured service names. - - This directive may appear at most once; if multiple instances are - present, the client should abort the authentication exchange. - - Note: In the HTTP use of Digest authentication, the digest-uri is the - URI (usually a URL) of the resource requested -- hence the name of - the directive. - -response - A string of 32 hex digits computed as defined below, which proves - that the user knows a password. This directive is required and MUST - be present exactly once; otherwise, authentication fails. - -maxbuf - A number indicating the size of the largest buffer the client is able - to receive. If this directive is missing, the default value is 65536. - This directive may appear at most once; if multiple instances are - present, the server should abort the authentication exchange. - -charset - This directive, if present, specifies that the client has used UTF-8 - encoding for the username and password. If not present, the username - and password must be encoded in ISO 8859-1 (of which US-ASCII is a - subset). The client should send this directive only if the server has - indicated it supports UTF-8. The directive is needed for backwards - compatibility with HTTP Digest, which only supports ISO 8859-1. - -LHEX - 32 hex digits, where the alphabetic characters MUST be lower case, - because MD5 is not case insensitive. - -cipher - The cipher chosen by the client. This directive MUST appear exactly - once if "auth-conf" is negotiated; if required and not present, - authentication fails. - - - -Leach, Newman Standards Track [Page 10] - - - Digest SASL Mechanism September, 1999 - - - - -authzid - The "authorization ID" as per RFC 2222, encoded in UTF-8. This - directive is optional. If present, and the authenticating user has - sufficient privilege, and the server supports it, then after - authentication the server will use this identity for making all - accesses and access checks. If the client specifies it, and the - server does not support it, then the response-value will be - incorrect, and authentication will fail. - -The size of a digest-response MUST be less than 4096 bytes. - - -2.1.2.1 Response-value -The definition of "response-value" above indicates the encoding for its -value -- 32 lower case hex characters. The following definitions show -how the value is computed. - - response-value = - HEX( KD ( HEX(H(A1)), - { nonce-value, ":" nc-value, ":", - cnonce-value, ":", qop-value, ":", HEX(H(A2)) })) - -If authzid is specified, then A1 is - - - A1 = { H( { username-value, ":", realm-value, ":", passwd } ), - ":", nonce-value, ":", cnonce-value, ":", authzid-value } - -If authzid is not specified, then A1 is - - - A1 = { H( { username-value, ":", realm-value, ":", passwd } ), - ":", nonce-value, ":", cnonce-value } - -where - - passwd = *OCTET - -The "username-value", "realm-value" and "passwd" are encoded according -to the value of the "charset" directive. If "charset=UTF-8" is present, -and all the characters of either "username-value" or "passwd" are in the -ISO 8859-1 character set, then it must be converted to ISO 8859-1 before -being hashed. This is so that authentication databases that store the -hashed username, realm and password (which is common) can be shared -compatibly with HTTP, which specifies ISO 8859-1. A sample -implementation of this conversion is in section 8. - -If the "qop" directive's value is "auth", then A2 is: - - - - -Leach, Newman Standards Track [Page 11] - - - Digest SASL Mechanism September, 1999 - - - - - A2 = { "AUTHENTICATE:", digest-uri-value } - -If the "qop" value is "auth-int" or "auth-conf" then A2 is: - - A2 = { "AUTHENTICATE:", digest-uri-value, - ":00000000000000000000000000000000" } - -Note that "AUTHENTICATE:" must be in upper case, and the second string -constant is a string with a colon followed by 32 zeros. - -These apparently strange values of A2 are for compatibility with HTTP; -they were arrived at by setting "Method" to "AUTHENTICATE" and the hash -of the entity body to zero in the HTTP digest calculation of A2. - -Also, in the HTTP usage of Digest, several directives in the "digest- -challenge" sent by the server have to be returned by the client in the -"digest-response". These are: - - opaque - algorithm - -These directives are not needed when Digest is used as a SASL mechanism -(i.e., MUST NOT be sent, and MUST be ignored if received). - -2.1.3Step Three - -The server receives and validates the "digest-response". The server -checks that the nonce-count is "00000001". If it supports subsequent -authentication (see section 2.2), it saves the value of the nonce and -the nonce-count. It sends a message formatted as follows: - - response-auth = "rspauth" "=" response-value - -where response-value is calculated as above, using the values sent in -step two, except that if qop is "auth", then A2 is - - A2 = { ":", digest-uri-value } - -And if qop is "auth-int" or "auth-conf" then A2 is - - A2 = { ":", digest-uri-value, ":00000000000000000000000000000000" } - -Compared to its use in HTTP, the following Digest directives in the -"digest-response" are unused: - - - - - - - - - -Leach, Newman Standards Track [Page 12] - - - Digest SASL Mechanism September, 1999 - - - - - nextnonce - qop - cnonce - nonce-count - -2.2 Subsequent Authentication - -If the client has previously authenticated to the server, and remembers -the values of username, realm, nonce, nonce-count, cnonce, and qop that -it used in that authentication, and the SASL profile for a protocol -permits an initial client response, then it MAY perform "subsequent -authentication", as defined in this section. - -2.2.1Step one - -The client uses the values from the previous authentication and sends an -initial response with a string formatted and computed according to the -rules for a "digest-response", as defined above, but with a nonce-count -one greater than used in the last "digest-response". - -2.2.2Step Two - -The server receives the "digest-response". If the server does not -support subsequent authentication, then it sends a "digest-challenge", -and authentication proceeds as in initial authentication. If the server -has no saved nonce and nonce-count from a previous authentication, then -it sends a "digest-challenge", and authentication proceeds as in initial -authentication. Otherwise, the server validates the "digest-response", -checks that the nonce-count is one greater than that used in the -previous authentication using that nonce, and saves the new value of -nonce-count. - -If the response is invalid, then the server sends a "digest-challenge", -and authentication proceeds as in initial authentication (and should be -configurable to log an authentication failure in some sort of security -audit log, since the failure may be a symptom of an attack). The nonce- -count MUST NOT be incremented in this case: to do so would allow a -denial of service attack by sending an out-of-order nonce-count. - -If the response is valid, the server MAY choose to deem that -authentication has succeeded. However, if it has been too long since the -previous authentication, or for any other reason, the server MAY send a -new "digest-challenge" with a new value for nonce. The challenge MAY -contain a "stale" directive with value "true", which says that the -client may respond to the challenge using the password it used in the -previous response; otherwise, the client must solicit the password anew -from the user. This permits the server to make sure that the user has -presented their password recently. (The directive name refers to the -previous nonce being stale, not to the last use of the password.) Except - - - - -Leach, Newman Standards Track [Page 13] - - - Digest SASL Mechanism September, 1999 - - - - -for the handling of "stale", after sending the "digest-challenge" -authentication proceeds as in the case of initial authentication. - -2.3 Integrity Protection - -If the server offered "qop=auth-int" and the client responded "qop=auth- -int", then subsequent messages, up to but not including the next -subsequent authentication, between the client and the server MUST be -integrity protected. Using as a base session key the value of H(A1) as -defined above the client and server calculate a pair of message -integrity keys as follows. - -The key for integrity protecting messages from client to server is: - -Kic = MD5({H(A1), -"Digest session key to client-to-server signing key magic constant"}) - -The key for integrity protecting messages from server to client is: - -Kis = MD5({H(A1), -"Digest session key to server-to-client signing key magic constant"}) - -where MD5 is as specified in [RFC 1321]. If message integrity is -negotiated, a MAC block for each message is appended to the message. The -MAC block is 16 bytes: the first 10 bytes of the HMAC-MD5 [RFC 2104] of -the message, a 2-byte message type number in network byte order with -value 1, and the 4-byte sequence number in network byte order. The -message type is to allow for future extensions such as rekeying. - -MAC(Ki, SeqNum, msg) = (HMAC(Ki, {SeqNum, msg})[0..9], 0x0001, SeqNum) - -where Ki is Kic for messages sent by the client and Kis for those sent -by the server. The sequence number is initialized to zero, and -incremented by one for each message sent. - -Upon receipt, MAC(Ki, SeqNum, msg) is computed and compared with the -received value; the message is discarded if they differ. - -2.4 Confidentiality Protection - -If the server sent a "cipher-opts" directive and the client responded -with a "cipher" directive, then subsequent messages between the client -and the server MUST be confidentiality protected. Using as a base -session key the value of H(A1) as defined above the client and server -calculate a pair of message integrity keys as follows. - -The key for confidentiality protecting messages from client to server -is: - -Kcc = MD5({H(A1)[0..n], - - - -Leach, Newman Standards Track [Page 14] - - - Digest SASL Mechanism September, 1999 - - - - -"Digest H(A1) to client-to-server sealing key magic constant"}) - -The key for confidentiality protecting messages from server to client -is: - -Kcs = MD5({H(A1)[0..n], -"Digest H(A1) to server-to-client sealing key magic constant"}) - -where MD5 is as specified in [RFC 1321]. For cipher "rc4-40" n is 5; for -"rc4-56" n is 7; for the rest n is 16. The key for the "rc-*" ciphers is -all 16 bytes of Kcc or Kcs; the key for "des" is the first 7 bytes; the -key for "3des" is the first 14 bytes. The IV for "des" and "3des" is the -last 8 bytes of Kcc or Kcs. - -If message confidentiality is negotiated, each message is encrypted with -the chosen cipher and a MAC block is appended to the message. - -The MAC block is a variable length padding prefix followed by 16 bytes -formatted as follows: the first 10 bytes of the HMAC-MD5 [RFC 2104] of -the message, a 2-byte message type number in network byte order with -value 1, and the 4-byte sequence number in network byte order. If the -blocksize of the chosen cipher is not 1 byte, the padding prefix is one -or more octets each containing the number of padding bytes, such that -total length of the encrypted part of the message is a multiple of the -blocksize. The padding and first 10 bytes of the MAC block are encrypted -along with the message. - -SEAL(Ki, Kc, SeqNum, msg) = - {CIPHER(Kc, {msg, pad, HMAC(Ki, {SeqNum, msg})[0..9])}), 0x0001, - SeqNum} - -where CIPHER is the chosen cipher, Ki and Kc are Kic and Kcc for -messages sent by the client and Kis and Kcs for those sent by the -server. The sequence number is initialized to zero, and incremented by -one for each message sent. - -Upon receipt, the message is decrypted, HMAC(Ki, {SeqNum, msg}) is -computed and compared with the received value; the message is discarded -if they differ. - - -3 Security Considerations - -3.1 Authentication of Clients using Digest Authentication - -Digest Authentication does not provide a strong authentication -mechanism, when compared to public key based mechanisms, for example. -However, since it prevents chosen plaintext attacks, it is stronger than -(e.g.) CRAM-MD5, which has been proposed for use with LDAP [10], POP and -IMAP (see RFC 2195 [9]). It is intended to replace the much weaker and - - - -Leach, Newman Standards Track [Page 15] - - - Digest SASL Mechanism September, 1999 - - - - -even more dangerous use of plaintext passwords; however, since it is -still a password based mechanism it avoids some of the potential -deployabilty issues with public-key, OTP or similar mechanisms. - -Digest Authentication offers no confidentiality protection beyond -protecting the actual password. All of the rest of the challenge -and response are available to an eavesdropper, including the -user's name and authentication realm. - -3.2 Comparison of Digest with Plaintext Passwords - -The greatest threat to the type of transactions for which these -protocols are used is network snooping. This kind of transaction -might involve, for example, online access to a mail service whose -use is restricted to paying subscribers. With plaintext password -authentication an eavesdropper can obtain the password of the -user. This not only permits him to access anything in the -database, but, often worse, will permit access to anything else -the user protects with the same password. - -3.3 Replay Attacks - -Replay attacks are defeated if the client or the server chooses a -fresh nonce for each authentication, as this specification -requires. - -3.4 Online dictionary attacks - -If the attacker can eavesdrop, then it can test any overheard -nonce/response pairs against a (potentially very large) list of common -words. Such a list is usually much smaller than the total number of -possible passwords. The cost of computing the response for each password -on the list is paid once for each challenge. - -The server can mitigate this attack by not allowing users to select -passwords that are in a dictionary. - -3.5 Offline dictionary attacks - -If the attacker can choose the challenge, then it can precompute the -possible responses to that challenge for a list of common words. Such a -list is usually much smaller than the total number of possible -passwords. The cost of computing the response for each password on the -list is paid just once. - -Offline dictionary attacks are defeated if the client chooses a fresh -nonce for each authentication, as this specification requires. - - - - - - -Leach, Newman Standards Track [Page 16] - - - Digest SASL Mechanism September, 1999 - - - - -3.6 Man in the Middle - -Digest authentication is vulnerable to "man in the middle" (MITM) -attacks. Clearly, a MITM would present all the problems of -eavesdropping. But it also offers some additional opportunities to the -attacker. - -A possible man-in-the-middle attack would be to substitute a weaker qop -scheme for the one(s) sent by the server; the server will not be able to -detect this attack. For this reason, the client should always use the -strongest scheme that it understands from the choices offered, and -should never choose a scheme that does not meet its minimum -requirements. - -3.7 Chosen plaintext attacks - -A chosen plaintext attack is where a MITM or a malicious server can -arbitrarily choose the challenge that the client will use to compute the -response. The ability to choose the challenge is known to make -cryptanalysis much easier [8]. - -However, Digest does not permit the attack to choose the challenge as -long as the client chooses a fresh nonce for each authentication, as -this specification requires. - -3.8 Spoofing by Counterfeit Servers - -If a user can be led to believe that she is connecting to a host -containing information protected by a password she knows, when in fact -she is connecting to a hostile server, then the hostile server can -obtain challenge/response pairs where it was able to partly choose the -challenge. There is no known way that this can be exploited. - -3.9 Storing passwords - -Digest authentication requires that the authenticating agent (usually -the server) store some data derived from the user's name and password in -a "password file" associated with a given realm. Normally this might -contain pairs consisting of username and H({ username-value, ":", realm- -value, ":", passwd }), which is adequate to compute H(A1) as described -above without directly exposing the user's password. - -The security implications of this are that if this password file is -compromised, then an attacker gains immediate access to documents on the -server using this realm. Unlike, say a standard UNIX password file, this -information need not be decrypted in order to access documents in the -server realm associated with this file. On the other hand, decryption, -or more likely a brute force attack, would be necessary to obtain the -user's password. This is the reason that the realm is part of the -digested data stored in the password file. It means that if one Digest - - - -Leach, Newman Standards Track [Page 17] - - - Digest SASL Mechanism September, 1999 - - - - -authentication password file is compromised, it does not automatically -compromise others with the same username and password (though it does -expose them to brute force attack). - -There are two important security consequences of this. First the -password file must be protected as if it contained plaintext passwords, -because for the purpose of accessing documents in its realm, it -effectively does. - -A second consequence of this is that the realm string should be unique -among all realms that any single user is likely to use. In particular a -realm string should include the name of the host doing the -authentication. - -3.10 Multiple realms - -Use of multiple realms may mean both that compromise of a the security -database for a single realm does not compromise all security, and that -there are more things to protect in order to keep the whole system -secure. - -3.11 Summary - -By modern cryptographic standards Digest Authentication is weak, -compared to (say) public key based mechanisms. But for a large range of -purposes it is valuable as a replacement for plaintext passwords. Its -strength may vary depending on the implementation. - - -4 Example - -This example shows the use of the Digest SASL mechanism with the IMAP4 -AUTHENTICATE command [RFC 2060]. - -In this example, "C:" and "S:" represent a line sent by the client or -server respectively including a CRLF at the end. Linebreaks and -indentation within a "C:" or "S:" are editorial and not part of the -protocol. The password in this example was "secret". Note that the -base64 encoding of the challenges and responses is part of the IMAP4 -AUTHENTICATE command, not part of the Digest specification itself. - - - - - - - - - - - - - -Leach, Newman Standards Track [Page 18] - - - Digest SASL Mechanism September, 1999 - - - - - S: * OK elwood.innosoft.com PMDF IMAP4rev1 V6.0-9 - C: c CAPABILITY - S: * CAPABILITY IMAP4 IMAP4rev1 ACL LITERAL+ NAMESPACE QUOTA - UIDPLUS AUTH=CRAM-MD5 AUTH=DIGEST-MD5 AUTH=PLAIN - S: c OK Completed - C: a AUTHENTICATE DIGEST-MD5 - S: + cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA== - C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg= - S: + cnNwYXV0aD00YjJiYjM3ZjA0OTEwNTA1Nzc3YzJmNjM4YzkyMjcyNQ== - C: - S: a OK User logged in - --- - - The base64-decoded version of the SASL exchange is: - - S: realm="elwood.innosoft.com",nonce="OA6MG9tEQGm2hh",qop="auth", - algorithm=md5-sess,charset=utf-8 - C: charset=utf-8,username="chris",realm="elwood.innosoft.com", - nonce="OA6MG9tEQGm2hh",nc=00000001,cnonce="OA6MHXh6VqTrRk", - digest-uri="imap/elwood.innosoft.com", - response=d388dad90d4bbd760a152321f2143af7,qop=auth - S: rspauth=4b2bb37f04910505777c2f638c922725 - - The password in this example was "secret". - -This example shows the use of the Digest SASL mechanism with the ACAP, -using the same notational conventions and password as in the previous -example. Note that ACAP does not base64 encode and uses fewer round -trips that IMAP4. - - - - - - - - - - - - - - - - - - -Leach, Newman Standards Track [Page 19] - - - Digest SASL Mechanism September, 1999 - - - - - S: * ACAP (IMPLEMENTATION "Test ACAP server") (SASL "CRAM-MD5" - "DIGEST-MD5" "PLAIN") - C: a AUTHENTICATE "DIGEST-MD5" - S: + {94} - S: realm="elwood.innosoft.com",nonce="OA9BSXrbuRhWay",qop="auth", - algorithm=md5-sess,charset=utf-8 - C: {206} - C: charset=utf-8,username="chris",realm="elwood.innosoft.com", - nonce="OA9BSXrbuRhWay",nc=00000001,cnonce="OA9BSuZWMSpW8m", - digest-uri="acap/elwood.innosoft.com", - response=6084c6db3fede7352c551284490fd0fc,qop=auth - S: a OK (SASL {40} - S: rspauth=d84489141f9d86605c6a77b95cb5365a) "AUTHENTICATE - Completed" - --- - -The server uses the values of all the directives, plus knowledge of the -users password (or the hash of the user's name, server's realm and the -user's password) to verify the computations above. If they check, then -the user has authenticated. - - -5 References - -[Digest] Franks, J., et. al., "HTTP Authentication: Basic and Digest - Access Authentication", , Work in - Progress of the HTTP Working Group, August, 1998 - -[ISO-8859] ISO-8859. International Standard -- Information Processing -- - 8-bit Single-Byte Coded Graphic Character Sets -- - Part 1: Latin alphabet No. 1, ISO-8859-1:1987. - Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. - Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. - Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. - Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. - Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. - Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. - Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. - Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. - - [RFC 822] D. H. Crocker, "Standard for The Format of ARPA Internet Text - Messages," STD 11, RFC 822, UDEL, August 1982. - -[RFC 1321] R. Rivest, "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992 - - - - - - -Leach, Newman Standards Track [Page 20] - - - Digest SASL Mechanism September, 1999 - - - - -[RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part - Three: Message Header Extensions for Non-ASCII Text", RFC 2047, - University of Tennessee, November 1996. - -[RFC 2052] A. Gulbrandsen, P. Vixie, A DNS RR for specifying the - location of services (DNS SRV). October 1996. - - [RFC 2060] Crispin, "Internet Message Access Protocol - Version 4rev1", - RFC 2060, University of Washington, December 1996. - - [RFC 2104] H. Krawczyk, M. Bellare, R. Canetti, "HMAC: Keyed-Hashing - for Message Authentication", RFC 2104, 02/05/1997 - -[RFC2195] Klensin, J., et. al., "IMAP/POP AUTHorize Extension for Simple - Challenge/Response", RFC 2195, September, 1997. - -[RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels," RFC 2119, Harvard University, March 1997. - -[USASCII] US-ASCII. Coded Character Set - 7-Bit American Standard Code - for Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. - - -6 Authors' Addresses - -Paul Leach -Microsoft -1 Microsoft Way -Redmond, WA 98052 -paulle@microsoft.com - -Chris Newman -Innosoft International, Inc. -1050 Lakes Drive -West Covina, CA 91790 USA -chris.newman@innosoft.com - - -7 ABNF - -What follows is the definition of the notation as is used in the -HTTP/1.1 specification (RFC 2616) and the HTTP authentication -specification (RFC 2617); it is reproduced here for ease of reference. -Since it is intended that a single Digest implementation can support -both HTTP and SASL-based protocols, the same notation is used in both to -facilitate comparison and prevention of unwanted differences. Since it -is cut-and-paste from the HTTP specifications, not all productions may - - - - -Leach, Newman Standards Track [Page 21] - - - Digest SASL Mechanism September, 1999 - - - - -be used in this specification. It is also not quite legal ABNF; again, -the errors were copied from the HTTP specifications. - -7.1 Augmented BNF - -All of the mechanisms specified in this document are described in both -prose and an augmented Backus-Naur Form (BNF) similar to that used by -RFC 822 [RFC 822]. Implementers will need to be familiar with the -notation in order to understand this specification. - -The augmented BNF includes the following constructs: - -name = definition - The name of a rule is simply the name itself (without any enclosing - "<" and ">") and is separated from its definition by the equal "=" - character. White space is only significant in that indentation of - continuation lines is used to indicate a rule definition that spans - more than one line. Certain basic rules are in uppercase, such as SP, - LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used within - definitions whenever their presence will facilitate discerning the - use of rule names. - -"literal" - Quotation marks surround literal text. Unless stated otherwise, the - text is case-insensitive. - -rule1 | rule2 - Elements separated by a bar ("|") are alternatives, e.g., "yes | no" - will accept yes or no. - -(rule1 rule2) - Elements enclosed in parentheses are treated as a single element. - Thus, "(elem (foo | bar) elem)" allows the token sequences - "elem foo elem" and "elem bar elem". - -*rule - The character "*" preceding an element indicates repetition. The full - form is "*element" indicating at least and at most - occurrences of element. Default values are 0 and infinity so that - "*(element)" allows any number, including zero; "1*element" requires - at least one; and "1*2element" allows one or two. - -[rule] - Square brackets enclose optional elements; "[foo bar]" is equivalent - to "*1(foo bar)". - -N rule - Specific repetition: "(element)" is equivalent to - - - -Leach, Newman Standards Track [Page 22] - - - Digest SASL Mechanism September, 1999 - - - - - "*(element)"; that is, exactly occurrences of (element). - Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three - alphabetic characters. - -#rule - A construct "#" is defined, similar to "*", for defining lists of - elements. The full form is "#element" indicating at least - and at most elements, each separated by one or more commas (",") - and OPTIONAL linear white space (LWS). This makes the usual form of - lists very easy; a rule such as - ( *LWS element *( *LWS "," *LWS element )) - can be shown as - 1#element - Wherever this construct is used, null elements are allowed, but do - not contribute to the count of elements present. That is, "(element), - , (element) " is permitted, but counts as only two elements. - Therefore, where at least one element is required, at least one non- - null element MUST be present. Default values are 0 and infinity so - that "#element" allows any number, including zero; "1#element" - requires at least one; and "1#2element" allows one or two. - -; comment - A semi-colon, set off some distance to the right of rule text, starts - a comment that continues to the end of line. This is a simple way of - including useful notes in parallel with the specifications. - - - implied *LWS - The grammar described by this specification is word-based. Except - where noted otherwise, linear white space (LWS) can be included - between any two adjacent words (token or quoted-string), and between - adjacent words and separators, without changing the interpretation of - a field. At least one delimiter (LWS and/or separators) MUST exist - between any two tokens (for the definition of "token" below), since - they would otherwise be interpreted as a single token. - - -7.2 Basic Rules - -The following rules are used throughout this specification to describe -basic parsing constructs. The US-ASCII coded character set is defined by -ANSI X3.4-1986 [USASCII]. - - OCTET = - CHAR = - UPALPHA = - LOALPHA = - ALPHA = UPALPHA | LOALPHA - DIGIT = - - - -Leach, Newman Standards Track [Page 23] - - - Digest SASL Mechanism September, 1999 - - - - - CTL = - CR = - LF = - SP = - HT = - <"> = - CRLF = CR LF - -All linear white space, including folding, has the same semantics as SP. -A recipient MAY replace any linear white space with a single SP before -interpreting the field value or forwarding the message downstream. - - LWS = [CRLF] 1*( SP | HT ) - -The TEXT rule is only used for descriptive field contents and values -that are not intended to be interpreted by the message parser. Words of -*TEXT MAY contain characters from character sets other than ISO-8859-1 -[ISO 8859] only when encoded according to the rules of RFC 2047 [RFC -2047]. - - TEXT = - -A CRLF is allowed in the definition of TEXT only as part of a header -field continuation. It is expected that the folding LWS will be replaced -with a single SP before interpretation of the TEXT value. - -Hexadecimal numeric characters are used in several protocol elements. - - HEX = "A" | "B" | "C" | "D" | "E" | "F" - | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT - -Many HTTP/1.1 header field values consist of words separated by LWS or -special characters. These special characters MUST be in a quoted string -to be used within a parameter value. - - token = 1* - separators = "(" | ")" | "<" | ">" | "@" - | "," | ";" | ":" | "\" | <"> - | "/" | "[" | "]" | "?" | "=" - | "{" | "}" | SP | HT - -A string of text is parsed as a single word if it is quoted using -double-quote marks. - - quoted-string = ( <"> qdstr-val <"> ) - qdstr-val = *( qdtext | quoted-pair ) - qdtext = > - - - - -Leach, Newman Standards Track [Page 24] - - - Digest SASL Mechanism September, 1999 - - - - -Note that LWS is NOT implicit between the double-quote marks (<">) -surrounding a qdstr-val and the qdstr-val; any LWS will be considered -part of the qdstr-val. This is also the case for quotation marks -surrounding any other construct. - - The backslash character ("\") MAY be used as a single-character quoting -mechanism only within qdstr-val and comment constructs. - - quoted-pair = "\" CHAR - -The value of this construct is CHAR. Note that an effect of this rule is -that backslash must be quoted. - - -8 Sample Code - -The sample implementation in [Digest] also applies to DIGEST-MD5. - -The following code implements the conversion from UTF-8 to 8859-1 if -necessary. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Leach, Newman Standards Track [Page 25] - - - Digest SASL Mechanism September, 1999 - - - - - /* if the string is entirely in the 8859-1 subset of UTF-8, then - * translate to 8859-1 prior to MD5 - */ - void MD5_UTF8_8859_1(MD5_CTX *ctx, const unsigned char *base, - int len) - { - const unsigned char *scan, *end; - unsigned char cbuf; - - end = base + len; - for (scan = base; scan < end; ++scan) { - if (*scan > 0xC3) break; /* abort if outside 8859-1 */ - if (*scan >= 0xC0 && *scan <= 0xC3) { - if (++scan == end || *scan < 0x80 || *scan > 0xBF) - break; - } - } - /* if we found a character outside 8859-1, don't alter string - */ - if (scan < end) { - MD5Update(ctx, base, len); - return; - } - - /* convert to 8859-1 prior to applying hash - */ - do { - for (scan = base; scan < end && *scan < 0xC0; ++scan) - ; - if (scan != base) MD5Update(ctx, base, scan - base); - if (scan + 1 >= end) break; - cbuf = ((scan[0] & 0x3) << 6) | (scan[1] & 0x3f); - MD5Update(ctx, &cbuf, 1); - base = scan + 2; - } while (base < end); - } - - -9 Full Copyright Statement - -Copyright (C) The Internet Society (1998). All Rights Reserved. - -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 the Internet Society or other Internet organizations, - - - -Leach, Newman Standards Track [Page 26] - - - Digest SASL Mechanism September, 1999 - - - - -except as needed for the purpose of developing Internet standards in -which case the procedures for copyrights defined in the Internet -Standards process must be followed, or as required to translate it into -languages other than English. - -The limited permissions granted above are perpetual and will not be -revoked by the Internet Society or its successors or assigns. - -This document and the information contained herein is provided on an "AS -IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK -FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT -LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT -INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR -FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Leach, Newman Standards Track [Page 27] \ No newline at end of file diff --git a/doc/rfc/rfc2829.txt b/doc/rfc/rfc2829.txt new file mode 100644 index 0000000000..343e153c8e --- /dev/null +++ b/doc/rfc/rfc2829.txt @@ -0,0 +1,899 @@ + + + + + + +Network Working Group M. Wahl +Request for Comments: 2829 Sun Microsystems, Inc. +Category: Standards Track H. Alvestrand + EDB Maxware + J. Hodges + Oblix, Inc. + R. Morgan + University of Washington + May 2000 + + + Authentication Methods for LDAP + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + This document specifies particular combinations of security + mechanisms which are required and recommended in LDAP [1] + implementations. + +1. Introduction + + LDAP version 3 is a powerful access protocol for directories. + + It offers means of searching, fetching and manipulating directory + content, and ways to access a rich set of security functions. + + In order to function for the best of the Internet, it is vital that + these security functions be interoperable; therefore there has to be + a minimum subset of security functions that is common to all + implementations that claim LDAPv3 conformance. + + Basic threats to an LDAP directory service include: + + (1) Unauthorized access to data via data-fetching operations, + + + + + +Wahl, et al. Standards Track [Page 1] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + (2) Unauthorized access to reusable client authentication + information by monitoring others' access, + + (3) Unauthorized access to data by monitoring others' access, + + (4) Unauthorized modification of data, + + (5) Unauthorized modification of configuration, + + (6) Unauthorized or excessive use of resources (denial of + service), and + + (7) Spoofing of directory: Tricking a client into believing that + information came from the directory when in fact it did not, + either by modifying data in transit or misdirecting the + client's connection. + + Threats (1), (4), (5) and (6) are due to hostile clients. Threats + (2), (3) and (7) are due to hostile agents on the path between client + and server, or posing as a server. + + The LDAP protocol suite can be protected with the following security + mechanisms: + + (1) Client authentication by means of the SASL [2] mechanism + set, possibly backed by the TLS credentials exchange + mechanism, + + (2) Client authorization by means of access control based on the + requestor's authenticated identity, + + (3) Data integrity protection by means of the TLS protocol or + data-integrity SASL mechanisms, + + (4) Protection against snooping by means of the TLS protocol or + data-encrypting SASL mechanisms, + + (5) Resource limitation by means of administrative limits on + service controls, and + + (6) Server authentication by means of the TLS protocol or SASL + mechanism. + + At the moment, imposition of access controls is done by means outside + the scope of the LDAP protocol. + + In this document, the term "user" represents any application which is + an LDAP client using the directory to retrieve or store information. + + + +Wahl, et al. Standards Track [Page 2] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [3]. + +2. Example deployment scenarios + + The following scenarios are typical for LDAP directories on the + Internet, and have different security requirements. (In the + following, "sensitive" means data that will cause real damage to the + owner if revealed; there may be data that is protected but not + sensitive). This is not intended to be a comprehensive list, other + scenarios are possible, especially on physically protected networks. + + (1) A read-only directory, containing no sensitive data, + accessible to "anyone", and TCP connection hijacking or IP + spoofing is not a problem. This directory requires no + security functions except administrative service limits. + + (2) A read-only directory containing no sensitive data; read + access is granted based on identity. TCP connection + hijacking is not currently a problem. This scenario requires + a secure authentication function. + + (3) A read-only directory containing no sensitive data; and the + client needs to ensure that the directory data is + authenticated by the server and not modified while being + returned from the server. + + (4) A read-write directory, containing no sensitive data; read + access is available to "anyone", update access to properly + authorized persons. TCP connection hijacking is not + currently a problem. This scenario requires a secure + authentication function. + + (5) A directory containing sensitive data. This scenario + requires session confidentiality protection AND secure + authentication. + +3. Authentication and Authorization: Definitions and Concepts + + This section defines basic terms, concepts, and interrelationships + regarding authentication, authorization, credentials, and identity. + These concepts are used in describing how various security approaches + are utilized in client authentication and authorization. + + + + + + + +Wahl, et al. Standards Track [Page 3] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +3.1. Access Control Policy + + An access control policy is a set of rules defining the protection of + resources, generally in terms of the capabilities of persons or other + entities accessing those resources. A common expression of an access + control policy is an access control list. Security objects and + mechanisms, such as those described here, enable the expression of + access control policies and their enforcement. Access control + policies are typically expressed in terms of access control + attributes as described below. + +3.2. Access Control Factors + + A request, when it is being processed by a server, may be associated + with a wide variety of security-related factors (section 4.2 of [1]). + The server uses these factors to determine whether and how to process + the request. These are called access control factors (ACFs). They + might include source IP address, encryption strength, the type of + operation being requested, time of day, etc. Some factors may be + specific to the request itself, others may be associated with the + connection via which the request is transmitted, others (e.g. time of + day) may be "environmental". + + Access control policies are expressed in terms of access control + factors. E.g., a request having ACFs i,j,k can perform operation Y + on resource Z. The set of ACFs that a server makes available for such + expressions is implementation-specific. + +3.3. Authentication, Credentials, Identity + + Authentication credentials are the evidence supplied by one party to + another, asserting the identity of the supplying party (e.g. a user) + who is attempting to establish an association with the other party + (typically a server). Authentication is the process of generating, + transmitting, and verifying these credentials and thus the identity + they assert. An authentication identity is the name presented in a + credential. + + There are many forms of authentication credentials -- the form used + depends upon the particular authentication mechanism negotiated by + the parties. For example: X.509 certificates, Kerberos tickets, + simple identity and password pairs. Note that an authentication + mechanism may constrain the form of authentication identities used + with it. + + + + + + + +Wahl, et al. Standards Track [Page 4] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +3.4. Authorization Identity + + An authorization identity is one kind of access control factor. It + is the name of the user or other entity that requests that operations + be performed. Access control policies are often expressed in terms + of authorization identities; e.g., entity X can perform operation Y + on resource Z. + + The authorization identity bound to an association is often exactly + the same as the authentication identity presented by the client, but + it may be different. SASL allows clients to specify an authorization + identity distinct from the authentication identity asserted by the + client's credentials. This permits agents such as proxy servers to + authenticate using their own credentials, yet request the access + privileges of the identity for which they are proxying [2]. Also, + the form of authentication identity supplied by a service like TLS + may not correspond to the authorization identities used to express a + server's access control policy, requiring a server-specific mapping + to be done. The method by which a server composes and validates an + authorization identity from the authentication credentials supplied + by a client is implementation-specific. + +4. Required security mechanisms + + It is clear that allowing any implementation, faced with the above + requirements, to pick and choose among the possible alternatives is + not a strategy that is likely to lead to interoperability. In the + absence of mandates, clients will be written that do not support any + security function supported by the server, or worse, support only + mechanisms like cleartext passwords that provide clearly inadequate + security. + + Active intermediary attacks are the most difficult for an attacker to + perform, and for an implementation to protect against. Methods that + protect only against hostile client and passive eavesdropping attacks + are useful in situations where the cost of protection against active + intermediary attacks is not justified based on the perceived risk of + active intermediary attacks. + + Given the presence of the Directory, there is a strong desire to see + mechanisms where identities take the form of a Distinguished Name and + authentication data can be stored in the directory; this means that + either this data is useless for faking authentication (like the Unix + "/etc/passwd" file format used to be), or its content is never passed + across the wire unprotected - that is, it's either updated outside + the protocol or it is only updated in sessions well protected against + snooping. It is also desirable to allow authentication methods to + + + + +Wahl, et al. Standards Track [Page 5] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + carry authorization identities based on existing forms of user + identities for backwards compatibility with non-LDAP-based + authentication services. + + Therefore, the following implementation conformance requirements are + in place: + + (1) For a read-only, public directory, anonymous authentication, + described in section 5, can be used. + + (2) Implementations providing password-based authenticated + access MUST support authentication using the DIGEST-MD5 SASL + mechanism [4], as described in section 6.1. This provides + client authentication with protection against passive + eavesdropping attacks, but does not provide protection + against active intermediary attacks. + + (3) For a directory needing session protection and + authentication, the Start TLS extended operation [5], and + either the simple authentication choice or the SASL EXTERNAL + mechanism, are to be used together. Implementations SHOULD + support authentication with a password as described in + section 6.2, and SHOULD support authentication with a + certificate as described in section 7.1. Together, these + can provide integrity and disclosure protection of + transmitted data, and authentication of client and server, + including protection against active intermediary attacks. + + If TLS is negotiated, the client MUST discard all information about + the server fetched prior to the TLS negotiation. In particular, the + value of supportedSASLMechanisms MAY be different after TLS has been + negotiated (specifically, the EXTERNAL mechanism or the proposed + PLAIN mechanism are likely to only be listed after a TLS negotiation + has been performed). + + If a SASL security layer is negotiated, the client MUST discard all + information about the server fetched prior to SASL. In particular, + if the client is configured to support multiple SASL mechanisms, it + SHOULD fetch supportedSASLMechanisms both before and after the SASL + security layer is negotiated and verify that the value has not + changed after the SASL security layer was negotiated. This detects + active attacks which remove supported SASL mechanisms from the + supportedSASLMechanisms list, and allows the client to ensure that it + is using the best mechanism supported by both client and server + (additionally, this is a SHOULD to allow for environments where the + supported SASL mechanisms list is provided to the client through a + different trusted source, e.g. as part of a digitally signed object). + + + + +Wahl, et al. Standards Track [Page 6] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +5. Anonymous authentication + + Directory operations which modify entries or access protected + attributes or entries generally require client authentication. + Clients which do not intend to perform any of these operations + typically use anonymous authentication. + + LDAP implementations MUST support anonymous authentication, as + defined in section 5.1. + + LDAP implementations MAY support anonymous authentication with TLS, + as defined in section 5.2. + + While there MAY be access control restrictions to prevent access to + directory entries, an LDAP server SHOULD allow an anonymously-bound + client to retrieve the supportedSASLMechanisms attribute of the root + DSE. + + An LDAP server MAY use other information about the client provided by + the lower layers or external means to grant or deny access even to + anonymously authenticated clients. + +5.1. Anonymous authentication procedure + + An LDAP client which has not successfully completed a bind operation + on a connection is anonymously authenticated. + + An LDAP client MAY also specify anonymous authentication in a bind + request by using a zero-length OCTET STRING with the simple + authentication choice. + +5.2. Anonymous authentication and TLS + + An LDAP client MAY use the Start TLS operation [5] to negotiate the + use of TLS security [6]. If the client has not bound beforehand, + then until the client uses the EXTERNAL SASL mechanism to negotiate + the recognition of the client's certificate, the client is + anonymously authenticated. + + Recommendations on TLS ciphersuites are given in section 10. + + An LDAP server which requests that clients provide their certificate + during TLS negotiation MAY use a local security policy to determine + whether to successfully complete TLS negotiation if the client did + not present a certificate which could be validated. + + + + + + +Wahl, et al. Standards Track [Page 7] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +6. Password-based authentication + + LDAP implementations MUST support authentication with a password + using the DIGEST-MD5 SASL mechanism for password protection, as + defined in section 6.1. + + LDAP implementations SHOULD support authentication with the "simple" + password choice when the connection is protected against + eavesdropping using TLS, as defined in section 6.2. + +6.1. Digest authentication + + An LDAP client MAY determine whether the server supports this + mechanism by performing a search request on the root DSE, requesting + the supportedSASLMechanisms attribute, and checking whether the + string "DIGEST-MD5" is present as a value of this attribute. + + In the first stage of authentication, when the client is performing + an "initial authentication" as defined in section 2.1 of [4], the + client sends a bind request in which the version number is 3, the + authentication choice is sasl, the sasl mechanism name is "DIGEST- + MD5", and the credentials are absent. The client then waits for a + response from the server to this request. + + The server will respond with a bind response in which the resultCode + is saslBindInProgress, and the serverSaslCreds field is present. The + contents of this field is a string defined by "digest-challenge" in + section 2.1.1 of [4]. The server SHOULD include a realm indication + and MUST indicate support for UTF-8. + + The client will send a bind request with a distinct message id, in + which the version number is 3, the authentication choice is sasl, the + sasl mechanism name is "DIGEST-MD5", and the credentials contain the + string defined by "digest-response" in section 2.1.2 of [4]. The + serv-type is "ldap". + + The server will respond with a bind response in which the resultCode + is either success, or an error indication. If the authentication is + successful and the server does not support subsequent authentication, + then the credentials field is absent. If the authentication is + successful and the server supports subsequent authentication, then + the credentials field contains the string defined by "response-auth" + in section 2.1.3 of [4]. Support for subsequent authentication is + OPTIONAL in clients and servers. + + + + + + + +Wahl, et al. Standards Track [Page 8] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +6.2. "simple" authentication choice under TLS encryption + + A user who has a directory entry containing a userPassword attribute + MAY authenticate to the directory by performing a simple password + bind sequence following the negotiation of a TLS ciphersuite + providing connection confidentiality [6]. + + The client will use the Start TLS operation [5] to negotiate the use + of TLS security [6] on the connection to the LDAP server. The client + need not have bound to the directory beforehand. + + For this authentication procedure to be successful, the client and + server MUST negotiate a ciphersuite which contains a bulk encryption + algorithm of appropriate strength. Recommendations on cipher suites + are given in section 10. + + Following the successful completion of TLS negotiation, the client + MUST send an LDAP bind request with the version number of 3, the name + field containing the name of the user's entry, and the "simple" + authentication choice, containing a password. + + The server will, for each value of the userPassword attribute in the + named user's entry, compare these for case-sensitive equality with + the client's presented password. If there is a match, then the + server will respond with resultCode success, otherwise the server + will respond with resultCode invalidCredentials. + +6.3. Other authentication choices with TLS + + It is also possible, following the negotiation of TLS, to perform a + SASL authentication which does not involve the exchange of plaintext + reusable passwords. In this case the client and server need not + negotiate a ciphersuite which provides confidentiality if the only + service required is data integrity. + +7. Certificate-based authentication + + LDAP implementations SHOULD support authentication via a client + certificate in TLS, as defined in section 7.1. + +7.1. Certificate-based authentication with TLS + + A user who has a public/private key pair in which the public key has + been signed by a Certification Authority may use this key pair to + authenticate to the directory server if the user's certificate is + requested by the server. The user's certificate subject field SHOULD + be the name of the user's directory entry, and the Certification + Authority must be sufficiently trusted by the directory server to + + + +Wahl, et al. Standards Track [Page 9] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + have issued the certificate in order that the server can process the + certificate. The means by which servers validate certificate paths + is outside the scope of this document. + + A server MAY support mappings for certificates in which the subject + field name is different from the name of the user's directory entry. + A server which supports mappings of names MUST be capable of being + configured to support certificates for which no mapping is required. + + The client will use the Start TLS operation [5] to negotiate the use + of TLS security [6] on the connection to the LDAP server. The client + need not have bound to the directory beforehand. + + In the TLS negotiation, the server MUST request a certificate. The + client will provide its certificate to the server, and MUST perform a + private key-based encryption, proving it has the private key + associated with the certificate. + + As deployments will require protection of sensitive data in transit, + the client and server MUST negotiate a ciphersuite which contains a + bulk encryption algorithm of appropriate strength. Recommendations + of cipher suites are given in section 10. + + The server MUST verify that the client's certificate is valid. The + server will normally check that the certificate is issued by a known + CA, and that none of the certificates on the client's certificate + chain are invalid or revoked. There are several procedures by which + the server can perform these checks. + + Following the successful completion of TLS negotiation, the client + will send an LDAP bind request with the SASL "EXTERNAL" mechanism. + +8. Other mechanisms + + The LDAP "simple" authentication choice is not suitable for + authentication on the Internet where there is no network or transport + layer confidentiality. + + As LDAP includes native anonymous and plaintext authentication + methods, the "ANONYMOUS" and "PLAIN" SASL mechanisms are not used + with LDAP. If an authorization identity of a form different from a + DN is requested by the client, a mechanism that protects the password + in transit SHOULD be used. + + The following SASL-based mechanisms are not considered in this + document: KERBEROS_V4, GSSAPI and SKEY. + + + + + +Wahl, et al. Standards Track [Page 10] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + The "EXTERNAL" SASL mechanism can be used to request the LDAP server + make use of security credentials exchanged by a lower layer. If a TLS + session has not been established between the client and server prior + to making the SASL EXTERNAL Bind request and there is no other + external source of authentication credentials (e.g. IP-level + security [8]), or if, during the process of establishing the TLS + session, the server did not request the client's authentication + credentials, the SASL EXTERNAL bind MUST fail with a result code of + inappropriateAuthentication. Any client authentication and + authorization state of the LDAP association is lost, so the LDAP + association is in an anonymous state after the failure. + +9. Authorization Identity + + The authorization identity is carried as part of the SASL credentials + field in the LDAP Bind request and response. + + When the "EXTERNAL" mechanism is being negotiated, if the credentials + field is present, it contains an authorization identity of the + authzId form described below. + + Other mechanisms define the location of the authorization identity in + the credentials field. + + The authorization identity is a string in the UTF-8 character set, + corresponding to the following ABNF [7]: + + ; Specific predefined authorization (authz) id schemes are + ; defined below -- new schemes may be defined in the future. + + authzId = dnAuthzId / uAuthzId + + ; distinguished-name-based authz id. + dnAuthzId = "dn:" dn + dn = utf8string ; with syntax defined in RFC 2253 + + ; unspecified userid, UTF-8 encoded. + uAuthzId = "u:" userid + userid = utf8string ; syntax unspecified + + A utf8string is defined to be the UTF-8 encoding of one or more ISO + 10646 characters. + + All servers which support the storage of authentication credentials, + such as passwords or certificates, in the directory MUST support the + dnAuthzId choice. + + + + + +Wahl, et al. Standards Track [Page 11] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + The uAuthzId choice allows for compatibility with client applications + which wish to authenticate to a local directory but do not know their + own Distinguished Name or have a directory entry. The format of the + string is defined as only a sequence of UTF-8 encoded ISO 10646 + characters, and further interpretation is subject to prior agreement + between the client and server. + + For example, the userid could identify a user of a specific directory + service, or be a login name or the local-part of an RFC 822 email + address. In general a uAuthzId MUST NOT be assumed to be globally + unique. + + Additional authorization identity schemes MAY be defined in future + versions of this document. + +10. TLS Ciphersuites + + The following ciphersuites defined in [6] MUST NOT be used for + confidentiality protection of passwords or data: + + TLS_NULL_WITH_NULL_NULL + TLS_RSA_WITH_NULL_MD5 + TLS_RSA_WITH_NULL_SHA + + The following ciphersuites defined in [6] can be cracked easily (less + than a week of CPU time on a standard CPU in 1997). The client and + server SHOULD carefully consider the value of the password or data + being protected before using these ciphersuites: + + TLS_RSA_EXPORT_WITH_RC4_40_MD5 + TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 + TLS_RSA_EXPORT_WITH_DES40_CBC_SHA + TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA + TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA + TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA + TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA + TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 + TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA + + The following ciphersuites are vulnerable to man-in-the-middle + attacks, and SHOULD NOT be used to protect passwords or sensitive + data, unless the network configuration is such that the danger of a + man-in-the-middle attack is tolerable: + + + + + + + + +Wahl, et al. Standards Track [Page 12] + +RFC 2829 Authentication Methods for LDAP May 2000 + + + TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 + TLS_DH_anon_WITH_RC4_128_MD5 + TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA + TLS_DH_anon_WITH_DES_CBC_SHA + TLS_DH_anon_WITH_3DES_EDE_CBC_SHA + + A client or server that supports TLS MUST support at least + TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA. + +11. SASL service name for LDAP + + For use with SASL [2], a protocol must specify a service name to be + used with various SASL mechanisms, such as GSSAPI. For LDAP, the + service name is "ldap", which has been registered with the IANA as a + GSSAPI service name. + +12. Security Considerations + + Security issues are discussed throughout this memo; the + (unsurprising) conclusion is that mandatory security is important, + and that session encryption is required when snooping is a problem. + + Servers are encouraged to prevent modifications by anonymous users. + Servers may also wish to minimize denial of service attacks by timing + out idle connections, and returning the unwillingToPerform result + code rather than performing computationally expensive operations + requested by unauthorized clients. + + A connection on which the client has not performed the Start TLS + operation or negotiated a suitable SASL mechanism for connection + integrity and encryption services is subject to man-in-the-middle + attacks to view and modify information in transit. + + Additional security considerations relating to the EXTERNAL mechanism + to negotiate TLS can be found in [2], [5] and [6]. + +13. Acknowledgements + + This document is a product of the LDAPEXT Working Group of the IETF. + The contributions of its members is greatly appreciated. + + + + + + + + + + + +Wahl, et al. Standards Track [Page 13] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +14. Bibliography + + [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [2] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC + 2222, October 1997. + + [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [4] Leach, P. and C. Newman, "Using Digest Authentication as a SASL + Mechanism", RFC 2831, May 2000. + + [5] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access + Protocol (v3): Extension for Transport Layer Security", RFC 2830, + May 2000. + + [6] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC + 2246, January 1999. + + [7] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [8] Kent, S. and R. Atkinson, "Security Architecture for the Internet + Protocol", RFC 2401, November 1998. + + + + + + + + + + + + + + + + + + + + + + + + + +Wahl, et al. Standards Track [Page 14] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +15. Authors' Addresses + + Mark Wahl + Sun Microsystems, Inc. + 8911 Capital of Texas Hwy #4140 + Austin TX 78759 + USA + + EMail: M.Wahl@innosoft.com + + + Harald Tveit Alvestrand + EDB Maxware + Pirsenteret + N-7462 Trondheim, Norway + + Phone: +47 73 54 57 97 + EMail: Harald@Alvestrand.no + + + Jeff Hodges + Oblix, Inc. + 18922 Forge Drive + Cupertino, CA 95014 + USA + + Phone: +1-408-861-6656 + EMail: JHodges@oblix.com + + + RL "Bob" Morgan + Computing and Communications + University of Washington + Seattle, WA 98105 + USA + + Phone: +1-206-221-3307 + EMail: rlmorgan@washington.edu + + + + + + + + + + + + + +Wahl, et al. Standards Track [Page 15] + +RFC 2829 Authentication Methods for LDAP May 2000 + + +16. Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + 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 the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Wahl, et al. Standards Track [Page 16] + diff --git a/doc/rfc/rfc2830.txt b/doc/rfc/rfc2830.txt new file mode 100644 index 0000000000..7801c7d5b9 --- /dev/null +++ b/doc/rfc/rfc2830.txt @@ -0,0 +1,675 @@ + + + + + + +Network Working Group J. Hodges +Request for Comments: 2830 Oblix Inc. +Category: Standards Track R. Morgan + Univ of Washington + M. Wahl + Sun Microsystems, Inc. + May 2000 + + + Lightweight Directory Access Protocol (v3): + Extension for Transport Layer Security + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + This document defines the "Start Transport Layer Security (TLS) + Operation" for LDAP [LDAPv3, TLS]. This operation provides for TLS + establishment in an LDAP association and is defined in terms of an + LDAP extended request. + +1. Conventions Used in this Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [ReqsKeywords]. + +2. The Start TLS Request + + This section describes the Start TLS extended request and extended + response themselves: how to form the request, the form of the + response, and enumerates the various result codes the client MUST be + prepared to handle. + + The section following this one then describes how to sequence an + overall Start TLS Operation. + + + + + +Hodges, et al. Standards Track [Page 1] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +2.1. Requesting TLS Establishment + + A client may perform a Start TLS operation by transmitting an LDAP + PDU containing an ExtendedRequest [LDAPv3] specifying the OID for the + Start TLS operation: + + 1.3.6.1.4.1.1466.20037 + + An LDAP ExtendedRequest is defined as follows: + + ExtendedRequest ::= [APPLICATION 23] SEQUENCE { + requestName [0] LDAPOID, + requestValue [1] OCTET STRING OPTIONAL } + + A Start TLS extended request is formed by setting the requestName + field to the OID string given above. The requestValue field is + absent. The client MUST NOT send any PDUs on this connection + following this request until it receives a Start TLS extended + response. + + When a Start TLS extended request is made, the server MUST return an + LDAP PDU containing a Start TLS extended response. An LDAP + ExtendedResponse is defined as follows: + + ExtendedResponse ::= [APPLICATION 24] SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] LDAPOID OPTIONAL, + response [11] OCTET STRING OPTIONAL } + + A Start TLS extended response MUST contain a responseName field which + MUST be set to the same string as that in the responseName field + present in the Start TLS extended request. The response field is + absent. The server MUST set the resultCode field to either success or + one of the other values outlined in section 2.3. + +2.2. "Success" Response + + If the ExtendedResponse contains a resultCode of success, this + indicates that the server is willing and able to negotiate TLS. Refer + to section 3, below, for details. + +2.3. Response other than "success" + + If the ExtendedResponse contains a resultCode other than success, + this indicates that the server is unwilling or unable to negotiate + TLS. + + + + + +Hodges, et al. Standards Track [Page 2] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + + If the Start TLS extended request was not successful, the resultCode + will be one of: + + operationsError (operations sequencing incorrect; e.g. TLS already + established) + + protocolError (TLS not supported or incorrect PDU structure) + + referral (this server doesn't do TLS, try this one) + + unavailable (e.g. some major problem with TLS, or server is + shutting down) + + The server MUST return operationsError if the client violates any of + the Start TLS extended operation sequencing requirements described in + section 3, below. + + If the server does not support TLS (whether by design or by current + configuration), it MUST set the resultCode to protocolError (see + section 4.1.1 of [LDAPv3]), or to referral. The server MUST include + an actual referral value in the LDAP Result if it returns a + resultCode of referral. The client's current session is unaffected if + the server does not support TLS. The client MAY proceed with any LDAP + operation, or it MAY close the connection. + + The server MUST return unavailable if it supports TLS but cannot + establish a TLS connection for some reason, e.g. the certificate + server not responding, it cannot contact its TLS implementation, or + if the server is in process of shutting down. The client MAY retry + the StartTLS operation, or it MAY proceed with any other LDAP + operation, or it MAY close the connection. + +3. Sequencing of the Start TLS Operation + + This section describes the overall procedures clients and servers + MUST follow for TLS establishment. These procedures take into + consideration various aspects of the overall security of the LDAP + association including discovery of resultant security level and + assertion of the client's authorization identity. + + Note that the precise effects, on a client's authorization identity, + of establishing TLS on an LDAP association are described in detail in + section 5. + + + + + + + + +Hodges, et al. Standards Track [Page 3] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +3.1. Requesting to Start TLS on an LDAP Association + + The client MAY send the Start TLS extended request at any time after + establishing an LDAP association, except that in the following cases + the client MUST NOT send a Start TLS extended request: + + - if TLS is currently established on the connection, or + - during a multi-stage SASL negotiation, or + - if there are any LDAP operations outstanding on the connection. + + The result of violating any of these requirements is a resultCode of + operationsError, as described above in section 2.3. + + The client MAY have already performed a Bind operation when it sends + a Start TLS request, or the client might have not yet bound. + + If the client did not establish a TLS connection before sending any + other requests, and the server requires the client to establish a TLS + connection before performing a particular request, the server MUST + reject that request with a confidentialityRequired or + strongAuthRequired result. The client MAY send a Start TLS extended + request, or it MAY choose to close the connection. + +3.2. Starting TLS + + The server will return an extended response with the resultCode of + success if it is willing and able to negotiate TLS. It will return + other resultCodes, documented above, if it is unable. + + In the successful case, the client, which has ceased to transfer LDAP + requests on the connection, MUST either begin a TLS negotiation or + close the connection. The client will send PDUs in the TLS Record + Protocol directly over the underlying transport connection to the + server to initiate TLS negotiation [TLS]. + +3.3. TLS Version Negotiation + + Negotiating the version of TLS or SSL to be used is a part of the TLS + Handshake Protocol, as documented in [TLS]. Please refer to that + document for details. + +3.4. Discovery of Resultant Security Level + + After a TLS connection is established on an LDAP association, both + parties MUST individually decide whether or not to continue based on + the privacy level achieved. Ascertaining the TLS connection's privacy + level is implementation dependent, and accomplished by communicating + with one's respective local TLS implementation. + + + +Hodges, et al. Standards Track [Page 4] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + + If the client or server decides that the level of authentication or + privacy is not high enough for it to continue, it SHOULD gracefully + close the TLS connection immediately after the TLS negotiation has + completed (see sections 4.1 and 5.2, below). + + The client MAY attempt to Start TLS again, or MAY send an unbind + request, or send any other LDAP request. + +3.5. Assertion of Client's Authorization Identity + + The client MAY, upon receipt of a Start TLS extended response + indicating success, assert that a specific authorization identity be + utilized in determining the client's authorization status. The client + accomplishes this via an LDAP Bind request specifying a SASL + mechanism of "EXTERNAL" [SASL]. See section 5.1.2, below. + +3.6. Server Identity Check + + The client MUST check its understanding of the server's hostname + against the server's identity as presented in the server's + Certificate message, in order to prevent man-in-the-middle attacks. + + Matching is performed according to these rules: + + - The client MUST use the server hostname it used to open the LDAP + connection as the value to compare against the server name as + expressed in the server's certificate. The client MUST NOT use the + server's canonical DNS name or any other derived form of name. + + - If a subjectAltName extension of type dNSName is present in the + certificate, it SHOULD be used as the source of the server's + identity. + + - Matching is case-insensitive. + + - The "*" wildcard character is allowed. If present, it applies only + to the left-most name component. + + E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not + bar.com. If more than one identity of a given type is present in the + certificate (e.g. more than one dNSName name), a match in any one of + the set is considered acceptable. + + If the hostname does not match the dNSName-based identity in the + certificate per the above check, user-oriented clients SHOULD either + notify the user (clients MAY give the user the opportunity to + + + + + +Hodges, et al. Standards Track [Page 5] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + + continue with the connection in any case) or terminate the connection + and indicate that the server's identity is suspect. Automated clients + SHOULD close the connection, returning and/or logging an error + indicating that the server's identity is suspect. + + Beyond the server identity checks described in this section, clients + SHOULD be prepared to do further checking to ensure that the server + is authorized to provide the service it is observed to provide. The + client MAY need to make use of local policy information. + +3.7. Refresh of Server Capabilities Information + + The client MUST refresh any cached server capabilities information + (e.g. from the server's root DSE; see section 3.4 of [LDAPv3]) upon + TLS session establishment. This is necessary to protect against + active-intermediary attacks which may have altered any server + capabilities information retrieved prior to TLS establishment. The + server MAY advertise different capabilities after TLS establishment. + +4. Closing a TLS Connection + +4.1. Graceful Closure + + Either the client or server MAY terminate the TLS connection on an + LDAP association by sending a TLS closure alert. This will leave the + LDAP association intact. + + Before closing a TLS connection, the client MUST either wait for any + outstanding LDAP operations to complete, or explicitly abandon them + [LDAPv3]. + + After the initiator of a close has sent a closure alert, it MUST + discard any TLS messages until it has received an alert from the + other party. It will cease to send TLS Record Protocol PDUs, and + following the receipt of the alert, MAY send and receive LDAP PDUs. + + The other party, if it receives a closure alert, MUST immediately + transmit a TLS closure alert. It will subsequently cease to send TLS + Record Protocol PDUs, and MAY send and receive LDAP PDUs. + +4.2. Abrupt Closure + + Either the client or server MAY abruptly close the entire LDAP + association and any TLS connection established on it by dropping the + underlying TCP connection. A server MAY beforehand send the client a + Notice of Disconnection [LDAPv3] in this case. + + + + + +Hodges, et al. Standards Track [Page 6] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +5. Effects of TLS on a Client's Authorization Identity + + This section describes the effects on a client's authorization + identity brought about by establishing TLS on an LDAP association. + The default effects are described first, and next the facilities for + client assertion of authorization identity are discussed including + error conditions. Lastly, the effects of closing the TLS connection + are described. + + Authorization identities and related concepts are defined in + [AuthMeth]. + +5.1. TLS Connection Establishment Effects + +5.1.1. Default Effects + + Upon establishment of the TLS connection onto the LDAP association, + any previously established authentication and authorization + identities MUST remain in force, including anonymous state. This + holds even in the case where the server requests client + authentication via TLS -- e.g. requests the client to supply its + certificate during TLS negotiation (see [TLS]). + +5.1.2. Client Assertion of Authorization Identity + + A client MAY either implicitly request that its LDAP authorization + identity be derived from its authenticated TLS credentials or it MAY + explicitly provide an authorization identity and assert that it be + used in combination with its authenticated TLS credentials. The + former is known as an implicit assertion, and the latter as an + explicit assertion. + +5.1.2.1. Implicit Assertion + + An implicit authorization identity assertion is accomplished after + TLS establishment by invoking a Bind request of the SASL form using + the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL NOT include + the optional credentials octet string (found within the + SaslCredentials sequence in the Bind Request). The server will derive + the client's authorization identity from the authentication identity + supplied in the client's TLS credentials (typically a public key + certificate) according to local policy. The underlying mechanics of + how this is accomplished are implementation specific. + + + + + + + + +Hodges, et al. Standards Track [Page 7] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +5.1.2.2. Explicit Assertion + + An explicit authorization identity assertion is accomplished after + TLS establishment by invoking a Bind request of the SASL form using + the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL include the + credentials octet string. This string MUST be constructed as + documented in section 9 of [AuthMeth]. + +5.1.2.3. Error Conditions + + For either form of assertion, the server MUST verify that the + client's authentication identity as supplied in its TLS credentials + is permitted to be mapped to the asserted authorization identity. The + server MUST reject the Bind operation with an invalidCredentials + resultCode in the Bind response if the client is not so authorized. + + Additionally, with either form of assertion, if a TLS session has not + been established between the client and server prior to making the + SASL EXTERNAL Bind request and there is no other external source of + authentication credentials (e.g. IP-level security [IPSEC]), or if, + during the process of establishing the TLS session, the server did + not request the client's authentication credentials, the SASL + EXTERNAL bind MUST fail with a result code of + inappropriateAuthentication. + + After the above Bind operation failures, any client authentication + and authorization state of the LDAP association is lost, so the LDAP + association is in an anonymous state after the failure. TLS + connection state is unaffected, though a server MAY end the TLS + connection, via a TLS close_notify message, based on the Bind failure + (as it MAY at any time). + +5.2. TLS Connection Closure Effects + + Closure of the TLS connection MUST cause the LDAP association to move + to an anonymous authentication and authorization state regardless of + the state established over TLS and regardless of the authentication + and authorization state prior to TLS connection establishment. + +6. Security Considerations + + The goals of using the TLS protocol with LDAP are to ensure + connection confidentiality and integrity, and to optionally provide + for authentication. TLS expressly provides these capabilities, as + described in [TLS]. + + + + + + +Hodges, et al. Standards Track [Page 8] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + + All security gained via use of the Start TLS operation is gained by + the use of TLS itself. The Start TLS operation, on its own, does not + provide any additional security. + + The use of TLS does not provide or ensure for confidentiality and/or + non-repudiation of the data housed by an LDAP-based directory server. + Nor does it secure the data from inspection by the server + administrators. Once established, TLS only provides for and ensures + confidentiality and integrity of the operations and data in transit + over the LDAP association, and only if the implementations on the + client and server support and negotiate it. + + The level of security provided though the use of TLS depends directly + on both the quality of the TLS implementation used and the style of + usage of that implementation. Additionally, an active-intermediary + attacker can remove the Start TLS extended operation from the + supportedExtension attribute of the root DSE. Therefore, both parties + SHOULD independently ascertain and consent to the security level + achieved once TLS is established and before beginning use of the TLS + connection. For example, the security level of the TLS connection + might have been negotiated down to plaintext. + + Clients SHOULD either warn the user when the security level achieved + does not provide confidentiality and/or integrity protection, or be + configurable to refuse to proceed without an acceptable level of + security. + + Client and server implementors SHOULD take measures to ensure proper + protection of credentials and other confidential data where such + measures are not otherwise provided by the TLS implementation. + + Server implementors SHOULD allow for server administrators to elect + whether and when connection confidentiality and/or integrity is + required, as well as elect whether and when client authentication via + TLS is required. + +7. Acknowledgements + + The authors thank Tim Howes, Paul Hoffman, John Kristian, Shirish + Rai, Jonathan Trostle, Harald Alvestrand, and Marcus Leech for their + contributions to this document. + + + + + + + + + + +Hodges, et al. Standards Track [Page 9] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +8. References + + [AuthMeth] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, + "Authentication Methods for LDAP", RFC 2829, May 2000. + + [IPSEC] Kent, S. and R. Atkinson, "Security Architecture for + the Internet Protocol", RFC 2401, November 1998. + + [LDAPv3] Wahl, M., Kille S. and T. Howes, "Lightweight + Directory Access Protocol (v3)", RFC 2251, December + 1997. + + [ReqsKeywords] Bradner, S., "Key Words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [SASL] Myers, J., "Simple Authentication and Security Layer + (SASL)", RFC 2222, October 1997. + + [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version + 1.0", RFC 2246, January 1999. + +9. Authors' Addresses + + Jeff Hodges + Oblix, Inc. + 18922 Forge Drive + Cupertino, CA 95014 + USA + + Phone: +1-408-861-6656 + EMail: JHodges@oblix.com + + RL "Bob" Morgan + Computing and Communications + University of Washington + Seattle, WA + USA + + Phone: +1-206-221-3307 + EMail: rlmorgan@washington.edu + + Mark Wahl + Sun Microsystems, Inc. + 8911 Capital of Texas Hwy #4140 + Austin TX 78759 + USA + + EMail: M.Wahl@innosoft.com + + + +Hodges, et al. Standards Track [Page 10] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +10. Intellectual Property Rights Notices + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hodges, et al. Standards Track [Page 11] + +RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + 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 the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Hodges, et al. Standards Track [Page 12] + diff --git a/doc/rfc/rfc2831.txt b/doc/rfc/rfc2831.txt new file mode 100644 index 0000000000..c1a54c4944 --- /dev/null +++ b/doc/rfc/rfc2831.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group P. Leach +Request for Comments: 2831 Microsoft +Category: Standards Track C. Newman + Innosoft + May 2000 + + + Using Digest Authentication as a SASL Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + This specification defines how HTTP Digest Authentication [Digest] + can be used as a SASL [RFC 2222] mechanism for any protocol that has + a SASL profile. It is intended both as an improvement over CRAM-MD5 + [RFC 2195] and as a convenient way to support a single authentication + mechanism for web, mail, LDAP, and other protocols. + +Table of Contents + + 1 INTRODUCTION.....................................................2 + 1.1 CONVENTIONS AND NOTATION......................................2 + 1.2 REQUIREMENTS..................................................3 + 2 AUTHENTICATION...................................................3 + 2.1 INITIAL AUTHENTICATION........................................3 + 2.1.1 Step One...................................................3 + 2.1.2 Step Two...................................................6 + 2.1.3 Step Three................................................12 + 2.2 SUBSEQUENT AUTHENTICATION....................................12 + 2.2.1 Step one..................................................13 + 2.2.2 Step Two..................................................13 + 2.3 INTEGRITY PROTECTION.........................................13 + 2.4 CONFIDENTIALITY PROTECTION...................................14 + 3 SECURITY CONSIDERATIONS.........................................15 + 3.1 AUTHENTICATION OF CLIENTS USING DIGEST AUTHENTICATION........15 + 3.2 COMPARISON OF DIGEST WITH PLAINTEXT PASSWORDS................16 + 3.3 REPLAY ATTACKS...............................................16 + + + +Leach & Newman Standards Track [Page 1] + +RFC 2831 Digest SASL Mechanism May 2000 + + + 3.4 ONLINE DICTIONARY ATTACKS....................................16 + 3.5 OFFLINE DICTIONARY ATTACKS...................................16 + 3.6 MAN IN THE MIDDLE............................................17 + 3.7 CHOSEN PLAINTEXT ATTACKS.....................................17 + 3.8 SPOOFING BY COUNTERFEIT SERVERS..............................17 + 3.9 STORING PASSWORDS............................................17 + 3.10 MULTIPLE REALMS.............................................18 + 3.11 SUMMARY.....................................................18 + 4 EXAMPLE.........................................................18 + 5 REFERENCES......................................................20 + 6 AUTHORS' ADDRESSES..............................................21 + 7 ABNF............................................................21 + 7.1 AUGMENTED BNF................................................21 + 7.2 BASIC RULES..................................................23 + 8 SAMPLE CODE.....................................................25 + 9 FULL COPYRIGHT STATEMENT........................................27 + +1 Introduction + + This specification describes the use of HTTP Digest Access + Authentication as a SASL mechanism. The authentication type + associated with the Digest SASL mechanism is "DIGEST-MD5". + + This specification is intended to be upward compatible with the + "md5-sess" algorithm of HTTP/1.1 Digest Access Authentication + specified in [Digest]. The only difference in the "md5-sess" + algorithm is that some directives not needed in a SASL mechanism have + had their values defaulted. + + There is one new feature for use as a SASL mechanism: integrity + protection on application protocol messages after an authentication + exchange. + + Also, compared to CRAM-MD5, DIGEST-MD5 prevents chosen plaintext + attacks, and permits the use of third party authentication servers, + mutual authentication, and optimized reauthentication if a client has + recently authenticated to a server. + +1.1 Conventions and Notation + + This specification uses the same ABNF notation and lexical + conventions as HTTP/1.1 specification; see appendix A. + + Let { a, b, ... } be the concatenation of the octet strings a, b, ... + + Let H(s) be the 16 octet MD5 hash [RFC 1321] of the octet string s. + + + + + +Leach & Newman Standards Track [Page 2] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Let KD(k, s) be H({k, ":", s}), i.e., the 16 octet hash of the string + k, a colon and the string s. + + Let HEX(n) be the representation of the 16 octet MD5 hash n as a + string of 32 hex digits (with alphabetic characters always in lower + case, since MD5 is case sensitive). + + Let HMAC(k, s) be the 16 octet HMAC-MD5 [RFC 2104] of the octet + string s using the octet string k as a key. + + The value of a quoted string constant as an octet string does not + include any terminating null character. + +1.2 Requirements + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC 2119]. + + An implementation is not compliant if it fails to satisfy one or more + of the MUST level requirements for the protocols it implements. An + implementation that satisfies all the MUST level and all the SHOULD + level requirements for its protocols is said to be "unconditionally + compliant"; one that satisfies all the MUST level requirements but + not all the SHOULD level requirements for its protocols is said to be + "conditionally compliant." + +2 Authentication + + The following sections describe how to use Digest as a SASL + authentication mechanism. + +2.1 Initial Authentication + + If the client has not recently authenticated to the server, then it + must perform "initial authentication", as defined in this section. If + it has recently authenticated, then a more efficient form is + available, defined in the next section. + +2.1.1 Step One + + The server starts by sending a challenge. The data encoded in the + challenge contains a string formatted according to the rules for a + "digest-challenge" defined as follows: + + + + + + + +Leach & Newman Standards Track [Page 3] + +RFC 2831 Digest SASL Mechanism May 2000 + + + digest-challenge = + 1#( realm | nonce | qop-options | stale | maxbuf | charset + algorithm | cipher-opts | auth-param ) + + realm = "realm" "=" <"> realm-value <"> + realm-value = qdstr-val + nonce = "nonce" "=" <"> nonce-value <"> + nonce-value = qdstr-val + qop-options = "qop" "=" <"> qop-list <"> + qop-list = 1#qop-value + qop-value = "auth" | "auth-int" | "auth-conf" | + token + stale = "stale" "=" "true" + maxbuf = "maxbuf" "=" maxbuf-value + maxbuf-value = 1*DIGIT + charset = "charset" "=" "utf-8" + algorithm = "algorithm" "=" "md5-sess" + cipher-opts = "cipher" "=" <"> 1#cipher-value <"> + cipher-value = "3des" | "des" | "rc4-40" | "rc4" | + "rc4-56" | token + auth-param = token "=" ( token | quoted-string ) + + The meanings of the values of the directives used above are as + follows: + + realm + Mechanistically, a string which can enable users to know which + username and password to use, in case they might have different + ones for different servers. Conceptually, it is the name of a + collection of accounts that might include the user's account. This + string should contain at least the name of the host performing the + authentication and might additionally indicate the collection of + users who might have access. An example might be + "registered_users@gotham.news.example.com". This directive is + optional; if not present, the client SHOULD solicit it from the + user or be able to compute a default; a plausible default might be + the realm supplied by the user when they logged in to the client + system. Multiple realm directives are allowed, in which case the + user or client must choose one as the realm for which to supply to + username and password. + + nonce + A server-specified data string which MUST be different each time a + digest-challenge is sent as part of initial authentication. It is + recommended that this string be base64 or hexadecimal data. Note + that since the string is passed as a quoted string, the + double-quote character is not allowed unless escaped (see section + 7.2). The contents of the nonce are implementation dependent. The + + + +Leach & Newman Standards Track [Page 4] + +RFC 2831 Digest SASL Mechanism May 2000 + + + security of the implementation depends on a good choice. It is + RECOMMENDED that it contain at least 64 bits of entropy. The nonce + is opaque to the client. This directive is required and MUST + appear exactly once; if not present, or if multiple instances are + present, the client should abort the authentication exchange. + + qop-options + A quoted string of one or more tokens indicating the "quality of + protection" values supported by the server. The value "auth" + indicates authentication; the value "auth-int" indicates + authentication with integrity protection; the value "auth-conf" + indicates authentication with integrity protection and encryption. + This directive is optional; if not present it defaults to "auth". + The client MUST ignore unrecognized options; if the client + recognizes no option, it should abort the authentication exchange. + + stale + The "stale" directive is not used in initial authentication. See + the next section for its use in subsequent authentications. This + directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + maxbuf + A number indicating the size of the largest buffer the server is + able to receive when using "auth-int" or "auth-conf". If this + directive is missing, the default value is 65536. This directive + may appear at most once; if multiple instances are present, the + client should abort the authentication exchange. + + charset + This directive, if present, specifies that the server supports + UTF-8 encoding for the username and password. If not present, the + username and password must be encoded in ISO 8859-1 (of which + US-ASCII is a subset). The directive is needed for backwards + compatibility with HTTP Digest, which only supports ISO 8859-1. + This directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + algorithm + This directive is required for backwards compatibility with HTTP + Digest., which supports other algorithms. . This directive is + required and MUST appear exactly once; if not present, or if + multiple instances are present, the client should abort the + authentication exchange. + + + + + + + +Leach & Newman Standards Track [Page 5] + +RFC 2831 Digest SASL Mechanism May 2000 + + + cipher-opts + A list of ciphers that the server supports. This directive must be + present exactly once if "auth-conf" is offered in the + "qop-options" directive, in which case the "3des" and "des" modes + are mandatory-to-implement. The client MUST ignore unrecognized + options; if the client recognizes no option, it should abort the + authentication exchange. + + des + the Data Encryption Standard (DES) cipher [FIPS] in cipher + block chaining (CBC) mode with a 56 bit key. + + 3des + the "triple DES" cipher in CBC mode with EDE with the same key + for each E stage (aka "two keys mode") for a total key length + of 112 bits. + + rc4, rc4-40, rc4-56 + the RC4 cipher with a 128 bit, 40 bit, and 56 bit key, + respectively. + + auth-param This construct allows for future extensions; it may appear + more than once. The client MUST ignore any unrecognized + directives. + + For use as a SASL mechanism, note that the following changes are made + to "digest-challenge" from HTTP: the following Digest options (called + "directives" in HTTP terminology) are unused (i.e., MUST NOT be sent, + and MUST be ignored if received): + + opaque + domain + + The size of a digest-challenge MUST be less than 2048 bytes. + +2.1.2 Step Two + + The client makes note of the "digest-challenge" and then responds + with a string formatted and computed according to the rules for a + "digest-response" defined as follows: + + + + + + + + + + + +Leach & Newman Standards Track [Page 6] + +RFC 2831 Digest SASL Mechanism May 2000 + + + digest-response = 1#( username | realm | nonce | cnonce | + nonce-count | qop | digest-uri | response | + maxbuf | charset | cipher | authzid | + auth-param ) + + username = "username" "=" <"> username-value <"> + username-value = qdstr-val + cnonce = "cnonce" "=" <"> cnonce-value <"> + cnonce-value = qdstr-val + nonce-count = "nc" "=" nc-value + nc-value = 8LHEX + qop = "qop" "=" qop-value + digest-uri = "digest-uri" "=" <"> digest-uri-value <"> + digest-uri-value = serv-type "/" host [ "/" serv-name ] + serv-type = 1*ALPHA + host = 1*( ALPHA | DIGIT | "-" | "." ) + serv-name = host + response = "response" "=" response-value + response-value = 32LHEX + LHEX = "0" | "1" | "2" | "3" | + "4" | "5" | "6" | "7" | + "8" | "9" | "a" | "b" | + "c" | "d" | "e" | "f" + cipher = "cipher" "=" cipher-value + authzid = "authzid" "=" <"> authzid-value <"> + authzid-value = qdstr-val + + + username + The user's name in the specified realm, encoded according to the + value of the "charset" directive. This directive is required and + MUST be present exactly once; otherwise, authentication fails. + + realm + The realm containing the user's account. This directive is + required if the server provided any realms in the + "digest-challenge", in which case it may appear exactly once and + its value SHOULD be one of those realms. If the directive is + missing, "realm-value" will set to the empty string when computing + A1 (see below for details). + + nonce + The server-specified data string received in the preceding + digest-challenge. This directive is required and MUST be present + exactly once; otherwise, authentication fails. + + + + + + +Leach & Newman Standards Track [Page 7] + +RFC 2831 Digest SASL Mechanism May 2000 + + + cnonce + A client-specified data string which MUST be different each time a + digest-response is sent as part of initial authentication. The + cnonce-value is an opaque quoted string value provided by the + client and used by both client and server to avoid chosen + plaintext attacks, and to provide mutual authentication. The + security of the implementation depends on a good choice. It is + RECOMMENDED that it contain at least 64 bits of entropy. This + directive is required and MUST be present exactly once; otherwise, + authentication fails. + + nonce-count + The nc-value is the hexadecimal count of the number of requests + (including the current request) that the client has sent with the + nonce value in this request. For example, in the first request + sent in response to a given nonce value, the client sends + "nc=00000001". The purpose of this directive is to allow the + server to detect request replays by maintaining its own copy of + this count - if the same nc-value is seen twice, then the request + is a replay. See the description below of the construction of + the response value. This directive may appear at most once; if + multiple instances are present, the client should abort the + authentication exchange. + + qop + Indicates what "quality of protection" the client accepted. If + present, it may appear exactly once and its value MUST be one of + the alternatives in qop-options. If not present, it defaults to + "auth". These values affect the computation of the response. Note + that this is a single token, not a quoted list of alternatives. + + serv-type + Indicates the type of service, such as "www" for web service, + "ftp" for FTP service, "smtp" for mail delivery service, etc. The + service name as defined in the SASL profile for the protocol see + section 4 of [RFC 2222], registered in the IANA registry of + "service" elements for the GSSAPI host-based service name form + [RFC 2078]. + + host + The DNS host name or IP address for the service requested. The + DNS host name must be the fully-qualified canonical name of the + host. The DNS host name is the preferred form; see notes on server + processing of the digest-uri. + + + + + + + +Leach & Newman Standards Track [Page 8] + +RFC 2831 Digest SASL Mechanism May 2000 + + + serv-name + Indicates the name of the service if it is replicated. The service + is considered to be replicated if the client's service-location + process involves resolution using standard DNS lookup operations, + and if these operations involve DNS records (such as SRV, or MX) + which resolve one DNS name into a set of other DNS names. In this + case, the initial name used by the client is the "serv-name", and + the final name is the "host" component. For example, the incoming + mail service for "example.com" may be replicated through the use + of MX records stored in the DNS, one of which points at an SMTP + server called "mail3.example.com"; it's "serv-name" would be + "example.com", it's "host" would be "mail3.example.com". If the + service is not replicated, or the serv-name is identical to the + host, then the serv-name component MUST be omitted. + + digest-uri + Indicates the principal name of the service with which the client + wishes to connect, formed from the serv-type, host, and serv-name. + For example, the FTP service on "ftp.example.com" would have a + "digest-uri" value of "ftp/ftp.example.com"; the SMTP server from + the example above would have a "digest-uri" value of + "smtp/mail3.example.com/example.com". + + Servers SHOULD check that the supplied value is correct. This will + detect accidental connection to the incorrect server. It is also so + that clients will be trained to provide values that will work with + implementations that use a shared back-end authentication service + that can provide server authentication. + + The serv-type component should match the service being offered. The + host component should match one of the host names of the host on + which the service is running, or it's IP address. Servers SHOULD NOT + normally support the IP address form, because server authentication + by IP address is not very useful; they should only do so if the DNS + is unavailable or unreliable. The serv-name component should match + one of the service's configured service names. + + This directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + Note: In the HTTP use of Digest authentication, the digest-uri is the + URI (usually a URL) of the resource requested -- hence the name of + the directive. + + response + A string of 32 hex digits computed as defined below, which proves + that the user knows a password. This directive is required and + MUST be present exactly once; otherwise, authentication fails. + + + +Leach & Newman Standards Track [Page 9] + +RFC 2831 Digest SASL Mechanism May 2000 + + + maxbuf + A number indicating the size of the largest buffer the client is + able to receive. If this directive is missing, the default value + is 65536. This directive may appear at most once; if multiple + instances are present, the server should abort the authentication + exchange. + + charset + This directive, if present, specifies that the client has used + UTF-8 encoding for the username and password. If not present, the + username and password must be encoded in ISO 8859-1 (of which + US-ASCII is a subset). The client should send this directive only + if the server has indicated it supports UTF-8. The directive is + needed for backwards compatibility with HTTP Digest, which only + supports ISO 8859-1. + + LHEX + 32 hex digits, where the alphabetic characters MUST be lower case, + because MD5 is not case insensitive. + + cipher + The cipher chosen by the client. This directive MUST appear + exactly once if "auth-conf" is negotiated; if required and not + present, authentication fails. + + authzid + The "authorization ID" as per RFC 2222, encoded in UTF-8. This + directive is optional. If present, and the authenticating user has + sufficient privilege, and the server supports it, then after + authentication the server will use this identity for making all + accesses and access checks. If the client specifies it, and the + server does not support it, then the response-value will be + incorrect, and authentication will fail. + + The size of a digest-response MUST be less than 4096 bytes. + +2.1.2.1 Response-value + + The definition of "response-value" above indicates the encoding for + its value -- 32 lower case hex characters. The following definitions + show how the value is computed. + + Although qop-value and components of digest-uri-value may be + case-insensitive, the case which the client supplies in step two is + preserved for the purpose of computing and verifying the + response-value. + + response-value = + + + +Leach & Newman Standards Track [Page 10] + +RFC 2831 Digest SASL Mechanism May 2000 + + + HEX( KD ( HEX(H(A1)), + { nonce-value, ":" nc-value, ":", + cnonce-value, ":", qop-value, ":", HEX(H(A2)) })) + + If authzid is specified, then A1 is + + + A1 = { H( { username-value, ":", realm-value, ":", passwd } ), + ":", nonce-value, ":", cnonce-value, ":", authzid-value } + + If authzid is not specified, then A1 is + + + A1 = { H( { username-value, ":", realm-value, ":", passwd } ), + ":", nonce-value, ":", cnonce-value } + + where + + passwd = *OCTET + + The "username-value", "realm-value" and "passwd" are encoded + according to the value of the "charset" directive. If "charset=UTF-8" + is present, and all the characters of either "username-value" or + "passwd" are in the ISO 8859-1 character set, then it must be + converted to ISO 8859-1 before being hashed. This is so that + authentication databases that store the hashed username, realm and + password (which is common) can be shared compatibly with HTTP, which + specifies ISO 8859-1. A sample implementation of this conversion is + in section 8. + + If the "qop" directive's value is "auth", then A2 is: + + A2 = { "AUTHENTICATE:", digest-uri-value } + + If the "qop" value is "auth-int" or "auth-conf" then A2 is: + + A2 = { "AUTHENTICATE:", digest-uri-value, + ":00000000000000000000000000000000" } + + Note that "AUTHENTICATE:" must be in upper case, and the second + string constant is a string with a colon followed by 32 zeros. + + These apparently strange values of A2 are for compatibility with + HTTP; they were arrived at by setting "Method" to "AUTHENTICATE" and + the hash of the entity body to zero in the HTTP digest calculation of + A2. + + Also, in the HTTP usage of Digest, several directives in the + + + +Leach & Newman Standards Track [Page 11] + +RFC 2831 Digest SASL Mechanism May 2000 + + + "digest-challenge" sent by the server have to be returned by the + client in the "digest-response". These are: + + opaque + algorithm + + These directives are not needed when Digest is used as a SASL + mechanism (i.e., MUST NOT be sent, and MUST be ignored if received). + +2.1.3 Step Three + + The server receives and validates the "digest-response". The server + checks that the nonce-count is "00000001". If it supports subsequent + authentication (see section 2.2), it saves the value of the nonce and + the nonce-count. It sends a message formatted as follows: + + response-auth = "rspauth" "=" response-value + + where response-value is calculated as above, using the values sent in + step two, except that if qop is "auth", then A2 is + + A2 = { ":", digest-uri-value } + + And if qop is "auth-int" or "auth-conf" then A2 is + + A2 = { ":", digest-uri-value, ":00000000000000000000000000000000" } + + Compared to its use in HTTP, the following Digest directives in the + "digest-response" are unused: + + nextnonce + qop + cnonce + nonce-count + +2.2 Subsequent Authentication + + If the client has previously authenticated to the server, and + remembers the values of username, realm, nonce, nonce-count, cnonce, + and qop that it used in that authentication, and the SASL profile for + a protocol permits an initial client response, then it MAY perform + "subsequent authentication", as defined in this section. + + + + + + + + + +Leach & Newman Standards Track [Page 12] + +RFC 2831 Digest SASL Mechanism May 2000 + + +2.2.1 Step one + + The client uses the values from the previous authentication and sends + an initial response with a string formatted and computed according to + the rules for a "digest-response", as defined above, but with a + nonce-count one greater than used in the last "digest-response". + +2.2.2 Step Two + + The server receives the "digest-response". If the server does not + support subsequent authentication, then it sends a + "digest-challenge", and authentication proceeds as in initial + authentication. If the server has no saved nonce and nonce-count from + a previous authentication, then it sends a "digest-challenge", and + authentication proceeds as in initial authentication. Otherwise, the + server validates the "digest-response", checks that the nonce-count + is one greater than that used in the previous authentication using + that nonce, and saves the new value of nonce-count. + + If the response is invalid, then the server sends a + "digest-challenge", and authentication proceeds as in initial + authentication (and should be configurable to log an authentication + failure in some sort of security audit log, since the failure may be + a symptom of an attack). The nonce-count MUST NOT be incremented in + this case: to do so would allow a denial of service attack by sending + an out-of-order nonce-count. + + If the response is valid, the server MAY choose to deem that + authentication has succeeded. However, if it has been too long since + the previous authentication, or for any other reason, the server MAY + send a new "digest-challenge" with a new value for nonce. The + challenge MAY contain a "stale" directive with value "true", which + says that the client may respond to the challenge using the password + it used in the previous response; otherwise, the client must solicit + the password anew from the user. This permits the server to make sure + that the user has presented their password recently. (The directive + name refers to the previous nonce being stale, not to the last use of + the password.) Except for the handling of "stale", after sending the + "digest-challenge" authentication proceeds as in the case of initial + authentication. + +2.3 Integrity Protection + + If the server offered "qop=auth-int" and the client responded + "qop=auth-int", then subsequent messages, up to but not including the + next subsequent authentication, between the client and the server + + + + + +Leach & Newman Standards Track [Page 13] + +RFC 2831 Digest SASL Mechanism May 2000 + + + MUST be integrity protected. Using as a base session key the value of + H(A1) as defined above the client and server calculate a pair of + message integrity keys as follows. + + The key for integrity protecting messages from client to server is: + + Kic = MD5({H(A1), + "Digest session key to client-to-server signing key magic constant"}) + + The key for integrity protecting messages from server to client is: + + Kis = MD5({H(A1), + "Digest session key to server-to-client signing key magic constant"}) + + where MD5 is as specified in [RFC 1321]. If message integrity is + negotiated, a MAC block for each message is appended to the message. + The MAC block is 16 bytes: the first 10 bytes of the HMAC-MD5 [RFC + 2104] of the message, a 2-byte message type number in network byte + order with value 1, and the 4-byte sequence number in network byte + order. The message type is to allow for future extensions such as + rekeying. + + MAC(Ki, SeqNum, msg) = (HMAC(Ki, {SeqNum, msg})[0..9], 0x0001, + SeqNum) + + where Ki is Kic for messages sent by the client and Kis for those + sent by the server. The sequence number is initialized to zero, and + incremented by one for each message sent. + + Upon receipt, MAC(Ki, SeqNum, msg) is computed and compared with the + received value; the message is discarded if they differ. + +2.4 Confidentiality Protection + + If the server sent a "cipher-opts" directive and the client responded + with a "cipher" directive, then subsequent messages between the + client and the server MUST be confidentiality protected. Using as a + base session key the value of H(A1) as defined above the client and + server calculate a pair of message integrity keys as follows. + + The key for confidentiality protecting messages from client to server + is: + + Kcc = MD5({H(A1)[0..n], + "Digest H(A1) to client-to-server sealing key magic constant"}) + + The key for confidentiality protecting messages from server to client + is: + + + +Leach & Newman Standards Track [Page 14] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Kcs = MD5({H(A1)[0..n], + "Digest H(A1) to server-to-client sealing key magic constant"}) + + where MD5 is as specified in [RFC 1321]. For cipher "rc4-40" n is 5; + for "rc4-56" n is 7; for the rest n is 16. The key for the "rc-*" + ciphers is all 16 bytes of Kcc or Kcs; the key for "des" is the first + 7 bytes; the key for "3des" is the first 14 bytes. The IV for "des" + and "3des" is the last 8 bytes of Kcc or Kcs. + + If message confidentiality is negotiated, each message is encrypted + with the chosen cipher and a MAC block is appended to the message. + + The MAC block is a variable length padding prefix followed by 16 + bytes formatted as follows: the first 10 bytes of the HMAC-MD5 [RFC + 2104] of the message, a 2-byte message type number in network byte + order with value 1, and the 4-byte sequence number in network byte + order. If the blocksize of the chosen cipher is not 1 byte, the + padding prefix is one or more octets each containing the number of + padding bytes, such that total length of the encrypted part of the + message is a multiple of the blocksize. The padding and first 10 + bytes of the MAC block are encrypted along with the message. + + SEAL(Ki, Kc, SeqNum, msg) = + {CIPHER(Kc, {msg, pad, HMAC(Ki, {SeqNum, msg})[0..9])}), 0x0001, + SeqNum} + + where CIPHER is the chosen cipher, Ki and Kc are Kic and Kcc for + messages sent by the client and Kis and Kcs for those sent by the + server. The sequence number is initialized to zero, and incremented + by one for each message sent. + + Upon receipt, the message is decrypted, HMAC(Ki, {SeqNum, msg}) is + computed and compared with the received value; the message is + discarded if they differ. + +3 Security Considerations + +3.1 Authentication of Clients using Digest Authentication + + Digest Authentication does not provide a strong authentication + mechanism, when compared to public key based mechanisms, for example. + However, since it prevents chosen plaintext attacks, it is stronger + than (e.g.) CRAM-MD5, which has been proposed for use with LDAP [10], + POP and IMAP (see RFC 2195 [9]). It is intended to replace the much + weaker and even more dangerous use of plaintext passwords; however, + since it is still a password based mechanism it avoids some of the + potential deployabilty issues with public-key, OTP or similar + mechanisms. + + + +Leach & Newman Standards Track [Page 15] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Digest Authentication offers no confidentiality protection beyond + protecting the actual password. All of the rest of the challenge and + response are available to an eavesdropper, including the user's name + and authentication realm. + +3.2 Comparison of Digest with Plaintext Passwords + + The greatest threat to the type of transactions for which these + protocols are used is network snooping. This kind of transaction + might involve, for example, online access to a mail service whose use + is restricted to paying subscribers. With plaintext password + authentication an eavesdropper can obtain the password of the user. + This not only permits him to access anything in the database, but, + often worse, will permit access to anything else the user protects + with the same password. + +3.3 Replay Attacks + + Replay attacks are defeated if the client or the server chooses a + fresh nonce for each authentication, as this specification requires. + +3.4 Online dictionary attacks + + If the attacker can eavesdrop, then it can test any overheard + nonce/response pairs against a (potentially very large) list of + common words. Such a list is usually much smaller than the total + number of possible passwords. The cost of computing the response for + each password on the list is paid once for each challenge. + + The server can mitigate this attack by not allowing users to select + passwords that are in a dictionary. + +3.5 Offline dictionary attacks + + If the attacker can choose the challenge, then it can precompute the + possible responses to that challenge for a list of common words. Such + a list is usually much smaller than the total number of possible + passwords. The cost of computing the response for each password on + the list is paid just once. + + Offline dictionary attacks are defeated if the client chooses a fresh + nonce for each authentication, as this specification requires. + + + + + + + + + +Leach & Newman Standards Track [Page 16] + +RFC 2831 Digest SASL Mechanism May 2000 + + +3.6 Man in the Middle + + Digest authentication is vulnerable to "man in the middle" (MITM) + attacks. Clearly, a MITM would present all the problems of + eavesdropping. But it also offers some additional opportunities to + the attacker. + + A possible man-in-the-middle attack would be to substitute a weaker + qop scheme for the one(s) sent by the server; the server will not be + able to detect this attack. For this reason, the client should always + use the strongest scheme that it understands from the choices + offered, and should never choose a scheme that does not meet its + minimum requirements. + +3.7 Chosen plaintext attacks + + A chosen plaintext attack is where a MITM or a malicious server can + arbitrarily choose the challenge that the client will use to compute + the response. The ability to choose the challenge is known to make + cryptanalysis much easier [8]. + + However, Digest does not permit the attack to choose the challenge as + long as the client chooses a fresh nonce for each authentication, as + this specification requires. + +3.8 Spoofing by Counterfeit Servers + + If a user can be led to believe that she is connecting to a host + containing information protected by a password she knows, when in + fact she is connecting to a hostile server, then the hostile server + can obtain challenge/response pairs where it was able to partly + choose the challenge. There is no known way that this can be + exploited. + +3.9 Storing passwords + + Digest authentication requires that the authenticating agent (usually + the server) store some data derived from the user's name and password + in a "password file" associated with a given realm. Normally this + might contain pairs consisting of username and H({ username-value, + ":", realm-value, ":", passwd }), which is adequate to compute H(A1) + as described above without directly exposing the user's password. + + The security implications of this are that if this password file is + compromised, then an attacker gains immediate access to documents on + the server using this realm. Unlike, say a standard UNIX password + file, this information need not be decrypted in order to access + documents in the server realm associated with this file. On the other + + + +Leach & Newman Standards Track [Page 17] + +RFC 2831 Digest SASL Mechanism May 2000 + + + hand, decryption, or more likely a brute force attack, would be + necessary to obtain the user's password. This is the reason that the + realm is part of the digested data stored in the password file. It + means that if one Digest authentication password file is compromised, + it does not automatically compromise others with the same username + and password (though it does expose them to brute force attack). + + There are two important security consequences of this. First the + password file must be protected as if it contained plaintext + passwords, because for the purpose of accessing documents in its + realm, it effectively does. + + A second consequence of this is that the realm string should be + unique among all realms that any single user is likely to use. In + particular a realm string should include the name of the host doing + the authentication. + +3.10 Multiple realms + + Use of multiple realms may mean both that compromise of a the + security database for a single realm does not compromise all + security, and that there are more things to protect in order to keep + the whole system secure. + +3.11 Summary + + By modern cryptographic standards Digest Authentication is weak, + compared to (say) public key based mechanisms. But for a large range + of purposes it is valuable as a replacement for plaintext passwords. + Its strength may vary depending on the implementation. + +4 Example + + This example shows the use of the Digest SASL mechanism with the + IMAP4 AUTHENTICATE command [RFC 2060]. + + In this example, "C:" and "S:" represent a line sent by the client or + server respectively including a CRLF at the end. Linebreaks and + indentation within a "C:" or "S:" are editorial and not part of the + protocol. The password in this example was "secret". Note that the + base64 encoding of the challenges and responses is part of the IMAP4 + AUTHENTICATE command, not part of the Digest specification itself. + + S: * OK elwood.innosoft.com PMDF IMAP4rev1 V6.0-9 + C: c CAPABILITY + S: * CAPABILITY IMAP4 IMAP4rev1 ACL LITERAL+ NAMESPACE QUOTA + UIDPLUS AUTH=CRAM-MD5 AUTH=DIGEST-MD5 AUTH=PLAIN + S: c OK Completed + + + +Leach & Newman Standards Track [Page 18] + +RFC 2831 Digest SASL Mechanism May 2000 + + + C: a AUTHENTICATE DIGEST-MD5 + S: + cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 + RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh + cnNldD11dGYtOA== + C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 + QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw + MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im + ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw + ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg= + S: + cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== + C: + S: a OK User logged in + --- + + The base64-decoded version of the SASL exchange is: + + S: realm="elwood.innosoft.com",nonce="OA6MG9tEQGm2hh",qop="auth", + algorithm=md5-sess,charset=utf-8 + C: charset=utf-8,username="chris",realm="elwood.innosoft.com", + nonce="OA6MG9tEQGm2hh",nc=00000001,cnonce="OA6MHXh6VqTrRk", + digest-uri="imap/elwood.innosoft.com", + response=d388dad90d4bbd760a152321f2143af7,qop=auth + S: rspauth=ea40f60335c427b5527b84dbabcdfffd + + The password in this example was "secret". + + This example shows the use of the Digest SASL mechanism with the + ACAP, using the same notational conventions and password as in the + previous example. Note that ACAP does not base64 encode and uses + fewer round trips that IMAP4. + + S: * ACAP (IMPLEMENTATION "Test ACAP server") (SASL "CRAM-MD5" + "DIGEST-MD5" "PLAIN") + C: a AUTHENTICATE "DIGEST-MD5" + S: + {94} + S: realm="elwood.innosoft.com",nonce="OA9BSXrbuRhWay",qop="auth", + algorithm=md5-sess,charset=utf-8 + C: {206} + C: charset=utf-8,username="chris",realm="elwood.innosoft.com", + nonce="OA9BSXrbuRhWay",nc=00000001,cnonce="OA9BSuZWMSpW8m", + digest-uri="acap/elwood.innosoft.com", + response=6084c6db3fede7352c551284490fd0fc,qop=auth + S: a OK (SASL {40} + S: rspauth=2f0b3d7c3c2e486600ef710726aa2eae) "AUTHENTICATE + Completed" + --- + + + + + +Leach & Newman Standards Track [Page 19] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The server uses the values of all the directives, plus knowledge of + the users password (or the hash of the user's name, server's realm + and the user's password) to verify the computations above. If they + check, then the user has authenticated. + +5 References + + [Digest] Franks, J., et al., "HTTP Authentication: Basic and Digest + Access Authentication", RFC 2617, June 1999. + + [ISO-8859] ISO-8859. International Standard--Information Processing-- + 8-bit Single-Byte Coded Graphic Character Sets -- + Part 1: Latin alphabet No. 1, ISO-8859-1:1987. + Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. + Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. + Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. + Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. + Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. + Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. + Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. + Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. + + [RFC 822] Crocker, D., "Standard for The Format of ARPA Internet + Text Messages," STD 11, RFC 822, August 1982. + + [RFC 1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, + April 1992. + + [RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + + [RFC 2052] Gulbrandsen, A. and P. Vixie, "A DNS RR for specifying the + location of services (DNS SRV)", RFC 2052, October 1996. + + [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + + [RFC 2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, February + 1997. + + [RFC 2195] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP + AUTHorize Extension for Simple Challenge/Response", RFC + 2195, September 1997. + + + + + + +Leach & Newman Standards Track [Page 20] + +RFC 2831 Digest SASL Mechanism May 2000 + + + [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC 2222] Myers, J., "Simple Authentication and Security Layer + (SASL)", RFC 2222, October 1997. + + [USASCII] US-ASCII. Coded Character Set - 7-Bit American Standard + Code for Information Interchange. Standard ANSI X3.4-1986, + ANSI, 1986. + +6 Authors' Addresses + + Paul Leach + Microsoft + 1 Microsoft Way + Redmond, WA 98052 + + EMail: paulle@microsoft.com + + + Chris Newman + Innosoft International, Inc. + 1050 Lakes Drive + West Covina, CA 91790 USA + + EMail: chris.newman@innosoft.com + +7 ABNF + + What follows is the definition of the notation as is used in the + HTTP/1.1 specification (RFC 2616) and the HTTP authentication + specification (RFC 2617); it is reproduced here for ease of + reference. Since it is intended that a single Digest implementation + can support both HTTP and SASL-based protocols, the same notation is + used in both to facilitate comparison and prevention of unwanted + differences. Since it is cut-and-paste from the HTTP specifications, + not all productions may be used in this specification. It is also not + quite legal ABNF; again, the errors were copied from the HTTP + specifications. + +7.1 Augmented BNF + + All of the mechanisms specified in this document are described in + both prose and an augmented Backus-Naur Form (BNF) similar to that + used by RFC 822 [RFC 822]. Implementers will need to be familiar with + the notation in order to understand this specification. + + + + + +Leach & Newman Standards Track [Page 21] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The augmented BNF includes the following constructs: + + name = definition + The name of a rule is simply the name itself (without any + enclosing "<" and ">") and is separated from its definition by the + equal "=" character. White space is only significant in that + indentation of continuation lines is used to indicate a rule + definition that spans more than one line. Certain basic rules are + in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle + brackets are used within definitions whenever their presence will + facilitate discerning the use of rule names. + + "literal" + Quotation marks surround literal text. Unless stated otherwise, + the text is case-insensitive. + + rule1 | rule2 + Elements separated by a bar ("|") are alternatives, e.g., "yes | + no" will accept yes or no. + + (rule1 rule2) + Elements enclosed in parentheses are treated as a single element. + Thus, "(elem (foo | bar) elem)" allows the token sequences + "elem foo elem" and "elem bar elem". + + *rule + The character "*" preceding an element indicates repetition. The + full form is "*element" indicating at least and at most + occurrences of element. Default values are 0 and infinity so + that "*(element)" allows any number, including zero; "1*element" + requires at least one; and "1*2element" allows one or two. + + [rule] + Square brackets enclose optional elements; "[foo bar]" is + equivalent to "*1(foo bar)". + + N rule + Specific repetition: "(element)" is equivalent to + "*(element)"; that is, exactly occurrences of (element). + Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three + alphabetic characters. + + #rule + A construct "#" is defined, similar to "*", for defining lists of + elements. The full form is "#element" indicating at least + and at most elements, each separated by one or more commas + (",") and OPTIONAL linear white space (LWS). This makes the usual + form of lists very easy; a rule such as + + + +Leach & Newman Standards Track [Page 22] + +RFC 2831 Digest SASL Mechanism May 2000 + + + ( *LWS element *( *LWS "," *LWS element )) + can be shown as + 1#element + Wherever this construct is used, null elements are allowed, but do + not contribute to the count of elements present. That is, + "(element), , (element) " is permitted, but counts as only two + elements. Therefore, where at least one element is required, at + least one non-null element MUST be present. Default values are 0 + and infinity so that "#element" allows any number, including zero; + "1#element" requires at least one; and "1#2element" allows one or + two. + + ; comment + A semi-colon, set off some distance to the right of rule text, + starts a comment that continues to the end of line. This is a + simple way of including useful notes in parallel with the + specifications. + + implied *LWS + The grammar described by this specification is word-based. Except + where noted otherwise, linear white space (LWS) can be included + between any two adjacent words (token or quoted-string), and + between adjacent words and separators, without changing the + interpretation of a field. At least one delimiter (LWS and/or + separators) MUST exist between any two tokens (for the definition + of "token" below), since they would otherwise be interpreted as a + single token. + +7.2 Basic Rules + + The following rules are used throughout this specification to + describe basic parsing constructs. The US-ASCII coded character set + is defined by ANSI X3.4-1986 [USASCII]. + + OCTET = + CHAR = + UPALPHA = + LOALPHA = + ALPHA = UPALPHA | LOALPHA + DIGIT = + CTL = + CR = + LF = + SP = + HT = + <"> = + CRLF = CR LF + + + +Leach & Newman Standards Track [Page 23] + +RFC 2831 Digest SASL Mechanism May 2000 + + + + All linear white space, including folding, has the same semantics as + SP. A recipient MAY replace any linear white space with a single SP + before interpreting the field value or forwarding the message + downstream. + + LWS = [CRLF] 1*( SP | HT ) + + The TEXT rule is only used for descriptive field contents and values + that are not intended to be interpreted by the message parser. Words + of *TEXT MAY contain characters from character sets other than + ISO-8859-1 [ISO 8859] only when encoded according to the rules of RFC + 2047 [RFC 2047]. + + TEXT = + + A CRLF is allowed in the definition of TEXT only as part of a header + field continuation. It is expected that the folding LWS will be + replaced with a single SP before interpretation of the TEXT value. + + Hexadecimal numeric characters are used in several protocol elements. + + HEX = "A" | "B" | "C" | "D" | "E" | "F" + | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT + + Many HTTP/1.1 header field values consist of words separated by LWS + or special characters. These special characters MUST be in a quoted + string to be used within a parameter value. + + token = 1* + separators = "(" | ")" | "<" | ">" | "@" + | "," | ";" | ":" | "\" | <"> + | "/" | "[" | "]" | "?" | "=" + | "{" | "}" | SP | HT + + A string of text is parsed as a single word if it is quoted using + double-quote marks. + + quoted-string = ( <"> qdstr-val <"> ) + qdstr-val = *( qdtext | quoted-pair ) + qdtext = > + + Note that LWS is NOT implicit between the double-quote marks (<">) + surrounding a qdstr-val and the qdstr-val; any LWS will be considered + part of the qdstr-val. This is also the case for quotation marks + surrounding any other construct. + + + + +Leach & Newman Standards Track [Page 24] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The backslash character ("\") MAY be used as a single-character + quoting mechanism only within qdstr-val and comment constructs. + + quoted-pair = "\" CHAR + + The value of this construct is CHAR. Note that an effect of this rule + is that backslash must be quoted. + +8 Sample Code + + The sample implementation in [Digest] also applies to DIGEST-MD5. + + The following code implements the conversion from UTF-8 to 8859-1 if + necessary. + + /* if the string is entirely in the 8859-1 subset of UTF-8, then + * translate to 8859-1 prior to MD5 + */ + void MD5_UTF8_8859_1(MD5_CTX *ctx, const unsigned char *base, + int len) + { + const unsigned char *scan, *end; + unsigned char cbuf; + + end = base + len; + for (scan = base; scan < end; ++scan) { + if (*scan > 0xC3) break; /* abort if outside 8859-1 */ + if (*scan >= 0xC0 && *scan <= 0xC3) { + if (++scan == end || *scan < 0x80 || *scan > 0xBF) + break; + } + } + /* if we found a character outside 8859-1, don't alter string + */ + if (scan < end) { + MD5Update(ctx, base, len); + return; + } + + /* convert to 8859-1 prior to applying hash + */ + do { + for (scan = base; scan < end && *scan < 0xC0; ++scan) + ; + if (scan != base) MD5Update(ctx, base, scan - base); + if (scan + 1 >= end) break; + cbuf = ((scan[0] & 0x3) << 6) | (scan[1] & 0x3f); + MD5Update(ctx, &cbuf, 1); + + + +Leach & Newman Standards Track [Page 25] + +RFC 2831 Digest SASL Mechanism May 2000 + + + base = scan + 2; + } while (base < end); + } + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leach & Newman Standards Track [Page 26] + +RFC 2831 Digest SASL Mechanism May 2000 + + +9 Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + 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 the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Leach & Newman Standards Track [Page 27] +