Skip to content

docs: add pre-built Ubuntu/Debian package installation instructions #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvershinin wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add pre-built Ubuntu/Debian package installation instructions #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 40 additions & 15 deletions readme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,37 @@ Nginx Digest Authentication module
Changes from other forks
========================
Bug fixes
`1 <https://github.com/samizdatco/nginx-http-auth-digest/commit/9d77dcc58420d5afb8aa5a8138b1bf22a1933dd6>`_,
`1 <https://github.com/samizdatco/nginx-http-auth-digest/commit/9d77dcc58420d5afb8aa5a8138b1bf22a1933dd6>`_,
`2 <https://github.com/samizdatco/nginx-http-auth-digest/commit/b98725d3d0506c895f6a9f9d38f9168d499275fc>`_,
`3 <https://github.com/samizdatco/nginx-http-auth-digest/commit/47d5bac13cf071b4dbe81048b0f12a742ba512ae>`_

`Added log message for invalid login attempts <https://github.com/samizdatco/nginx-http-auth-digest/commit/9a402045082291c1f2f0a432ac24475277e2d176>`_


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 <https://apt-nginx-extras.getpagespeed.com/apt-setup/>`_.


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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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*
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down