<?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>

