readme.rst
1==================================
2Nginx Digest Authentication module
3==================================
4
5Changes from other forks
6========================
7Bug fixes
8`1 <https://github.com/samizdatco/nginx-http-auth-digest/commit/9d77dcc58420d5afb8aa5a8138b1bf22a1933dd6>`_,
9`2 <https://github.com/samizdatco/nginx-http-auth-digest/commit/b98725d3d0506c895f6a9f9d38f9168d499275fc>`_,
10`3 <https://github.com/samizdatco/nginx-http-auth-digest/commit/47d5bac13cf071b4dbe81048b0f12a742ba512ae>`_
11
12`Added log message for invalid login attempts <https://github.com/samizdatco/nginx-http-auth-digest/commit/9a402045082291c1f2f0a432ac24475277e2d176>`_
13
14Description
15===========
16The ``ngx_http_auth_digest`` module supplements Nginx_'s built-in Basic Authentication `module`_ by providing support for `RFC`_ 2617 `Digest Authentication`_. The module is currently functional but has only been tested and reviewed by its author. And given that this is security code, one set of eyes is almost certainly insufficient to guarantee that it's 100% correct. Until a few bug reports come in and some of the ‘unknown unknowns’ in the code are flushed out, consider this module an ‘alpha’ and treat it with the appropriate amount of skepticism.
17
18A listing of known issues with the module can be found in the ``bugs.txt`` file as well as in the `Issue Tracker`_. Please do consider contributing a patch if you have the time and inclination. Any help fixing the bugs or changing the implementation to a more idiomatically nginx-y one would be greatly appreciated.
19
20Dependencies
21============
22* Sources for Nginx_ 1.0.x, and its dependencies.
23
24
25Building
26========
27
281. Unpack the Nginx_ sources::
29
30 $ tar zxvf nginx-1.0.x.tar.gz
31
322. Unpack the sources for the digest module::
33
34 $ tar xzvf samizdatco-nginx-http-auth-digest-xxxxxxx.tar.gz
35
363. Change to the directory which contains the Nginx_ sources, run the
37 configuration script with the desired options and be sure to put an
38 ``--add-module`` flag pointing to the directory which contains the source
39 of the digest module::
40
41 $ cd nginx-1.0.x
42 $ ./configure --add-module=../samizdatco-nginx-http-auth-digest-xxxxxxx [other configure options]
43
444. Build and install the software::
45
46 $ make && sudo make install
47
485. Configure Nginx_ using the module's configuration directives_.
49
50
51Example
52=======
53
54You can password-protect a directory tree by adding the following lines into
55a ``server`` section in your Nginx_ configuration file::
56
57 auth_digest_user_file /opt/httpd/conf/passwd.digest; # a file created with htdigest
58 location /private{
59 auth_digest 'this is not for you'; # set the realm for this location block
60 }
61
62
63The other directives control the lifespan defaults for the authentication session. The
64following is equivalent to the previous example but demonstrates all the directives::
65
66 auth_digest_user_file /opt/httpd/conf/passwd.digest;
67 auth_digest_shm_size 4m; # the storage space allocated for tracking active sessions
68
69 location /private {
70 auth_digest 'this is not for you';
71 auth_digest_timeout 60s; # allow users to wait 1 minute between receiving the
72 # challenge and hitting send in the browser dialog box
73 auth_digest_expires 10s; # after a successful challenge/response, let the client
74 # continue to use the same nonce for additional requests
75 # for 10 seconds before generating a new challenge
76 auth_digest_replays 20; # also generate a new challenge if the client uses the
77 # same nonce more than 20 times before the expire time limit
78 }
79
80Adding digest authentication to a location will affect any uris that match that block. To
81disable authentication for specific sub-branches off a uri, set ``auth_digest`` to ``off``::
82
83 location / {
84 auth_digest 'this is not for you';
85 location /pub {
86 auth_digest off; # this sub-tree will be accessible without authentication
87 }
88 }
89
90Directives
91==========
92
93auth_digest
94~~~~~~~~~~~
95:Syntax: ``auth_digest`` [*realm-name* | ``off``]
96:Default: ``off``
97:Context: server, location
98:Description:
99 Enable or disable digest authentication for a server or location block. The realm name
100 should correspond to a realm used in the user file. Any user within that realm will be
101 able to access files after authenticating.
102
103 To selectively disable authentication within a protected uri hierarchy, set ``auth_digest``
104 to “``off``” within a more-specific location block (see example).
105
106
107auth_digest_user_file
108~~~~~~~~~~~~~~~~~~~~~
109:Syntax: ``auth_digest_user_file`` */path/to/passwd/file*
110:Default: *unset*
111:Context: server, location
112:Description:
113 The password file should be of the form created by the apache ``htdigest`` command (or the
114 included `htdigest.py`_ script). Each line of the file is a colon-separated list composed
115 of a username, realm, and md5 hash combining name, realm, and password. For example:
116 ``joi:enfield:ef25e85b34208c246cfd09ab76b01db7``
117
118auth_digest_timeout
119~~~~~~~~~~~~~~~~~~~
120:Syntax: ``auth_digest_timeout`` *delay-time*
121:Default: ``60s``
122:Context: server, location
123:Description:
124 When a client first requests a protected page, the server returns a 401 status code along with
125 a challenge in the ``www-authenticate`` header.
126
127 At this point most browsers will present a dialog box to the user prompting them to log in. This
128 directive defines how long challenges will remain valid. If the user waits longer than this time
129 before submitting their name and password, the challenge will be considered ‘stale’ and they will
130 be prompted to log in again.
131
132auth_digest_expires
133~~~~~~~~~~~~~~~~~~~
134:Syntax: ``auth_digest_expires`` *lifetime-in-seconds*
135:Default: ``10s``
136:Context: server, location
137:Description:
138 Once a digest challenge has been successfully answered by the client, subsequent requests
139 will attempt to re-use the ‘nonce’ value from the original challenge. To complicate MitM_
140 attacks, it's best to limit the number of times a cached nonce will be accepted. This
141 directive sets the duration for this re-use period after the first successful authentication.
142
143auth_digest_replays
144~~~~~~~~~~~~~~~~~~~
145:Syntax: ``auth_digest_replays`` *number-of-uses*
146:Default: ``20``
147:Context: server, location
148:Description:
149 Nonce re-use should also be limited to a fixed number of requests. Note that increasing this
150 value will cause a proportional increase in memory usage and the shm_size may have to be
151 adjusted to keep up with heavy traffic within the digest-protected location blocks.
152
153auth_digest_evasion_time
154~~~~~~~~~~~~~~~~~~~~~~~~
155:Syntax: ``auth_digest_evasion_time`` *time-in-seconds*
156:Default: ``300s``
157:Context: server, location
158:Description:
159 The amount of time for which the server will ignore authentication requests from a client
160 address once the number of failed authentications from that client reaches ``auth_digest_maxtries``.
161
162auth_digest_maxtries
163~~~~~~~~~~~~~~~~~~~~
164:Syntax: ``auth_digest_maxtries`` *number-of-attempts*
165:Default: ``5``
166:Context: server, location
167:Description:
168 The number of failed authentication attempts from a client address before the module enters
169 evasive tactics. For evasion purposes, only network clients are tracked, and only by address
170 (not including port number). A successful authentication clears the counters.
171
172auth_digest_shm_size
173~~~~~~~~~~~~~~~~~~~~
174:Syntax: ``auth_digest_shm_size`` *size-in-bytes*
175:Default: ``4096k``
176:Context: server
177:Description:
178 The module maintains a fixed-size cache of active digest sessions to save state between
179 authenticated requests. Once this cache is full, no further authentication will be possible
180 until active sessions expire.
181
182 As a result, choosing the proper size is a little tricky since it depends upon the values set in
183 the expiration-related directives. Each stored challenge takes up ``48 + ceil(replays/8)`` bytes
184 and will live for up to ``auth_digest_timeout + auth_digest_expires`` seconds. When using the
185 default module settings this translates into allowing around 82k non-replay requests every 70
186 seconds.
187
188.. _nginx: http://nginx.net
189.. _module: http://wiki.nginx.org/HttpAuthBasicModule
190.. _htdigest.py: https://github.com/samizdatco/nginx-http-auth-digest/blob/master/htdigest.py
191.. _RFC: http://www.ietf.org/rfc/rfc2617.txt
192.. _Digest Authentication: http://en.wikipedia.org/wiki/Digest_access_authentication
193.. _Issue Tracker: https://github.com/samizdatco/nginx-http-auth-digest/issues
194.. _MitM: http://en.wikipedia.org/wiki/Man-in-the-middle_attack
195