mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
617 lines
19 KiB
617 lines
19 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
|
|
<!-- Auth_db Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This module contains all authentication related functions that need
|
|
the access to the database. This module should be used together with
|
|
auth module, it cannot be used independently because it depends on
|
|
the module. Select this module if you want to use database to store
|
|
authentication information like subscriber usernames and passwords. If
|
|
you want to use radius authentication, then use auth_radius instead.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The module depends on the following modules (in the other words
|
|
the listed modules must be loaded before this module):
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>auth</emphasis> -- Generic authentication
|
|
functions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>database</emphasis> -- Any database module
|
|
(currently mysql, postgres, dbtext)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed
|
|
before running &kamailio; with this module loaded:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>none</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="auth_db.p.db_url">
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
This is URL of the database to be used. Value of the parameter depends
|
|
on the database module used. For example for mysql and postgres modules
|
|
this is something like mysql://username:password@host:port/database.
|
|
For dbtext module (which stores data in plaintext files) it is
|
|
directory in which the database resides.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>&defaultrodb;</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title><varname>db_url</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "db_url", "&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.user_column">
|
|
<title><varname>user_column</varname> (string)</title>
|
|
<para>
|
|
This is the name of the column holding usernames. Default value is
|
|
fine for most people. Use the parameter if you really need to change it.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>username</quote>.
|
|
</para>
|
|
<example>
|
|
<title><varname>user_column</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "user_column", "user")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.domain_column">
|
|
<title><varname>domain_column</varname> (string)</title>
|
|
<para>
|
|
This is the name of the column holding domains of users. Default value
|
|
is fine for most people. Use the parameter if you really need to
|
|
change it.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>domain</quote>.
|
|
</para>
|
|
<example>
|
|
<title><varname>domain_column</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "domain_column", "domain")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.password_column">
|
|
<title><varname>password_column</varname> (string)</title>
|
|
<para>
|
|
This is the name of the column holding 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
|
|
safe because the server doesn't need to know plaintext passwords and
|
|
they cannot be obtained from HA1 strings.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>ha1</quote>.
|
|
</para>
|
|
<example>
|
|
<title><varname>password_column</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "password_column", "password")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.2password_column_2">
|
|
<title><varname>password_column_2</varname> (string)</title>
|
|
<para>
|
|
As described in the previous section this parameter contains name of
|
|
column holding pre-calculated HA1 string that were calculated including
|
|
the domain in the username. This parameter is used only when
|
|
<varname>calculate_ha1</varname> is set to 0 and user agent send a
|
|
credentials containing the domain in the username.
|
|
</para>
|
|
<para>
|
|
Default value of the parameter is ha1b.
|
|
</para>
|
|
<example>
|
|
<title><varname>password_column_2</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "password_column_2", "ha1_2")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.calculate_ha1">
|
|
<title><varname>calculate_ha1</varname> (integer)</title>
|
|
<para>
|
|
This parameter tells the server whether it should use a pre-calculated
|
|
HA1 string or plaintext passwords for authentification.
|
|
</para>
|
|
<para>
|
|
If the parameter is set to 0 and the username parameter of credentials
|
|
contains also <quote>@domain</quote> (some user agents append the
|
|
domain to the username parameter), then the server will use the HA1
|
|
values from the column specified in the
|
|
<quote>password_column_2</quote> parameter. If the username parameter
|
|
doesn't contain a domain, the server will use the HA1 values from the
|
|
column given in the <quote>password_column</quote>parameter.
|
|
</para>
|
|
<para>
|
|
If the parameter is set to 1 then the HA1 value will be calculated
|
|
from the column specified in the <quote>password_column</quote>
|
|
parameter.
|
|
</para>
|
|
<para>
|
|
The <quote>password_column_2</quote>column contain 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 contains 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.
|
|
</para>
|
|
<example>
|
|
<title><varname>calculate_ha1</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "calculate_ha1", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.use_domain">
|
|
<title><varname>use_domain</varname> (integer)</title>
|
|
<para>
|
|
If true (not 0), domain will be also used when looking up in the
|
|
subscriber table. If you have a multi-domain setup, it is strongly
|
|
recommended to turn on this parameter to avoid username overlapping
|
|
between domains.
|
|
</para>
|
|
<para>
|
|
IMPORTANT: before turning on this parameter, be sure that the
|
|
<varname>domain</varname> column in <varname>subscriber</varname>
|
|
table is properly populated.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>0 (false)</quote>.
|
|
</para>
|
|
<example>
|
|
<title><varname>use_domain</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "use_domain", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.load_credentials">
|
|
<title><varname>load_credentials</varname> (string)</title>
|
|
<para>
|
|
This parameter specifies of credentials to be fetch from database when
|
|
the authentication is performed. The loaded credentials will be stored
|
|
in AVPs. If the AVP name is not specificaly given, it will be used a
|
|
NAME AVP with the same name as the column name.
|
|
</para>
|
|
<para>
|
|
Parameter syntax:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>
|
|
load_credentials = credential (';' credential)*
|
|
</emphasis></para></listitem>
|
|
<listitem><para><emphasis>
|
|
credential = (avp_specification '=' column_name) |
|
|
(column_name)
|
|
</emphasis></para></listitem>
|
|
<listitem><para><emphasis>
|
|
avp_specification = '$avp(' + 'i:'ID | 's:'NAME | alias + ')'
|
|
</emphasis></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Default value of this parameter is <quote>NULL</quote> (no credientials
|
|
loaded).
|
|
</para>
|
|
<example>
|
|
<title><varname>load_credentials</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# load rpid column into $avp(i:123) and email_address column
|
|
# into $avp(s:email_address)
|
|
modparam("auth_db", "load_credentials", "$avp(i:123)=rpid;email_address")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.p.version_table">
|
|
<title><varname>version_table</varname> (integer)</title>
|
|
<para>
|
|
If set to 0, the module will skip checking the version
|
|
for subscriber table.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>1 (check for table version)</quote>.
|
|
</para>
|
|
<example>
|
|
<title><varname>version_table</varname> parameter usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("auth_db", "version_table", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="auth_db.f.www_authenticate">
|
|
<title>
|
|
<function moreinfo="none">www_authenticate(realm, table [, method])</function>
|
|
</title>
|
|
<para>
|
|
Name alias: www_authorize(realm, table)
|
|
</para>
|
|
<para>
|
|
The function verifies credentials according to
|
|
<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If the
|
|
credentials are verified successfully then the function will succeed
|
|
and mark the credentials as authorized (marked credentials can be later
|
|
used by some other functions). If the function was unable to verify the
|
|
credentials for some reason then it will fail and the script should
|
|
call <function moreinfo="none">www_challenge</function> which will
|
|
challenge the user again.
|
|
</para>
|
|
<para>Negative codes may be interpreted as follows:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>-1 (generic error)</emphasis> - some generic error
|
|
occurred and no reply was sent out;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-2 (invalid password)</emphasis> - wrong password;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-3 (invalid user)</emphasis> - authentication user does
|
|
not exist.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-4 (nonce expired)</emphasis> - the nonce has expired
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-5 (no credentials)</emphasis> - request does not contain
|
|
an Authorization header with the correct realm.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-6 (nonce reused)</emphasis> - the nonce has already been
|
|
used to authenticate a previous request
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>-8 (authuser mismatch)</emphasis> - depending on the method, th
|
|
From/To/RURI user does not match the authentication user (see auth_check() function).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>realm</emphasis> - Realm is a opaque string that
|
|
the user agent should present to the user so he can decide what
|
|
username and password to use. Usually this is domain of the host
|
|
the server is running on.
|
|
</para>
|
|
<para>
|
|
It must not be empty string <quote></quote>. In case of REGISTER
|
|
requests To header field domain (e.g., variable $td) can be used
|
|
(because this header field represents the user being registered),
|
|
for all other messages From header field domain can be used
|
|
(e.g., variable $fd).
|
|
</para>
|
|
<para>
|
|
The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>table</emphasis> - Table to be used to lookup
|
|
usernames and passwords (usually subscribers table).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>method</emphasis> - the method to be used for
|
|
authentication. This parameter is optional and if not set
|
|
is the first "word" on the request-line.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function moreinfo="none">www_authorize</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!www_authorize("kamailio.org", "subscriber")) {
|
|
www_challenge("kamailio.org", "1");
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.f.www_authorize">
|
|
<title>
|
|
<function moreinfo="none">www_authorize(realm, table)</function>
|
|
</title>
|
|
<para>
|
|
It is same function as www_authenticate(realm, table). This name
|
|
is kept for backward compatibility, since it was named this way
|
|
first time by it actually does user authentication.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="auth_db.f.proxy_authenticate">
|
|
<title>
|
|
<function moreinfo="none">proxy_authenticate(realm, table)</function>
|
|
</title>
|
|
<para>
|
|
Name alias: proxy_authorize(realm, table)
|
|
</para>
|
|
<para>
|
|
The function verifies credentials according to
|
|
<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If
|
|
the credentials are verified successfully then the function will
|
|
succeed and mark the credentials as authorized (marked credentials can
|
|
be later used by some other functions). If the function was unable to
|
|
verify the credentials for some reason then it will fail and
|
|
the script should call
|
|
<function moreinfo="none">proxy_challenge</function> which will
|
|
challenge the user again.
|
|
</para>
|
|
<para>Negative return codes have the same meaning as for
|
|
www_authenticate().</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>realm</emphasis> - Realm is a opaque string that
|
|
the user agent should present to the user so he can decide what
|
|
username and password to use. Usually this is domain of the host
|
|
the server is running on.
|
|
</para>
|
|
<para>
|
|
It must not be empty string <quote></quote>. Apart of a static
|
|
string, typical value is From header field domain
|
|
(e.g., variable $fd).
|
|
</para>
|
|
<para>
|
|
If an empty string <quote></quote> is used then the server will
|
|
generate it from the request. From header field domain will be
|
|
used as realm.
|
|
</para>
|
|
<para>
|
|
The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>table</emphasis> - Table to be used to lookup
|
|
usernames and passwords (usually subscribers table).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>proxy_authorize usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!proxy_authorize("$fd", "subscriber)) {
|
|
proxy_challenge("$fd", "1"); # Realm will be autogenerated
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="auth_db.f.proxy_authorize">
|
|
<title>
|
|
<function moreinfo="none">proxy_authorize(realm, table)</function>
|
|
</title>
|
|
<para>
|
|
It is same function as proxy_authenticate(realm, table). This name
|
|
is kept for backward compatibility, since it was named this way
|
|
first time but it actually does user authentication.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="auth_db.f.auth_check">
|
|
<title>
|
|
<function moreinfo="none">auth_check(realm, table, flags)</function>
|
|
</title>
|
|
<para>The function combines the functionalities of
|
|
<function moreinfo="none">www_authenticate</function> and
|
|
<function moreinfo="none">proxy_authenticate</function>, first being
|
|
exectuted if the SIP request is a REGISTER, the second for the rest.
|
|
</para>
|
|
<para>
|
|
In addition, a matter of <emphasis>flags</emphasis> parameter value,
|
|
the function checks if authentication username matches From/To header
|
|
username, and Request-URI in case of PUBLISH.
|
|
</para>
|
|
<para>Negative return codes have the same meaning as for
|
|
www_authenticate().</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>realm</emphasis> - Realm is a opaque string that
|
|
the user agent should present to the user so he can decide what
|
|
username and password to use. Usually this is domain of the host
|
|
the server is running on.
|
|
</para>
|
|
<para>
|
|
It must not be empty string <quote></quote>. Apart of a static
|
|
string, typical value is From header field domain
|
|
(e.g., variable $fd).
|
|
</para>
|
|
<para>
|
|
The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>table</emphasis> - Table to be used to lookup
|
|
usernames and passwords (usually subscribers table).
|
|
</para>
|
|
<para>
|
|
The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>flags</emphasis> - set of flags to control the
|
|
behaviour of the function. If it is 1, then the function will
|
|
check to see if the authentication username matches either To or
|
|
From header username. REGISTER requests: From and To must match the
|
|
authentication user. PUBLISH requests: From, To and Request-URI must
|
|
match the authentication user. All other requests: From header must
|
|
match the authentication user. If bit 2 is set as well (flags==3),
|
|
the ID check is skipped for INVITE, BYE, PRACK, UPDATE, MESSAGE
|
|
- these requests can come with anonymoys caller id.
|
|
</para>
|
|
<para>
|
|
Additionally all domains in the checked URIs and the realm in the
|
|
authentication header will be checked to match the provided realm parameter.
|
|
</para>
|
|
<para>
|
|
The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>auth_check usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!auth_check("$fd", "subscriber", "1")) {
|
|
auth_challenge("$fd", "1");
|
|
exit;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title id="auth_db.f.is_subscriber">
|
|
<function moreinfo="none">is_subscriber(uri, dbtable, flags)</function>
|
|
</title>
|
|
<para>The function checks if there is a subscriber corresponding to
|
|
the AoR in uri parameter. It uses same database connection as for
|
|
authentication functions.
|
|
</para>
|
|
<para>
|
|
In addition, if the subscriber record is found, then the load_credentials
|
|
attributes are loaded. An use case can be loading the credential attributes
|
|
for callee.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>uri</emphasis> - a valid SIP URI value to identify
|
|
the subscriber. The string may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>dbtable</emphasis> - Table to be used to lookup
|
|
username and domain from URI (usually subscriber table). The string
|
|
may contain pseudo variables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>flags</emphasis> - set of flags to control the
|
|
behaviour of the function. If 1st bit is set, then the function will
|
|
use the domain part of the URI to perform the database table search.
|
|
If 2nd bit is set, then the credentials are not loaded in variables
|
|
(a simple check if subscriber exists).
|
|
</para>
|
|
<para>
|
|
The parameter may be a pseudo variable.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>is_subscriber usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!is_subscriber("$ru", "subscriber", "3")) {
|
|
# callee is not a local subscriber
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
</chapter>
|
|
|