45 Oaklands Wood Hatfield Hertfordshire AL10 8LU United Kingdom +44 (0)1707 258219 nickshanks@nickshanks.com http://nickshanks.com/

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.

This scheme builds upon the Digest authentication scheme defined by and updated by , 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) , serving only to obscure passwords from eavesdroppers, however nothing prevents its use over an encrypted connection if so desired.

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

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 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>

This scheme defines specific meanings for the following form field names and gives user agents processing directives for each. 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. An integer value in seconds which, when not empty, generates an Authentication-Control header () 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.

This scheme introduces no new parameters for the Authorization header additional to those already defined by .

When using the Form authentication scheme, the default value for the auth-style parameter of the Authentication-Control header is the token "non-modal".

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

This section is non-normative. Readers are directed to 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.

Yet to be written (mostly). All security considerations in pertaining to the Digest authentication method apply to the Form method too. Futher vulnerabilities to Digest authentication are discussed in 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.

IANA is to register the "Form" authentication scheme, citing 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 .

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.

The author thanks to the memebers of the http-auth mailing list for their assistance.

Clarify role with respect to TLS. Added , and , and split out into its own sub-section. Altered token order, added definitions and corrected indentation issue with ABNF in . Added normative reference to , and an informational references to and . 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 , and added six terms. Added , , and expanded .

Server requirements and User Agent requirements are inter-mixed in , 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), 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.