Skip to content
This repository
Newer
Older
100644 164 lines (128 sloc) 7.281 kb
258c20ca »
2011-11-04 Initial import
1 ==================================
2 Nginx Digest Authentication module
3 ==================================
4
1cce8374 »
2011-11-23 re{naming,wording}
5 The ``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.
258c20ca »
2011-11-04 Initial import
6
1cce8374 »
2011-11-23 re{naming,wording}
7 A 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.
258c20ca »
2011-11-04 Initial import
8
9 Dependencies
10 ============
97e643b6 »
2011-11-21 error handling and hash verification fixes
11 * Sources for Nginx_ 1.0.x, and its dependencies.
258c20ca »
2011-11-04 Initial import
12
13
14 Building
15 ========
16
17 1. Unpack the Nginx_ sources::
18
97e643b6 »
2011-11-21 error handling and hash verification fixes
19 $ tar zxvf nginx-1.0.x.tar.gz
258c20ca »
2011-11-04 Initial import
20
21 2. Unpack the sources for the digest module::
22
1cce8374 »
2011-11-23 re{naming,wording}
23 $ tar xzvf samizdatco-nginx-http-auth-digest-xxxxxxx.tar.gz
258c20ca »
2011-11-04 Initial import
24
25 3. Change to the directory which contains the Nginx_ sources, run the
26 configuration script with the desired options and be sure to put an
27 ``--add-module`` flag pointing to the directory which contains the source
28 of the digest module::
29
97e643b6 »
2011-11-21 error handling and hash verification fixes
30 $ cd nginx-1.0.x
1cce8374 »
2011-11-23 re{naming,wording}
31 $ ./configure --add-module=../samizdatco-nginx-http-auth-digest-xxxxxxx [other configure options]
258c20ca »
2011-11-04 Initial import
32
33 4. Build and install the software::
34
35 $ make && sudo make install
36
37 5. Configure Nginx_ using the module's configuration directives_.
38
39
40 Example
41 =======
42
43 You can password-protect a directory tree by adding the following lines into
44 a ``server`` section in your Nginx_ configuration file::
45
46 auth_digest_user_file /opt/httpd/conf/passwd.digest; # a file created with htdigest
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
47 location /private{
258c20ca »
2011-11-04 Initial import
48 auth_digest 'this is not for you'; # set the realm for this location block
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
49 }
50
51
52 The other directives control the lifespan defaults for the authentication session. The
53 following is equivalent to the previous example but demonstrates all the directives::
54
55 auth_digest_user_file /opt/httpd/conf/passwd.digest;
97e643b6 »
2011-11-21 error handling and hash verification fixes
56 auth_digest_shm_size 4m; # the storage space allocated for tracking active sessions
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
57
58 location /private {
59 auth_digest 'this is not for you';
258c20ca »
2011-11-04 Initial import
60 auth_digest_timeout 60s; # allow users to wait 1 minute between receiving the
61 # challenge and hitting send in the browser dialog box
62 auth_digest_expires 10s; # after a successful challenge/response, let the client
63 # continue to use the same nonce for additional requests
64 # for 10 seconds before generating a new challenge
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
65 auth_digest_replays 20; # also generate a new challenge if the client uses the
66 # same nonce more than 20 times before the expire time limit
67 }
258c20ca »
2011-11-04 Initial import
68
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
69 Adding digest authentication to a location will affect any uris that match that block. To
70 disable authentication for specific sub-branches off a uri, set ``auth_digest`` to ``off``::
71
72 location / {
73 auth_digest 'this is not for you';
74 location /pub {
75 auth_digest off; # this sub-tree will be accessible without authentication
258c20ca »
2011-11-04 Initial import
76 }
77 }
78
79 Directives
80 ==========
81
82 auth_digest
83 ~~~~~~~~~~~
5c66278b »
2011-11-04 Typos & cleanup
84 :Syntax: ``auth_digest`` [*realm-name* | ``off``]
85 :Default: ``off``
258c20ca »
2011-11-04 Initial import
86 :Context: server, location
87 :Description:
88 Enable or disable digest authentication for a server or location block. The realm name
89 should correspond to a realm used in the user file. Any user within that realm will be
90 able to access files after authenticating.
91
5c66278b »
2011-11-04 Typos & cleanup
92 To selectively disable authentication within a protected uri hierarchy, set ``auth_digest``
93 to “``off``” within a more-specific location block (see example).
258c20ca »
2011-11-04 Initial import
94
95
96 auth_digest_user_file
97 ~~~~~~~~~~~~~~~~~~~~~
5c66278b »
2011-11-04 Typos & cleanup
98 :Syntax: ``auth_digest_user_file`` */path/to/passwd/file*
258c20ca »
2011-11-04 Initial import
99 :Default: *unset*
100 :Context: server, location
101 :Description:
b4ed5933 »
2011-11-04 Additional links
102 The password file should be of the form created by the apache ``htdigest`` command (or the
103 included `htdigest.py`_ script). Each line of the file is a colon-separated list composed
e3ca7c87 »
2011-11-04 Further detypoification
104 of a username, realm, and md5 hash combining name, realm, and password. For example:
97e643b6 »
2011-11-21 error handling and hash verification fixes
105 ``joi:enfield:ef25e85b34208c246cfd09ab76b01db7``
258c20ca »
2011-11-04 Initial import
106
107 auth_digest_timeout
108 ~~~~~~~~~~~~~~~~~~~
5c66278b »
2011-11-04 Typos & cleanup
109 :Syntax: ``auth_digest_timeout`` *delay-time*
110 :Default: ``60s``
258c20ca »
2011-11-04 Initial import
111 :Context: server, location
112 :Description:
5c66278b »
2011-11-04 Typos & cleanup
113 When a client first requests a protected page, the server returns a 401 status code along with
114 a challenge in the ``www-authenticate`` header.
115
116 At this point most browsers will present a dialog box to the user prompting them to log in. This
117 directive defines how long challenges will remain valid. If the user waits longer than this time
118 before submitting their name and password, the challenge will be considered ‘stale’ and they will
119 be prompted to log in again.
120
258c20ca »
2011-11-04 Initial import
121 auth_digest_expires
122 ~~~~~~~~~~~~~~~~~~~
5c66278b »
2011-11-04 Typos & cleanup
123 :Syntax: ``auth_digest_expires`` *lifetime-in-seconds*
124 :Default: ``10s``
258c20ca »
2011-11-04 Initial import
125 :Context: server, location
126 :Description:
127 Once a digest challenge has been successfully answered by the client, subsequent requests
5c66278b »
2011-11-04 Typos & cleanup
128 will attempt to re-use the ‘nonce’ value from the original challenge. To complicate MitM_
258c20ca »
2011-11-04 Initial import
129 attacks, it's best to limit the number of times a cached nonce will be accepted. This
130 directive sets the duration for this re-use period after the first successful authentication.
131
132 auth_digest_replays
133 ~~~~~~~~~~~~~~~~~~~
e3ca7c87 »
2011-11-04 Further detypoification
134 :Syntax: ``auth_digest_replays`` *number-of-uses*
5c66278b »
2011-11-04 Typos & cleanup
135 :Default: ``20``
258c20ca »
2011-11-04 Initial import
136 :Context: server, location
137 :Description:
138 Nonce re-use should also be limited to a fixed number of requests. Note that increasing this
139 value will cause a proportional increase in memory usage and the shm_size may have to be
140 adjusted to keep up with heavy traffic within the digest-protected location blocks.
141
142 auth_digest_shm_size
143 ~~~~~~~~~~~~~~~~~~~~
5c66278b »
2011-11-04 Typos & cleanup
144 :Syntax: ``auth_digest_shm_size`` *size-in-bytes*
d120601e »
2011-11-18 moved the session cache's cleanup routine into an async timer rather …
145 :Default: ``4096k``
258c20ca »
2011-11-04 Initial import
146 :Context: server
147 :Description:
97e643b6 »
2011-11-21 error handling and hash verification fixes
148 The module maintains a fixed-size cache of active digest sessions to save state between
149 authenticated requests. Once this cache is full, no further authentication will be possible
150 until active sessions expire.
151
152 As a result, choosing the proper size is a little tricky since it depends upon the values set in
153 the expiration-related directives. Each stored challenge takes up ``48 + ceil(replays/8)`` bytes
154 and will live for up to ``auth_digest_timeout + auth_digest_expires`` seconds. When using the
155 default module settings this translates into allowing around 82k non-replay requests every 70
156 seconds.
258c20ca »
2011-11-04 Initial import
157
158 .. _nginx: http://nginx.net
b4ed5933 »
2011-11-04 Additional links
159 .. _module: http://wiki.nginx.org/HttpAuthBasicModule
1cce8374 »
2011-11-23 re{naming,wording}
160 .. _htdigest.py: https://github.com/samizdatco/nginx-http-auth-digest/blob/master/htdigest.py
5c66278b »
2011-11-04 Typos & cleanup
161 .. _RFC: http://www.ietf.org/rfc/rfc2617.txt
162 .. _Digest Authentication: http://en.wikipedia.org/wiki/Digest_access_authentication
1cce8374 »
2011-11-23 re{naming,wording}
163 .. _Issue Tracker: https://github.com/samizdatco/nginx-http-auth-digest/issues
5c66278b »
2011-11-04 Typos & cleanup
164 .. _MitM: http://en.wikipedia.org/wiki/Man-in-the-middle_attack
Something went wrong with that request. Please try again.