<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>


	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		UAC (User Agent Client) module provides some basic UAC
		functionalities like FROM / TO header manipulation (anonymization)
		or client authentication.
		</para>
		<para>
		If the dialog module is loaded and a dialog can be created, 
		then the auto mode can be done more efficiently.
		</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
		<title>Dependencies</title>
		<section>
			<title>&osips; Modules</title>
			<para>
			The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>TM - Transaction Module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>RR - Record-Route Module</emphasis>, but only if
				restore mode for FROM URI is set to <quote>auto</quote>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>UAC_AUTH - UAC Authentication Module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>Dialog Module</emphasis>, if <quote>force_dialog</quote>
				module parameter is enabled, or a dialog is created from the
				configuration script.
			</para>
			</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
				The following libraries or applications must be installed 
				before running &osips; with this module loaded:
				<itemizedlist>
				<listitem>
				<para>
					<emphasis>None</emphasis>
				</para>
				</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
	
		<section id="param_restore_mode" xreflabel="restore_mode">
			<title><varname>restore_mode</varname> (string)</title>
			<para>
			There are 3 mode of restoring the original headers (FROM/TO) URI:
			<itemizedlist>
			<listitem>
				<para>
				<quote>none</quote> - no information about original URI is 
				stored; restoration is not possible.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>manual</quote> - all following replies will be restored,
				except for the sequential requests - these must be manually 
				updated based on original URI.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>auto</quote> - all sequential requests and replies will 
				be automatically updated based on stored original URI.
				</para>
			</listitem>
			</itemizedlist>
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default value being 
					<quote>auto</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>restore_mode</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("uac","restore_mode","auto")
...
				</programlisting>
			</example>
		</section>

		<section id="param_restore_passwd" xreflabel="restore_passwd">
			<title><varname>restore_passwd</varname> (string)</title>
			<para>
			String password to be used to encrypt the RR storing parameter
			(when replacing the TO/FROM headers). If empty, no encryption 
			will be used.
			</para>
			<para>
				<emphasis>
					Default value of this parameter is empty.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>restore_passwd</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac","restore_passwd","my_secret_passwd")
...
				</programlisting>
			</example>
		</section>

		<section id="param_rr_from_store_param" xreflabel="rr_from_store_param">
			<title><varname>rr_from_store_param</varname> (string)</title>
			<para>
			Name of Record-Route header parameter that will be used to store 
			(encoded) the original FROM URI.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default value being 
					<quote>vsf</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>rr_from_store_param</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac","rr_from_store_param","my_Fparam")
...
				</programlisting>
				</example>
		</section>

		<section id="param_rr_to_store_param" xreflabel="rr_to_store_param">
			<title><varname>rr_to_store_param</varname> (string)</title>
			<para>
			Name of Record-Route header parameter that will be used to store 
			(encoded) the original TO URI.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default value being 
					<quote>vst</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>rr_to_store_param</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac","rr_to_store_param","my_Tparam")
...
				</programlisting>
			</example>
		</section>

		<section id="param_force_dialog" xreflabel="force_dialog">
			<title><varname>force_dialog</varname> (int)</title>
			<para>
				Force create dialog if it is not created from the configuration script.
			</para>
			<para>
				Default value is no.
			</para>
			<example>
				<title>Set <varname>force_dialog</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac", "force_dialog", yes)
...
				</programlisting>
			</example>
		</section>
	</section>


	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>

		<section id="func_uac_replace_from" xreflabel="uac_replace_from()">
			<title>
				<function moreinfo="none">uac_replace_from([display],uri)</function>
				<function moreinfo="none">uac_replace_to([display],uri)</function>
			</title>
			<para>
			Replace in FROM/TO header the <emphasis>display</emphasis> name or/and
			the <emphasis>URI</emphasis> part.
			</para>
			<para>
			Both parameters are string. The <emphasis>display</emphasis> is optional.
			If missing, only the URI will be changed in the message.
			</para>
			<para>
			IMPORTANT: calling the function more than once per branch will lead
			to inconsistent changes over the request.Be sure you do the change
			only ONCE per branch. Note that calling the function from REQUEST
			ROUTE affects all the branches!, so no other change will be 
			possible in the future. For per branch changes use BRANCH and 
			FAILURE route.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
			FAILURE_ROUTE.
			</para>
			<example>
				<title><function>uac_replace_from</function>/<function>uac_replace_to</function> usage</title>
				<programlisting format="linespecific">
...
# replace both display and uri
uac_replace_from($avp(display),$avp(uri));
# replace only display and do not touch uri
uac_replace_from("batman","");
# remove display and replace uri
uac_replace_from("","sip:robin@gotham.org");
# remove display and do not touch uri
uac_replace_from("","");
# replace the URI without touching the display
uac_replace_from( , "sip:batman@gotham.org");
...
				</programlisting>
			</example>
		</section>

		<section id="func_uac_restore_from" xreflabel="uac_restore_from()">
			<title>
				<function moreinfo="none">uac_restore_from()</function>
				<function moreinfo="none">uac_restore_to()</function>
			</title>
			<para>
			This function will check if the FROM/TO URI was modified and will
			use the information stored in header parameter to restore
			the original FROM/TO URI value.
			</para>
			<para>
			NOTE - this function should be used only if you configured MANUAL
			restoring of the headers (see restore_mode param). For AUTO 
			and NONE, there is no need to use this function.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
				<title><function>uac_restore_from</function>/<function>uac_restore_to</function> usage</title>
				<programlisting format="linespecific">
...
uac_restore_from();
...
				</programlisting>
			</example>
		</section>

		<section id="func_uac_auth" xreflabel="uac_auth([algs])">
			<title>
				<function moreinfo="none">uac_auth()</function>
			</title>
			<para>
			This function can be called only from failure route and will 
			build the authentication response header and insert it into the
			request without sending anything.
			Credentials for buiding the authentication response will be taken
			from the list of credentials provided by the uac_auth module (static
			or via AVPs).
			</para>
			<para>
			As optional parameter, the function may receive a list of auth
			algorithms to be considered / supported during authentication:
			</para>
			<itemizedlist>
			<listitem>
				<para>MD5, MD5-sess</para>
			</listitem>
			<listitem>
				<para>SHA-256, SHA-256-sess (may be missing, depends on lib support)</para>
			</listitem>
			<listitem>
				<para>SHA-512-256, SHA-512-256-sess (may be missing, depends on lib support)</para>
			</listitem>
			</itemizedlist>
			<para>
			Note that the CSeq is automatically increased during authentication.
			</para>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<para>
				<emphasis>NOTE: </emphasis> when used without dialog support, the
				<emphasis>uac_auth()</emphasis> function cannot be used for authenticating
				in-dialog requests, as there is no mechanism to store the CSeq changes that
				are required for ensuring the correctness of the dialog. The only exception are
				<emphasis>BYE</emphasis> messages, which are the last messages within a call,
				hence no further adjustments are needed. The function can still be used for
				authenticating the initial INVITE though.
			</para>
			<example>
				<title><function>uac_auth</function> usage</title>
				<programlisting format="linespecific">
...
uac_auth();
...
failure_route[check_auth] {
    ...
    if ($T_reply_code==407) {
        if (uac_auth("MD5,MD5-sess")) {
            # auth is succesful, just relay
            t_relay();
            exit;
        }
        # auth failed (no credentials maybe)
        # so continue handling the 407 reply
    }
    ...
}
...
				</programlisting>
			</example>
		</section>

		<section id="func_uac_inc_cseq" xreflabel="uac_inc_cseq(cseq)">
			<title>
				<function moreinfo="none">uac_inc_cseq()</function>
			</title>
			<para>
			This function can be called to increase the CSeq of an ongoing request.
			</para>
			<para>
			It receives as the <emphasis>cseq</emphasis> parameter the value that
			the CSeq should be incremented with.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and  FAILURE_ROUTE.
			</para>
			<example>
				<title><function>uac_inc_cseq</function> usage</title>
				<programlisting format="linespecific">
...
uac_inc_cseq(1);
...
				</programlisting>
			</example>
		</section>
	</section>

</chapter>

