diff --git a/readme.rst b/readme.rst index 9f55260..8f3b28e 100644 --- a/readme.rst +++ b/readme.rst @@ -5,12 +5,37 @@ Nginx Digest Authentication module Changes from other forks ======================== Bug fixes -`1 `_, +`1 `_, `2 `_, `3 `_ `Added log message for invalid login attempts `_ + +Pre-built Packages +================== + +Ubuntu / Debian +--------------- + +Pre-built packages for this module are freely available from the GetPageSpeed repository:: + + # Install the repository keyring + sudo install -d -m 0755 /etc/apt/keyrings + curl -fsSL https://extras.getpagespeed.com/deb-archive-keyring.gpg \ + | sudo tee /etc/apt/keyrings/getpagespeed.gpg >/dev/null + + # Add the repository (Ubuntu example - replace 'ubuntu' and 'jammy' for your distro) + echo "deb [signed-by=/etc/apt/keyrings/getpagespeed.gpg] https://extras.getpagespeed.com/ubuntu jammy main" \ + | sudo tee /etc/apt/sources.list.d/getpagespeed-extras.list + + # Install nginx and the module + sudo apt-get update + sudo apt-get install nginx nginx-module-auth-digest + +The module is automatically enabled after installation. Supported distributions include Debian 12/13 and Ubuntu 20.04/22.04/24.04 (both amd64 and arm64). See `the complete setup instructions `_. + + Description =========== 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. @@ -60,7 +85,7 @@ a ``server`` section in your Nginx_ configuration file:: } -The other directives control the lifespan defaults for the authentication session. The +The other directives control the lifespan defaults for the authentication session. The following is equivalent to the previous example but demonstrates all the directives:: auth_digest_user_file /opt/httpd/conf/passwd.digest; @@ -99,23 +124,23 @@ auth_digest 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 ``auth_digest`` + + To selectively disable authentication within a protected uri hierarchy, set ``auth_digest`` to “``off``” within a more-specific location block (see example). - - + + auth_digest_user_file ~~~~~~~~~~~~~~~~~~~~~ :Syntax: ``auth_digest_user_file`` */path/to/passwd/file* :Default: *unset* :Context: server, location :Description: - The password file should be of the form created by the apache ``htdigest`` command (or the - included `htdigest.py`_ script). Each line of the file is a colon-separated list composed + The password file should be of the form created by the apache ``htdigest`` command (or the + included `htdigest.py`_ 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`` This file needs to be readable by your nginx user! - + auth_digest_timeout ~~~~~~~~~~~~~~~~~~~ :Syntax: ``auth_digest_timeout`` *delay-time* @@ -124,19 +149,19 @@ auth_digest_timeout :Description: When a client first requests a protected page, the server returns a 401 status code along with a challenge in the ``www-authenticate`` 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: ``10s`` :Context: server, location :Description: - Once a digest challenge has been successfully answered by the client, subsequent requests + 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. @@ -176,10 +201,10 @@ auth_digest_shm_size :Default: ``4096k`` :Context: server :Description: - The module maintains a fixed-size cache of active digest sessions to save state between + 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. - + 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 ``48 + ceil(replays/8)`` bytes and will live for up to ``auth_digest_timeout + auth_digest_expires`` seconds. When using the