Network Working Group N. Shanks Internet-Draft November 30, 2012 Intended status: Standards Track Expires: June 3, 2013 Hypertext Transfer Protocol (HTTP) Form Authentication Scheme draft-shanks-http-form-authentication-01 Abstract This document defines the "Form" HTTP authentication scheme. It allows web developers access to standard HTTP-based authentication mechanisms whilst retaining control over the look and feel of their log-in page, without requiring any client-side scripting. Comments are requested and should be addressed to the author. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on June 3, 2013. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Shanks Expires June 3, 2013 [Page 1] Internet-Draft HTTP Form Authentication November 2012 1. Introduction This scheme builds upon the Digest authentication scheme defined by [RFC2617] and updated by [draft-ietf-httpbis-p7-auth], but changes the process for creating the A1 value (section 3.2.2.2 of RFC 2617), and specifies different user agent behaviour. It is intended to allow migration away from application/x-www-form-urlencoded requests over unencrypted HTTP which transmit the password in clear-text, a common occurance on the web (for example see Look At All Of These Passwords! [1]); and to do so in a way that, when widely supported by user agents and server software, will also allow simple migration from Digest authentication, should developers who are already using that scheme wish to take control of their credentials solicitation appearance. It is intended to function independent of Transport Layer Security (TLS) [RFC5246], serving only to obscure passwords from eavesdroppers, however nothing prevents its use over an encrypted connection if so desired. 1.1. Terminology 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 [RFC2119]. The terms "form field", "form input" and "form output" are used somewhat interchangably and refer to elements generated by markup which may be submitted with the form by the user agent. The phrase "submittable field" means any form field which would generate a key-value pair on form submission. In HTML 4 that would mean every input type except an unchecked checkbox and a radio group with no selected element. A form field's "name" refers to the property of the field which is used to create the key in each key-value pair submitted by the form. In HTML this would be the value of the name attribute of e.g. an input element. The phrase "reserved name pattern" indicates a form field name which begins and ends with an underscore character "_", ASCII value decimal 95. As a regular expression, this would be represented by the pattern /_.*_/ The "effective checksum algorithm" is determined as described by section 3.2.1 of RFC 2617, under "algorithm". The string obtained by applying the checksum algorithm to the data "data" will be denoted H(data). The notation unq(X) means the value Shanks Expires June 3, 2013 [Page 2] Internet-Draft HTTP Form Authentication November 2012 of the quoted-string X without the surrounding quotes. Shanks Expires June 3, 2013 [Page 3] Internet-Draft HTTP Form Authentication November 2012 2. The "Form" Authentication Scheme Supporting user agents MUST present to the user (or to another software/hardware agent acting on behalf of the user) the parsed body of a response which uses either a HTTP status code of 401 and a WWW- Authenticate header specifying the "Form" scheme; or a 407 status code and a Proxy-Authenticate header specifying the "Form" scheme. This response body MUST contain a form in a format that the user agent can understand, e.g. HTML
element with descendants, XML incorperating XForms elements, or other comparable markup which the user agent knows about. If the response does not meet these conditions, then the user agent MAY ignore this document and process the response as it would otherwise. When submitting the form, instead of obeying the action, method and encoding as may be specified by the form, user agents MUST create an Authorization header then re-submit the original request with this additional header to the original request URI. This header MUST be created per [RFC2617] with the exception of the the scheme name token, which must be "Form", and the "A1" string value. To generate the A1 value, the user agent MUST concatenate the values of all submittable fields of the form, in document order, excepting those with names that match the reserved name pattern. Each value is to be seperated from the next by a single colon character ":" not surrounded by whitespace. If a "nonce" parameter is supplied by the server in the WWW-Authenticate header, the result of the previous step is then to be hashed using the effective checksum algorithm, and followed by nonce and cnonce values also seperated from the hash and each other by single colon characters. Processing then continues as described by section 3.2.2.1 of RFC 2617. When no nonce value is provided by the server A1 = form-field-value *[ ":" form-field-value ] form-field-value = *TEXT If a nonce value is provided by the server A1 = H( form-field-value *[ ":" form-field-value ] ) ":" unq(nonce-value) ":" unq(cnonce-value) nonce-value = cnonce-value = Shanks Expires June 3, 2013 [Page 4] Internet-Draft HTTP Form Authentication November 2012 2.1. Field Names This scheme defines specific meanings for the following form field names and gives user agents processing directives for each. username If a form field exists with this name, then its value is used for the "username" parameter of the Authorization request header. If there is no field with this name, then the value of the first non-hidden, clear-text input is used as the value of the "username" parameter. _auth_expire_ An integer value in seconds which, when not empty, generates an Authentication-Control header ([draft-oiwa-httpbis-auth-extension]) with the logout-timeout parameter set to the value of this field. If multiple fields exist with this name, only the last submittable field is considered. Valid values are the empty string and any non- negative integer. Invalid values are mapped to the empty string. The value zero ("0") is not considered to be empty (i.e. it doesn't prevent parameter generation), and represents immediate expiry of the credentials after the client receives a response. 2.2. Authorization Parameters This scheme introduces no new parameters for the Authorization header additional to those already defined by [RFC2617]. 2.3. Authentication-Control Parameters When using the Form authentication scheme, the default value for the auth-style parameter of the Authentication-Control header is the token "non-modal". [draft-oiwa-httpbis-auth-extension] 2.4. Examples This section is non-normative. An example in HTML: Do not log out after 15 minutes of inactivity. Shanks Expires June 3, 2013 [Page 5] Internet-Draft HTTP Form Authentication November 2012 When filled out by the user (or acting agent) with values of user=dave and pass=p455w0rd, and assuming the default MD5 algorithm is to be used, this form will result in an Authorization header being generated by conforming user agents by means of computing the function H(A1) = md5(dave:admin:p455w0rd), then combining that with qop, nonce and other parameters as per [RFC2617]. In the above example, the presence of the hidden field "realm" will produce the same checksum result as would be generated by Digest authentication (assuming the field value "admin" matches that of the WWW- Authenticate header's realm parameter [see Appendix C]). This trick may be of use to those migrating from existing Digest deployments. An empty field results in an empty string being concatenated, with no special treatment, i.e. an empty value between two others would result in a double colon appearing in the string to be hashed, "::", and an empty field at the start or end would result in the unhashed string beginning or ending with a colon. The field names, if provided, are not included in the checksum in any way. They serve only as fallback for UAs that do not support the Form authentication method, and for identifying which field values should be excluded from string to be hashed. In the above case, user agents which do not support this scheme are expected to send a POST request to the path /login.php with the form fields URL-encoded in the request body. This allows for incremental support to be introduced as user agents are released which support this scheme and users upgrade. 2.5. De-authentication Mechanisms This section is non-normative. Readers are directed to [draft-oiwa-httpbis-auth-extension] and the Authentication-Control header, which defines such mechanisms as a means by which clients may log out, and servers may direct clients to cease sending certain authentication credentials. Shanks Expires June 3, 2013 [Page 6] Internet-Draft HTTP Form Authentication November 2012 3. Security Considerations Yet to be written (mostly). All security considerations in [RFC2617] pertaining to the Digest authentication method apply to the Form method too. Futher vulnerabilities to Digest authentication are discussed in [RFC4169] and also apply to Form authentication. Until such time as standard server software (such as Apache, Lighttpd, Nginx, etc.) nativly supports this authentication scheme, web developers will have to implement support using server-side processing langauges (such as Ruby, Node.js or PHP). All incoming requests to URIs beyond the authentication point will need to be caught and processed for authentication credentials, to avoid exposing valid URIs from invalid ones. It is expected that third- party libraries will be developed to ease this. Shanks Expires June 3, 2013 [Page 7] Internet-Draft HTTP Form Authentication November 2012 4. IANA Considerations IANA is to register the "Form" authentication scheme, citing Section 4.1 of this document as the reference, within the http- authschemes registry at as established by Section 2.3 of [draft-ietf-httpbis-p7-auth]. 4.1. Authentication Scheme Registration Authentication scheme name: Form Specification text: This document Notes: A variant of the Digest authentication scheme, with new processing requirements for the server and the client. Shanks Expires June 3, 2013 [Page 8] Internet-Draft HTTP Form Authentication November 2012 5. References 5.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997. [RFC2617] Franks, J., "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. [draft-oiwa-httpbis-auth-extension] Oiwa, Y., "HTTP Authentication Extensions for Interactive Clients", June 2012. [draft-ietf-httpbis-p7-auth] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Authentication", October 2012. 5.2. Informational References [RFC4169] Torvinen, V., "Hypertext Transfer Protocol (HTTP) Digest Authentication Using Authentication and Key Agreement (AKA) Version-2", RFC 4169, November 2005. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [draft-ahrens-httpbis-digest-auth-update] Ahrens, D. and R. Shekh Yusef, "HTTP Digest Access Authentication Algorithm Update", July 2012. [draft-ietf-httpbis-authscheme-registrations] Reschke, J., "Initial Hypertext Transfer Protocol (HTTP) Authentication Scheme Registrations", October 2012. Shanks Expires June 3, 2013 [Page 9] Internet-Draft HTTP Form Authentication November 2012 URIs [1] Shanks Expires June 3, 2013 [Page 10] Internet-Draft HTTP Form Authentication November 2012 Appendix A. Acknowledgments The author thanks to the memebers of the http-auth mailing list for their assistance. Shanks Expires June 3, 2013 [Page 11] Internet-Draft HTTP Form Authentication November 2012 Appendix B. Change History B.1. Since draft-shanks-http-form-authentication-00 Clarify role with respect to TLS. Added Section 2.1, Section 2.3 and Section 2.5, and split out Section 2.2 into its own sub-section. Altered token order, added definitions and corrected indentation issue with ABNF in Section 2. Added normative reference to [draft-oiwa-httpbis-auth-extension], and an informational references to [RFC4169] and [RFC5246]. Amended various references used in the text, and some external links in the references sections. Sorted reference sections chronologically. Changed the title and anchor of Section 1.1, and added six terms. Added Appendix A, Appendix B, and expanded Appendix C. Shanks Expires June 3, 2013 [Page 12] Internet-Draft HTTP Form Authentication November 2012 Appendix C. Known Issues Server requirements and User Agent requirements are inter-mixed in Section 2, and both are poorly defined IMO. Should fields with a name matching a WWW-Authenticate header parameter mirror the value of that parameter and ignore any value provided by the markup? i.e. Should form fields with the same name as a parameter adopt the value of the parameter? The original value of such fields will be submitted to the action URI by old UAs. Perhaps only for "realm"? I don't feel comfortable including a link to a blog article (see the Introduction (Section 1)), but I wanted to provide examples of just how common sending unencrypted auth data was in practice. Can anyone suggest a better external reference, or something I can inline? How do I add an "et al." to the list of authors where there is more than two for a given reference? I haven't yet read the ABNF documentation so I don't know if I'm using it correctly. I am also not sure how to reference it. Must the browser's response echo back "Form" as the authentication scheme, or could we get away with returning "Digest" if certain conditions are met, similar to my example? I want to make as few changes as is possible to the current Digest scheme so that as much as possible continues to function when people switch from either forms+cookies or existing Digest deployments. Perhaps change the reserved name pattern from /_.*_/ to /_.+_/ ? The rather verbose text about handling of empty fields and colons seems rather obvious and perhaps unnecessary. Shanks Expires June 3, 2013 [Page 13] Internet-Draft HTTP Form Authentication November 2012 Author's Address Nicholas Shanks 45 Oaklands Wood Hatfield, Hertfordshire AL10 8LU United Kingdom Phone: +44 (0)1707 258219 Email: nickshanks@nickshanks.com URI: http://nickshanks.com/ Shanks Expires June 3, 2013 [Page 14]