Re: [http-auth] I-D Action: draft-ietf-httpauth-digest-09.txt

[Julian Reschke <[e-mail]>]

Hi there,

it's the first time I read this in a long time; apologies for the lack 
of structure; and also that most of these should have been made during WGLC.



Abstract

    HTTP provides a simple challenge-response authentication mechanism
    that may be used by a server to challenge a client request and by a
    client to provide authentication information. This document defines
    the HTTP Digest Authentication scheme that may be used with the
    authentication mechanism.

s/may/can/

Also maybe: ...that can used with the *HTTP* authentication mechanism.

1 Introduction

    HTTP provides a simple challenge-response authentication mechanism
    that may be used by a server to challenge a client request and by a
    client to provide authentication information. This document defines
    the HTTP Digest Authentication scheme that may be used with the
    authentication mechanism.

(see above)

    The details of the challenge-response authentication mechanism are
    specified in the [RFC7235] document.

...in "Hypertext Transfer Protocol (HTTP/1.1): Authentication" [RFC7235].

    The combination of this document with Basic [BASIC] and [RFC7235]
    obsolete RFC2617.

s/Basic/the definition of the "Basic" authentication scheme/
s/RFC2617/RFC 2617/

2.2 Algorithm Variants

    When used with the Digest mechanism, each one of the algorithms has
    two variants: Session variant and non-Session variant.

    The non-Session variant is denoted by "<algorithm>", e.g. "SHA-256",
    and the Session variant is denoted by "<algorithm>-sess", e.g. "SHA-
    256-sess".

This comes very early; maybe it would be better mentioned later on.

2.3 ABNF

    This specification uses the Augmented Backus-Naur Form (ABNF)
    notation of [RFC5234].

Actually, you'll also need 
<http://greenbytes.de/tech/webdav/rfc7230.html#abnf.extension> (see 
below later).


    realm
       A string to be displayed to users so they know which username and
       password to use. 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 "[e-mail]". (See section 2.2 of
       [RFC7235] for more details).

s/section/Section/

For the host name part, see <https://tools.ietf.org/html/rfc2606>.

    domain
       A quoted, space-separated list of URIs, as specified in RFC 3986
       [RFC3986], that define the protection space. If a URI is an
       abs_path, it is relative to the canonical root URL of the web-
       origin. An absolute-URI in this list may refer to a different
       server than the web-origin. The client can use this list to
       determine the set of URIs for which the same authentication
       information may be sent: any URI that has a URI in this list as a

s/may/can/ or MAY

       prefix (after both have been made absolute) may be assumed to be
       in the same protection space. If this parameter is omitted or its
       value is empty, the client SHOULD assume that the protection space
       consists of all URIs on the web-origin. All URIs in this list
       SHOULD use the same scheme (https or http); mixing them is a bad
       idea.

web_origin and canonical root need definitions.

Why is mixing them a "bad idea"? - maybe this could be explained better.

       This parameter is not meaningful in Proxy-Authenticate header
       fields, for which the protection space is always the entire proxy;
       if present it should be ignored.

MUST? SHOULD?

    nonce
       A server-specified data string which should be uniquely generated
       each time a 401 response is made. It is recommended that this

RECOMMENDED?

Would there be a problem if it is a differen format? If no, why a 
normative requirement here?

       string be base64 or hexadecimal data. Specifically, since the
       string is passed in the header field lines as a quoted string, the
       double-quote character is not allowed.

well, unless suitably escaped.

       The contents of the nonce are implementation dependent. The

s/are/is/?

       quality of the implementation depends on a good choice. A nonce
       might, for example, be constructed as the base 64 encoding of

             time-stamp H(time-stamp ":" ETag ":" secret-data)

       where time-stamp is a server-generated time, which preferably

s/value/values/

       includes micro or nano seconds, or other non-repeating value, ETag
       is the value of the HTTP ETag header field associated with the
       requested entity, and secret-data is data known only to the
       server. With a nonce of this form a server would recalculate the
       hash portion after receiving the client authentication header
       field and reject the request if it did not match the nonce from
       that header field or if the time-stamp value is not recent enough.
       In this way the server can limit the time of the nonce's validity.
       The inclusion of the ETag prevents a replay request for an updated
       version of the resource. Including the IP address of the client in
       the nonce would appear to offer the server the ability to limit
       the reuse of the nonce to the same client that originally got it.
       However, that would break proxy farms, where requests from a
       single user often go through different proxies in the farm. Also,
       IP address spoofing is not that hard.

Do you need a proxy *farm* for this problem?

       An implementation might choose not to accept a previously used
       nonce or a previously used digest, in order to protect against a
       replay attack. Or, an implementation might choose to use one-time
       nonces or digests for POST or PUT requests and a time-stamp for
       GET requests. For more details on the issues involved see section
       5 of this document.

s/section/Section/

...why are these lowercase; aren't they generated by xml2rfc? If not, 
they should, because otherwise they break too easily.

       The nonce is opaque to the client.

    opaque
       A string of data, specified by the server, which SHOULD be
       returned by the client unchanged in the Authorization header field
       of subsequent requests with URIs in the same protection space. It
       is RECOMMENDED that this string be base64 or hexadecimal data.

(see above)

    stale
       A case-insensitive flag indicating that the previous request from
       the client was rejected because the nonce value was stale. If
       stale is TRUE, the client MAY wish to simply retry the request

"MAY wish" doesn't seem like a case for a BCP14 keyword.

       with a new encrypted response, without re-prompting the user for a
       new username and password. The server SHOULD only set stale to
       TRUE if it receives a request for which the nonce is invalid. If
       stale is FALSE, or anything other than TRUE, or the stale
       parameter is not present, the username and/or password are
       invalid, and new values MUST be obtained.

    algorithm
       A string indicating a pair of algorithms used to produce the
       digest and a checksum. If this is not present it is assumed to be
       "MD5". If the algorithm is not understood, the challenge should be
       ignored (and a different one used, if there is more than one).

Avoid lowercase BCP14 keywords. Either uppercase or choose something 
else (here and later on).


    userhash
       This is an OPTIONAL parameter that is used by the server to
       indicate that it supports username hashing. Valid values are:
       "true" or "false".

Defaults to false, I assume.


3.4 The Authorization Request Header

s/header/header field/

       The client is expected to retry the request, passing an
       Authorization header field line with Digest scheme, which is
       defined according to the framework above. The values of the opaque
       and algorithm fields must be those supplied in the WWW-
       Authenticate response header field for the entity being requested.

       The request includes some or all of the following parameters:

"some or all" reads weird...

    uri
       The URI from request-target of the Request-Line; duplicated here
       because proxies are allowed to change the Request-Line in transit.

The request-target of the Request-Line isn't necessarily a URI...

    qop
       Indicates what "quality of protection" the client has applied to
       the message. Its value MUST be one of the alternatives the server
       indicated it supports in the WWW-Authenticate header field. These
       values affect the computation of the response. Note that this is a
       single token, not a quoted list of alternatives as in WWW-
       Authenticate.

Can it use quoted-string nevertheless?

    nc
       This parameter MUST be used by all implementations compliant with
       this version of the Digest scheme. The "nc" parameter stands for

I wonder why we need to say "compliant with this version"?

    userhash
       This OPTIONAL parameter is used by the client to indicate that the
       username has been hashed. Valid values are: "true" or "false".

Default?

    If a parameter or its value is improper, or required parameters are
    missing, the proper response is 400 Bad Request. If the request-

Is this a requirement? Could it be a more specifc 4xx code?

    digest is invalid, then a login failure should be logged, since
    repeated login failures from a single client may indicate an attacker
    attempting to guess passwords. The server implementation should be

SHOULD?

    careful with the information being logged so that it won't put a
    cleartext password (e.g. entered into the username field) into the
    log.

    The definition of response above indicates the encoding for its

s/of/of the/

    value. The following definitions show how the value is computed.



    This creates a 'session key' for the authentication of subsequent

double quotes?

    requests and responses which is different for each "authentication
    session", thus limiting the amount of material hashed with any one
    key. (Note: see further discussion of the authentication session in
    section 3.6.) Because the server need only use the hash of the user

s/need/needs/

    credentials in order to create the A1 value, this construction could
    be used in conjunction with a third party authentication service so
    that the web server would not need the actual password value. The
    specification of such a protocol is beyond the scope of this
    specification.

    Also note that if integrity protection is applied (qop=auth-int), the
    H(entity-body) is the hash of the entity body, not the message body -
    it is computed before any transfer encoding is applied by the sender
    and after it has been removed by the recipient. Note that this
    includes multipart boundaries and embedded header fields in each part
    of any multipart content-type.

(reduce amout of "note that"...)

3.4.6 Various Considerations

    The "Method" value is the HTTP request method, in all-uppercase US-
    ASCII letters, as specified in section 3.1.1 of [RFC7230]. The

Hm, no. The registered methods happen to be all-uppercase, but method 
names are case-sensitive.

    Implementers should be aware of how authenticated transactions

...need to be...

    interact with shared caches. The HTTP/1.1 protocol specifies that

s/The HTTP/1.1 protocol/HTTP/

    when a shared cache (see [RFC7234]) has received a request containing
    an Authorization header field and a response from relaying that
    request, it MUST NOT return that response as a reply to any other
    request, unless one of two Cache-Control (see section 3.2 of
    [RFC7234]) directive was present in the response. If the original
    response included the "must-revalidate" Cache-Control directive, the
    cache MAY use the entity of that response in replying to a subsequent
    request, but MUST first revalidate it with the origin server, using
    the request header fields from the new request to allow the origin
    server to authenticate the new request. Alternatively, if the
    original response included the "public" Cache-Control directive, the
    response entity MAY be returned in reply to any subsequent request.

Do we need to replicate this information here? (Asking because the Basic 
spec does not)

3.5 The Authentication-Info Header

    The Authentication-Info header field is a generic field that MAY be
    used by a server to communicate some information regarding the
    successful authentication of a client response. The following is the
    syntax of the header:

            Authentication-Info = auth-info

            auth-info = *auth-param

This needs to be "#auth-param" and invoke the list ABNF extension from 
RFC 7230.

    The auth-param is defined in [RFC7235].

(I still believe we should extract this into a separate spec)

3.5.1 Digest Usage of Authentication-Info

    The Digest authentication scheme MAY add the Authentication-Info
    header field in the confirmation request with some or all of the
    following parameters:

"Some or all" reads weird.


3.6 Digest Operation

    Upon receiving the Authorization header field, the server MAY check
    its validity by looking up the password that corresponds to the
    submitted username. Then, the server MUST perform the same digest
    operation (e.g. MD5, SHA-256) performed by the client, and compare
    the result to the given response value.

    Note that the HTTP server does not actually need to know the user's
    cleartext password. As long as H(A1) is available to the server, the
    validity of an Authorization header field MAY be verified.

s/MAY/can/

    Because the client is required to return the value of the opaque

s/required/REQUIRED/

    parameter given to it by the server for the duration of a session,
    the opaque data MAY be used to transport authentication session state

s/MAY/can/

    information. (Note that any such use can also be accomplished more
    easily and safely by including the state in the nonce.) For example,
    a server could be responsible for authenticating content that
    actually sits on another server. It would achieve this by having the
    first 401 response include a domain parameter whose value includes a
    URI on the second server, and an opaque parameter whose value
    contains the state information. The client will retry the request, at
    which time the server might respond with a 301/302 redirection,

Do not exclude 307/308. Just say "HTTP Redirection (Section 6.4 of 
[RFC7231])"

    As with the basic scheme, proxies MUST be completely transparent in

s/basic/"Basic"/

Is it wise to cite that hear?

    the Digest access authentication scheme. That is, they MUST forward
    the WWW-Authenticate, Authentication-Info and Authorization header
    fields untouched. If a proxy wants to authenticate a client before a
    request is forwarded to the server, it can be done using the Proxy-
    Authenticate and Proxy-Authorization header fields described in
    section 3.8 below.


3.7 Security Protocol Negotiation

    It is useful for a server to be able to know which security schemes a
    client is capable of handling.

    It is possible that a server MAY want to require Digest as its

s/MAY want/wants/

    authentication method, even if the server does not know that the
    client supports it. A client is encouraged to fail gracefully if the
    server specifies only authentication schemes it cannot handle.

    When a server receives a request to access a resource, the server
    might challenge the client by responding with "401 Unauthorized"
    status code, and include one or more WWW-Authenticate header fields.

s/status code/response/

    If the server challenges with multiple Digest header fields, then
    each one of these header fields MUST use a different digest

You could have multiple challenges in a single header field instance.

    algorithm. The server MUST add these Digest header fields to the
    response in order of preference, starting with the most preferred
    header field, followed by the less preferred header fields.

most preferred algorithm?

    When the client receives the response it SHOULD use the topmost
    header field that it supports, unless a local policy dictates

First challenge.

    otherwise. The client SHOULD ignore any challenge it does not
    understand.

MUST, I believe.

Also, this sounds like requirements that are generic to WWW-A, not 
specific to Digest, no?


3.8 Proxy-Authenticate and Proxy-Authorization

    The digest authentication scheme MAY also be used for authenticating

s/MAY/can/

    users to proxies, proxies to proxies, or proxies to origin servers by
    use of the Proxy-Authenticate and Proxy-Authorization header fields.
    These header fields are instances of the Proxy-Authenticate and
    Proxy- Authorization header fields specified in sections 4.2 and 4.3

s/Proxy- Authorization/Proxy-Authorization/

    of the HTTP/1.1 specification [RFC7235] and their behavior is subject
    to restrictions described there. The transactions for proxy
    authentication are very similar to those already described. Upon
    receiving a request which requires authentication, the proxy/server
    MUST issue the "407 Proxy Authentication Required" response with a
    "Proxy-Authenticate" header field. The digest-challenge used in the
    Proxy-Authenticate header field is the same as that for the WWW-
    Authenticate header field as defined above in section 3.2.1.

I don't see a Section 3.2.1.


3.9 Examples

3.9.1 Example with SHA-256 and MD5


    The following example assumes that an access protected document is
    being requested from the server via a GET request. The URI of the
    document is http://www.nowhere.org/dir/index.html". Both client and
    server know that the username for this document is "Mufasa" and the
    password is "Circle of Life" ( with one space between each of the
    three words).

Need to use RFC 2606 hostnames.

    The first time the client requests the document, no Authorization
    header field is sent, so the server responds with:

         HTTP/1.1 401 Unauthorized
         WWW-Authenticate: Digest
                 realm="[e-mail]",
                 qop="auth, auth-int",
                 algorithm="SHA-256",
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"
         WWW-Authenticate: Digest
                 realm="[e-mail]",
                 qop="auth, auth-int",
                 algorithm="MD5",
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

    The client MAY prompt the user for their username and password, after

s/MAY/can/ or /will/

Maybe also point out that you could also send...:

         WWW-Authenticate: Digest realm="[e-mail]",
                 qop="auth, auth-int",
                 algorithm="SHA-256",
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS",
                 Digest realm="[e-mail]",
                 qop="auth, auth-int",
                 algorithm="MD5",
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

Later:


         Authorization:Digest username="Mufasa",

insert an SP after the colon.

                 realm="[e-mail]",
                 uri="/dir/index.html",
                 algorithm=MD5,
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 nc=00000001,
                 cnonce="f2/wE4q74E6zIJEtWaHKaf5wv/H5QzzpXusqGemxURZJ",
                 qop=auth,
                 response="8ca523f5e9506fed4657c9700eebdbec",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"


    If the client chooses to use the SHA-256 algorithm for calculating
    the response, the client responds with a new request including the
    following Authorization header field:


         Authorization:Digest username="Mufasa",
                 realm="[e-mail]",
                 uri="/dir/index.html",
                 algorithm=SHA-256,
                 nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
                 nc=00000001,
                 cnonce="f2/wE4q74E6zIJEtWaHKaf5wv/H5QzzpXusqGemxURZJ",
                 qop=auth,
                 response="753927fa0e85d155564e2e272a28d1802ca10daf449
                    6794697cf8db5856cb6c1",
                 opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

3.9.2 Example with SHA-512-256, Charset, and Userhash

    The following example assumes that an access protected document is
    being requested from the server via a GET request. The URI for the
    request is "http://api.example.org/doe.json". Both client and server
    know the userhash of the username, support the UTF-8 charset, and use

s/UTF-8 charset/UTF-8 character encoding scheme/

    the SHA-512-256 algorithm. The username for the request is "Jason
    Doe" and the password is "Secret, or not?".

It would be good to have non-ASCII characters in the example.

    The first time the client requests the document, no Authorization
    header field is sent, so the server responds with:


         HTTP/2.0 401 Unauthorized

HTTP/2.0????

         WWW-Authenticate: Digest
                 realm="[e-mail]",
                 qop=auth,
                 algorithm=SHA-512-256,
                 nonce="5TsQWLVdgBdmrQ0XsxbDODV+57QdFR34I9HAbC/RVvkK",
                 opaque="HRPCssKJSGjCrkzDg8OhwpzCiGPChXYjwrI2QmXDnsOS",
                 charset=UTF-8,
                 userhash=true


    The client MAY prompt the user for the required credentials and send
    a new request with following Authorization header field:

         Authorization: Digest
                 username="488869477bf257147b804c45308cd62ac4e25eb717
                    b12b298c79e62dcea254ec",
                 realm="[e-mail]",
                 uri="/doe.json",
                 algorithm=SHA-512-256,
                 nonce="5TsQWLVdgBdmrQ0XsxbDODV+57QdFR34I9HAbC/RVvkK",
                 nc=00000001,
                 cnonce="NTg6RKcb9boFIAS3KrFK9BGeh+iDa/sm6jUMp2wds69v",
                 qop=auth,
                 response="ae66e67d6b427bd3f120414a82e4acff38e8ecd9101d
                    6c861229025f607a79dd",
                 opaque="HRPCssKJSGjCrkzDg8OhwpzCiGPChXYjwrI2QmXDnsOS",
                 userhash=true

    If the client can not provide a hashed username for any reason, the
    client MAY try a request with this Authorization header field:

         Authorization: Digest
                 username*=UTF-8''J%C3%A4s%C3%B8n%20Doe,
                 realm="[e-mail]",
                 uri="/doe.json",
                 algorithm=SHA-512-256,
                 nonce="5TsQWLVdgBdmrQ0XsxbDODV+57QdFR34I9HAbC/RVvkK",
                 nc=00000001,
                 cnonce="NTg6RKcb9boFIAS3KrFK9BGeh+iDa/sm6jUMp2wds69v",
                 qop=auth,
                 response="ae66e67d6b427bd3f120414a82e4acff38e8ecd9101d6
                    c861229025f607a79dd",
                 opaque="HRPCssKJSGjCrkzDg8OhwpzCiGPChXYjwrI2QmXDnsOS",
                 userhash=false

Wait, you can't do that. You'll need to formally state that some or all 
of your auth-params can be sent using the RFC 5987 encoding (and 
upfront, not in the example here).


    For the username, recipients MUST support all characters defined in
    the "UsernameCasePreserved" profile defined in in Section 3.3 of
    [PRECIS], with the exception of the colon (":") character.

This is copied from Basic. Is it true for Digest as well?

    If the user agent does not support the encoding indicated by the
    server, it MUST fail the request.

That sounds like a deployment problem. Also it reads weird given the 
fact that only one value ("UTF-8") is allowed.


5.6 Weakness Created by Multiple Authentication Schemes

    An HTTP/1.1 server MAY return multiple challenges with a 401
    (Authenticate) response, and each challenge MAY use a different auth-
    scheme. A user agent MUST choose to use the strongest auth- scheme it

s/auth- scheme/auth-scheme/

    understands and request credentials from the user based upon that
    challenge.

       Note that many browsers will only recognize Basic and will require
       that it be the first auth-scheme presented. Servers should only

s/should/SHOULD/

       include Basic if it is minimally acceptable.

    When the server offers choices of authentication schemes using the
    WWW-Authenticate header field, the strength of the resulting
    authentication is only as good as that of the of the weakest of the
    authentication schemes. See section 5.7 below for discussion of
    particular attack scenarios that exploit multiple authentication
    schemes.



5.8 Man in the Middle

    Both Basic and Digest authentication are vulnerable to "man in the
    middle" (MITM) attacks, for example, from a hostile or compromised
    proxy. Clearly, this would present all the problems of eavesdropping.
    But it also offers some additional opportunities to the attacker.

The Digest spec shouldn't talk about "Basic". And it seems that there's 
a security consideration I dropped from 2617 and which I need to include 
into the Basic spec.

5.12 Spoofing by Counterfeit Servers

    Basic Authentication is vulnerable to spoofing by counterfeit
    servers. If a user can be led to believe that she is connecting to a

...this section doesn't belong here.


6.2  Digest Scheme Registration

    This specification registers the Digest scheme with the
    Authentication Scheme Registry.

       Authentication Scheme Name: Digest

       Pointer to specification text: RFCXXX

s/RFCXXXX/this specification/



7 Acknowledgments

    The authors of this document would like to thank the authors of
    RFC2617, as this document heavily borrows text from their document to
    provide a complete description of the digest scheme and its
    operations.

s/RFC2617/RFC 2617/


8 References

8.1 Normative References

    [RFC4513]  Harrison, R., Ed., "Lightweight Directory Access Protocol
               (LDAP): Authentication Methods and Security Mechanisms",
               RFC 4513, June 2006.

doesn't seem to be normative.


    [BASIC]    Reschke, J., "The 'Basic' HTTP Authentication Scheme",
               draft-ietf-httpauth-basicauth-update (Work in Progress),
               September 2013.

Needs update. Also shouldn't be normative.


Best regards, Julian