Skip to content

Commit

Permalink
auth_db docs: Eliminate references to "HA1b"; Document new columns
Browse files Browse the repository at this point in the history
Credits to Adrian Georgescu for the report!
  • Loading branch information
liviuchircu committed Aug 16, 2021
1 parent 5ba7317 commit b4b24ca
Showing 1 changed file with 64 additions and 27 deletions.
91 changes: 64 additions & 27 deletions modules/auth_db/doc/auth_db_admin.xml
Expand Up @@ -90,36 +90,38 @@ modparam("auth_db", "db_url", "&exampledb;")
<listitem><para><emphasis>1 (calculate HA1)</emphasis> - the loaded
password is a plaintext password, so OpenSIPS will internally
calculate the HA1. As the passwords will be loaded from the column
specified in the <quote>password_column</quote> parameter, be sure
this parameter points to a column holding a plaintext password
(by default, this parameter points to <quote>ha1</quote> column);
specified in the <xref linkend="param_password_column"/> parameter,
be sure this parameter points to a column holding a plaintext password
(by default, this parameter points to the <quote>ha1</quote> column);
</para></listitem>
<listitem><para><emphasis>0 (do NOT calculate HA1)</emphasis> - the
loaded password is an already computed HA1 value, so OpenSIPS does
not have do any further computing (for HA1 value). Depending on
the presence of a <quote>@domain</quote> part (some user agents
append the domain to the username credentials parameter too),
the modules will load the password (pre-computed HA1) from the
<quote>password_column_2</quote> column (if domain present) or from
the <quote>password_column</quote> column (if domain not present).
Usually, most of the UAs do NOT include a domain part in the
username credentials parameter.

<listitem><para><emphasis>0 (do <emphasis role='bold'>not</emphasis>
calculate HA1)</emphasis> - the loaded password is a pre-computed
HA1 hash (no calculation needed). The module will load all hashes
stored in the <xref linkend="param_password_column"/>,
<xref linkend="param_hash_column_sha256"/> and
<xref linkend="param_hash_column_sha512t256"/> columns, then use
the hash corresponding to the hashing algorithm selected for a
given digest authentication challenge.
</para>

<para>
The content of the hash columns can be generated as follows:
<itemizedlist>
<listitem><para>password_column: MD5(username:realm:password)
</para></listitem>
<listitem><para>hash_column_sha256: SHA-256(username:realm:password)
</para></listitem>
<listitem><para>hash_column_sha512t256: SHA-512-256(username:realm:password)
</para></listitem>
</itemizedlist>
</para>

</listitem>
</itemizedlist>
<para>
The <quote>password_column_2</quote> column contains also HA1 strings
but they should be calculated including the domain in the username
parameter (as opposed to password_column which (when containing HA1
strings) should always contain HA1 strings calculated without domain
in username.
</para>
<para>
This ensures that the authentication will always work when using
pre-calculated HA1 strings, not depending on the presence of the
domain in username.
</para>
<para>
Default value of this parameter is 0.
Default value of this parameter is
<emphasis>0 (use hashed passwords)</emphasis>.
</para>
<example>
<title><varname>calculate_ha1</varname> parameter usage</title>
Expand Down Expand Up @@ -249,7 +251,7 @@ modparam("auth_db", "domain_column", "domain")
This is the name of the column in a 'SUBSCRIBER' like table holding
the passwords. Passwords can be
either stored as plain text or pre-calculated HA1 strings. HA1 strings
are MD5 hashes of username, password, and realm. HA1 strings are more
are MD5 hashes of username, password and realm. HA1 strings are more
safe because the server doesn't need to know plaintext passwords and
they cannot be obtained from HA1 strings.
</para>
Expand All @@ -264,6 +266,41 @@ modparam("auth_db", "password_column", "password")
</example>
</section>

<section id="param_hash_column_sha256" xreflabel="hash_column_sha256">
<title><varname>hash_column_sha256</varname> (string)</title>
<para>
The name of the column holding SHA-256 HA1 hashes
(<ulink url="https://datatracker.ietf.org/doc/html/rfc8760">RFC 8760</ulink> support).

</para>
<para>
Default value is <quote>ha1_sha256</quote>.
</para>
<example>
<title><varname>password_column</varname> parameter usage</title>
<programlisting format="linespecific">
modparam("auth_db", "hash_column_sha256", "ha1_sha256")
</programlisting>
</example>
</section>

<section id="param_hash_column_sha512t256" xreflabel="hash_column_sha512t256">
<title><varname>hash_column_sha512t256</varname> (string)</title>
<para>
The name of the column holding SHA-512/256 HA1 hashes.
(<ulink url="https://datatracker.ietf.org/doc/html/rfc8760">RFC 8760</ulink> support).
</para>
<para>
Default value is <quote>ha1_sha512t256</quote>.
</para>
<example>
<title><varname>password_column</varname> parameter usage</title>
<programlisting format="linespecific">
modparam("auth_db", "hash_column_sha512t256", "ha1_sha512t256")
</programlisting>
</example>
</section>

<section id="param_uri_user_column" xreflabel="uri_user_column">
<title><varname>uri_user_column</varname> (string)</title>
<para>
Expand Down

0 comments on commit b4b24ca

Please sign in to comment.