# HG changeset patch
# User Maxim Dounin <mdounin@mdounin.ru>
# Date 1725070765 -10800
# Node ID aea3e104f11deba904f88166ddd1befe79621ec1
# Parent  f7e9bd7de0f9a4fbb476b4a6217de3bb55cdaa7b
Reworked auth_basic_user_file documentation.

Some extra details about crypt(3) are provided, emphasizing modular
crypt() usage and commonly available password hashing methods.  Also,
added some examples on how to use "openssl passwd" to generate password
hashes, made it clear that {SSHA} passwords are not secure now, and
added a note about passwords being validated on each request.

diff -r f7e9bd7de0f9 -r aea3e104f11d xml/en/docs/http/ngx_http_auth_basic_module.xml
--- a/xml/en/docs/http/ngx_http_auth_basic_module.xml	Tue Aug 13 17:45:23 2024 +0300
+++ b/xml/en/docs/http/ngx_http_auth_basic_module.xml	Sat Aug 31 05:19:25 2024 +0300
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_auth_basic_module"
         link="/en/docs/http/ngx_http_auth_basic_module.html"
         lang="en"
-        rev="11">
+        rev="12">
 
 <section id="summary">
 
@@ -89,18 +89,37 @@
 </para>
 
 <para>
-The following password types are supported:
+Passwords are expected to be encrypted by the
+<link url="https://en.wikipedia.org/wiki/Crypt_(C)">crypt() function</link>.
+All password hashing methods as supported by the OS can be used.
+In particular, the following <c-func>crypt</c-func> hashing methods are
+commonly available:
+
 <list type="bullet">
 
 <listitem>
-encrypted with the <c-func>crypt</c-func> function; can be generated using
-the “<command>htpasswd</command>” utility from the Apache HTTP Server
-distribution or the “<command>openssl passwd</command>” command;
+MD5-based <c-func>crypt</c-func> method, <literal>$1$</literal>;
+</listitem>
+
+<listitem>
+SHA256-based <c-func>crypt</c-func> method, <literal>$5$</literal>;
 </listitem>
 
 <listitem>
-hashed with the Apache variant of the MD5-based password algorithm (apr1);
-can be generated with the same tools;
+SHA512-based <c-func>crypt</c-func> method, <literal>$6$</literal>.
+</listitem>
+
+</list>
+</para>
+
+<para>
+Additionally, the following cross-platform password types are supported:
+
+<list type="bullet">
+
+<listitem>
+hashed with the Apache variant of the MD5-based <c-func>crypt</c-func>
+method (<literal>$apr1$</literal>);
 </listitem>
 
 <listitem>
@@ -108,23 +127,36 @@
 “<literal>{</literal><value>scheme</value><literal>}</literal><value>data</value>”
 syntax (1.0.3+) as described in
 <link url="https://datatracker.ietf.org/doc/html/rfc2307#section-5.3">RFC 2307</link>;
-currently implemented schemes include <literal>PLAIN</literal> (an example one,
-should not be used), <literal>SHA</literal> (1.3.13) (plain SHA-1
-hashing, should not be used) and <literal>SSHA</literal> (salted SHA-1 hashing,
-used by some software packages, notably OpenLDAP and Dovecot).
-<note>
-Support for <literal>SHA</literal> scheme was added only to aid
-in migration from other web servers.
-It should not be used for new passwords, since unsalted SHA-1 hashing
-that it employs is vulnerable to
-<link url="http://en.wikipedia.org/wiki/Rainbow_attack">rainbow table</link>
-attacks.
-</note>
+supported schemes are
+<literal>PLAIN</literal> (an example one, should not be used),
+<literal>SHA</literal> (1.3.13) (plain SHA-1 hashing,
+insecure and should not be used),
+and <literal>SSHA</literal> (salted SHA-1 hashing,
+also insecure by today's standards).
 </listitem>
 
 </list>
 </para>
 
+<para>
+Password hashes for common hashing methods can be generated using
+the “<command>openssl passwd</command>” command, for example:
+
+<example>
+$ openssl passwd -apr1 secret
+$apr1$x/muFo1c$zwUN24M2TEq.6wg0AZacn0
+</example>
+<example>
+$ openssl passwd -6 secret
+$6$FjZ1ss8ytcGmrGFY$1fopTJLuLUGCRlv2YcRPIsZk9uaD9NBOGcKsUay/BLV3RR1ol0ONS08oPTVqA4XBkZ44M7OL4K6NjP9xPKShP0
+</example>
+</para>
+
+<para>
+Note that HTTP Basic Authentication implies password validation on each
+request, and password hashing method should be choosen with this in mind.
+</para>
+
 </directive>
 
 </section>
diff -r f7e9bd7de0f9 -r aea3e104f11d xml/ru/docs/http/ngx_http_auth_basic_module.xml
--- a/xml/ru/docs/http/ngx_http_auth_basic_module.xml	Tue Aug 13 17:45:23 2024 +0300
+++ b/xml/ru/docs/http/ngx_http_auth_basic_module.xml	Sat Aug 31 05:19:25 2024 +0300
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_auth_basic_module"
         link="/ru/docs/http/ngx_http_auth_basic_module.html"
         lang="ru"
-        rev="11">
+        rev="12">
 
 <section id="summary">
 
@@ -89,18 +89,35 @@
 </para>
 
 <para>
-Поддерживаются следующие типы паролей:
+Пароли должны быть зашифрованы
+<link url="https://ru.wikipedia.org/wiki/Crypt_(C)">функцией crypt()</link>.
+Доступны все методы хэширования паролей, поддерживаемые операционной системой.
+В частности, распространены следующие методы хэширования:
+
 <list type="bullet">
 
 <listitem>
-зашифрованные функцией <c-func>crypt</c-func>; могут быть созданы
-с помощью утилиты “<command>htpasswd</command>” из дистрибутива HTTP-сервера
-Apache или команды “<command>openssl passwd</command>”;
+основанный на MD5 метод, <literal>$1$</literal>;
+</listitem>
+
+<listitem>
+основанный на SHA256 метод, <literal>$5$</literal>;
 </listitem>
 
 <listitem>
-хэшированные с помощью алгоритма, основанного на MD5, по версии Apache (apr1);
-могут быть созданы теми же инструментами;
+основанный на SHA512 метод, <literal>$6$</literal>.
+</listitem>
+
+</list>
+</para>
+
+<para>
+Кроме того, поддерживаются следующие кросс-платформенные типы паролей:
+<list type="bullet">
+
+<listitem>
+хэшированные с помощью основанного на MD5 метода по версии Apache
+(<literal>$apr1$</literal>);
 </listitem>
 
 <listitem>
@@ -111,20 +128,31 @@
 в настоящий момент реализованы схемы <literal>PLAIN</literal> (в качестве
 примера, не следует применять), <literal>SHA</literal> (1.3.13) (простое SHA-1
 хэширование, не следует применять) и <literal>SSHA</literal> (SHA-1 хэширование
-с солью, используется в некоторых программах, в частности OpenLDAP
-и Dovecot).
-<note>
-Поддержка схемы <literal>SHA</literal> была добавлена лишь для облегчения
-процесса миграции файлов паролей с других веб-серверов.
-Её не следует применять для новых паролей, т.к. используемое при этом
-SHA-1 хэширование без соли уязвимо к взлому при помощи
-<link url="http://en.wikipedia.org/wiki/Rainbow_attack">радужных таблиц</link>.
-</note>
+с солью, также небезопасно по современным стандартам).
 </listitem>
 
 </list>
 </para>
 
+<para>
+Хэши паролей для распространнённых методов хэширования могут быть сгенерированы
+с помощью команды “<command>openssl passwd</command>”, например:
+
+<example>
+$ openssl passwd -apr1 secret
+$apr1$x/muFo1c$zwUN24M2TEq.6wg0AZacn0
+</example>
+<example>
+$ openssl passwd -6 secret
+$6$FjZ1ss8ytcGmrGFY$1fopTJLuLUGCRlv2YcRPIsZk9uaD9NBOGcKsUay/BLV3RR1ol0ONS08oPTVqA4XBkZ44M7OL4K6NjP9xPKShP0
+</example>
+</para>
+
+<para>
+При выборе метода хэширования паролей следует учитывать, что
+HTTP Basic Authentication подразумевает проверку пароля при каждом запросе.
+</para>
+
 </directive>
 
 </section>