kamailio/modules_s/permissions/doc/permissions.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="permissions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Miklos</firstname>
		<surname>Tirpak</surname>
		<address>
		    <email>mtirpak@sztaki.hu</email>
		</address>
	    </author>
	    <author>
		<firstname>Juha</firstname>
		<surname>Heinanen</surname>
		<address>
		    <email>jh@tutpro.com</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2003</year>
	    <holder>Miklos Tirpak</holder>
	    <holder>Juha Heinanen</holder>
	    <year>2006</year>
	    <holder>iptelorg GmbH</holder>
	</copyright>
    </sectioninfo>

    <title>Permissions Module</title>

    <section id="permissions.overview">
	<title>Overview</title>
	<section id="call_routing">
	    <title>Call Routing</title>
	    <para>
		The module can be used to determine if a call has appropriate
		permission to be established. Permission rules are stored in
		plaintext configuration files similar to
		<filename>hosts.allow</filename> and
		<filename>hosts.deny</filename> files used by tcpd.
	    </para>
	    <para>
		When <function>allow_routing</function> function is called it
		tries to find a rule that matches selected fields of the
		message.
	    </para>
	    <para>
		SER is a forking proxy and therefore a single message can be
		sent to different destinations simultaneously. When checking
		permissions all the destinations must be checked and if one of
		them fails, the forwarding will fail.
	    </para>
	    <para>
		The matching algorithm is as follows, first match wins:
	    </para>
	    <itemizedlist>
		<listitem>
		    <para>
			Create a set of pairs of form (From, R-URI of branch
			1), (From, R-URI of branch 2), etc.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Routing will be allowed when all pairs match an entry
			in the allow file.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Otherwise routing will be denied when one of pairs
			matches an entry in the deny file.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Otherwise, routing will be allowed.
		    </para>
	    </listitem>
	    </itemizedlist>
	    <para>
		A non-existing permission control file is treated as if it were
		an empty file. Thus, permission control can be turned off by
		providing no permission control files.
	    </para>
	    <para>
		From header field and Request-URIs are always compared with
		regular expressions! For the syntax see the sample file:
		<filename>config/permissions.allow</filename>.
	    </para>
	</section>
	<section id="registration_permissions">
	    <title>Registration Permissions</title>
	    <para>
		In addition to call routing it is also possible to check
		REGISTER messages and decide--based on the configuration
		files--whether the message should be allowed and the
		registration accepted or not.
	    </para>
	    <para>
		Main purpose of the function is to prevent registration of
		"prohibited" IP addresses. One example, when a malicious user
		registers a contact containing IP address of a PSTN gateway, he
		might be able to bypass authorization checks performed by the
		SIP proxy. That is undesirable and therefore attempts to
		register IP address of a PSTN gateway should be rejected. Files
		<filename>config/register.allow</filename> and
		<filename>config/register.deny</filename>
		contain an example configuration.
	    </para>
	    <para>
		Function for registration checking is called
		<function>allow_register</function> and the algorithm is very
		similar to the algorithm described in <xref
		linkend="call_routing"/>. The only difference is in the way how
		pairs are created.
	    </para>
	    <para>
		Instead of From header field the function uses To header field because To header
		field in REGISTER messages contains the URI of the person being registered. Instead
		of the Request-URI of branches the function uses Contact header field.
	    </para>
	    <para>
		Thus, pairs used in matching will look like this: (To, Contact 1), (To, Contact
		2), (To, Contact 3), and so on..
	    </para>
	    <para>
		The algorithm of matching is same as described in <xref linkend="call_routing"/>.
	    </para>
	</section>
	<section id="refer_to_permissions">
	    <title>Refer-To Permissions</title>
	    <para>
		In addition to call routing and REGISTER it is also possible to check
		REFER messages and decide--based on the configuration files--
		whether or not the message should be accepted for forwarding.
	    </para>
	    <para>
		Main purpose of the function is to prevent referring a SIP UA to
		"prohibited" IP addresses. One example is user sending a REFER
		request to PSTN gateway trying to refer it to an expensive phone
		number.
	    </para>
	    <para>
		Function for Refer-To checking is called allow_refer_to
		and the algorithm is very similar to the algorithm described
		in Section 1.1.1. The only difference is in the way how pairs
		are created.
	    </para>
	    <para>
		Instead of Request-URI the function uses Refer-To header field
		because Refer-To header field in REFER messages contains the URI
   		to which the UA is being referred to.  The algorithm of matching is
		same as described in Section 1.1.1.
	    </para>
	</section>
	<section id="Messages catching">
	    <title>Messages catching</title>
	    <para>
		The module can be also used for catching messages coming from
		or going to specific network elements, for example gateways or
		peering partners.
	    </para>
	    <para>
		Users can register or forward the calls to the address of
		a gateway resulting unauthorized access to them. Such calls
		must be catched and dropped, see ipmatch functions for details.
	    </para>
	</section>
    </section>
    
    <xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>
    <xi:include href="xmlrpc.xml"/>

</section>