Cds: rewordings

2011-11-26T02:31:48Z

rewordings

New page

= Name =

'''ngx_http_auth_digest''' - HTTP Digest Authentication support for Nginx.

''This module is not distributed with the Nginx source.'' See the [https://github.com/samizdatco/nginx-http-auth-digest/blob/master/readme.rst installation instructions].

= Status =

The module is feature-complete with respect to the RFC but is in need of broader testing before it can be considered secure enough for use in production. See the [https://github.com/samizdatco/nginx-http-auth-digest/blob/master/bugs.txt <code>bugs.txt</code>] file and the github [https://github.com/samizdatco/nginx-http-auth-digest/issues issue tracker] for the current set of caveats.

= Synopsis =

You can limit access to a directory tree by adding the following lines into
a ''server'' section in your Nginx configuration file:

<geshi lang="nginx">
auth_digest_user_file /opt/httpd/conf/passwd.digest; # a file created with htdigest
location /private{
auth_digest 'this is not for you'; # set the realm for this location block
}
</geshi>

The other directives control the lifespan defaults for the authentication session. The
following is equivalent to the previous example but demonstrates all the directives:

<geshi lang="nginx">
auth_digest_user_file /opt/httpd/conf/passwd.digest;
auth_digest_shm_size 4m; # the storage space allocated for tracking active sessions

location /private {
auth_digest 'this is not for you';
auth_digest_timeout 60s; # allow users to wait 1 minute between receiving the
# challenge and hitting send in the browser dialog box
auth_digest_expires 10s; # after a successful challenge/response, let the client
# continue to use the same nonce for additional requests
# for 10 seconds before generating a new challenge
auth_digest_replays 20; # also generate a new challenge if the client uses the
# same nonce more than 20 times before the expire time limit
}
</geshi>

Adding digest authentication to a location will affect any uris that match that block. To
disable authentication for specific sub-branches off a uri, set <code>auth_digest</code> to <code>off</code>:

<geshi lang="nginx">
location / {
auth_digest 'this is not for you';
location /pub {
auth_digest off; # this sub-tree will be accessible without authentication
}
}
</geshi>

= Directives =

== auth_digest ==

'''Syntax:''' auth_digest [''realm-name'' | <code>off</code> ]

'''Default:''' <code>off</code>

'''Context:''' ''server, location''

Enable or disable digest authentication for a server or location block. The realm name
should correspond to a realm used in the user file. Any user within that realm will be
able to access files after authenticating.

To selectively disable authentication within a protected uri hierarchy, set <code>auth_digest</code>
to “<code>off</code>” within a more-specific location block (see example).
== auth_digest_user_file ==

'''Syntax:''' auth_digest_user_file ''/path/to/passwd/file''

'''Default:''' ''none''

'''Context:''' ''server, location''

The password file should be of the form created by the apache <code>htdigest</code> command (or the
included <code>[https://github.com/samizdatco/nginx-http-auth-digest/blob/master/htdigest.py htdigest.py]</code> script). Each line of the file is a colon-separated list composed
of a username, realm, and md5 hash combining name, realm, and password. For example:

joi:enfield:ef25e85b34208c246cfd09ab76b01db7
== auth_digest_timeout ==

'''Syntax:''' auth_digest_timeout ''delay-time''

'''Default:''' <code>60s</code>

'''Context:''' ''server, location''

When a client first requests a protected page, the server returns a 401 status code along with
a challenge in the <code>WWW-Authenticate</code> header.

At this point most browsers will present a dialog box to the user prompting them to log in. This
directive defines how long challenges will remain valid. If the user waits longer than this time
before submitting their name and password, the challenge will be considered ‘stale’ and they will
be prompted to log in again.
== auth_digest_expires ==

'''Syntax:''' auth_digest_expires ''lifetime-in-seconds''

'''Default:''' <code>10s</code>

'''Context:''' ''server, location''

Once a digest challenge has been successfully answered by the client, subsequent requests
will attempt to re-use the ‘nonce’ value from the original challenge. To complicate MitM
attacks, it's best to limit the number of times a cached nonce will be accepted. This
directive sets the duration for this re-use period after the first successful authentication.
== auth_digest_replays ==

'''Syntax:''' auth_digest_replays ''number-of-uses''

'''Default:''' <code>20</code>

'''Context:''' ''server, location''

Nonce re-use should also be limited to a fixed number of requests. Note that increasing this
value will cause a proportional increase in memory usage and the shm_size may have to be
adjusted to keep up with heavy traffic within the digest-protected location blocks.
== auth_digest_shm_size ==

'''Syntax:''' auth_digest_shm_size ''size-in-bytes''

'''Default:''' <code>4096k</code>

'''Context:''' ''server''

The module maintains a fixed-size cache of active digest sessions to save state between
authenticated requests. Once this cache is full, no further authentication will be possible
until active sessions expire.

As a result, choosing the proper size is a little tricky since it depends upon the values set in
the expiration-related directives. Each stored challenge takes up <code>48 + ceil(auth_digest_replays/8)</code> bytes
and will live for up to <code>auth_digest_timeout + auth_digest_expires</code> seconds. When using the
default module settings this translates into allowing around 82k non-replay requests every 70
seconds.

= Source Repository =

Available on github at [https://github.com/samizdatco/nginx-http-auth-digest samizdatco/nginx-http-auth-digest].

= Author =

Christian Swinehart / [http://samizdat.cc Samizdat Drafting Co.]

= Copyright & License =

The basic request-handling and password-file-parsing is based on the <code>ngx_http_auth_basic</code> module in the Nginx 1.0.8 sources. The original code is copyright Igor Sysoev.

Copyright (c) 2011, Christian Swinehart

This module is licensed under the terms of the [https://github.com/samizdatco/nginx-http-auth-digest/blob/master/LICENSE BSD license].

= See Also =

* The [http://www.ietf.org/rfc/rfc2617.txt RFC 2617] definition of basic and digest authentication.
* Shane Holloway's werkzeug [https://bitbucket.org/shanewholloway/werkzeug-main/src/tip/werkzeug/contrib/authdigest.py module] which was used as a reference implementation.

HttpAuthDigestModule - Revision history

Cds: rewordings