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 03, 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.

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!); 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 of the quoted-string X without the surrounding quotes.

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 <form> element with <input> descendants, XML incorperating XForms <xf:input> 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  = <defined in RFC 2617>
    cnonce-value = <defined in RFC 2617>
				

2.1. Field Names

This scheme defines specific meanings for the following form field names and gives user agents processing directives for each.

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:

<form action=/login.php method=POST>
    <input name=user required>
    <input name=realm type=hidden value=admin>
    <input name=pass type=password required>
    <input name=_auth_expire_ type=hidden value=900>
    <input name=_auth_expire_ type=checkbox> Do not
        log out after 15 minutes of inactivity.
    <button>Log In</button>
</form>
					

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 [issues]]). 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.

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.

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 <http://www.iana.org/assignments/http-authschemes> 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.

5. References

5.1. Normative References

5.2. Informational References

Author's Address

Table of Contents

• 1. Introduction
• 1.1. Terminology
• 2. The "Form" Authentication Scheme
• 2.1. Field Names
• 2.2. Authorization Parameters
• 2.3. Authentication-Control Parameters
• 2.4. Examples
• 2.5. De-authentication Mechanisms
• 3. Security Considerations
• 4. IANA Considerations
• 4.1. Authentication Scheme Registration
• 5. References
• 5.1. Normative References
• 5.2. Informational References
• Author's Address