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

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

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para> Peering module allows SIP
	providers (operators or organizations) to verify from a broker
	if source or destination of a SIP request is a trusted peer.
        </para>
        <para>
	In order to participate in the trust community provided by a
	broker, each SIP provider registers with the broker the domains
	(host parts of SIP URIs) that they serve.  When a SIP proxy of a
	provider needs to send a SIP request to a non-local domain, it
	can find out from the broker using verify_destination() function
	if the non-local domain is served by a trusted peer.  If so, the
	provider receives from the broker a hash of the SIP request and
	a timestamp that it includes in the request to the non-local
	domain.  When a SIP
	proxy of the non-local domain receives the SIP request, it, in
	turn, can verify from the broker using verify_source() function
	if the request came from a trusted peer.
        </para>
        <para>
        Verification functions communicate with the broker using an AAA
        protocol.  
        </para>

        <para>
        Comments and suggestions for improvements are welcome.
        </para>

	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
		<section>
		<title>&osips; 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>an AAA implementing module</emphasis></para>
				</listitem>
			</itemizedlist>
			</para>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_aaa_url" xreflabel="aaa_url">
		<title><varname>aaa_url</varname> (string)</title>
		<para>
		This is the url representing the AAA protocol used and the location of the configuration file of this protocol.
		</para>
		<para>
			If the parameter is set to empty string, the AAA accounting support
			will be disabled (even if compiled).
		</para>
		<para>
		Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title>Set <varname>aaa_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("peering", "aaa_url", "radius:/etc/radiusclient-ng/radiusclient.conf")
...
</programlisting>
		</example>
	</section>
	<section id="param_verify_destination_service_type" xreflabel="verify_destination_service_type">
		<title><varname>verify_destination_service_type</varname> (integer)</title>
		<para>
		This is the value of the Service-Type AAA attribute to be
		used, when sender of SIP Request verifies request's
	destination using verify_destination() function.
		</para>
		<para>
		Default value is dictionary value of <quote>Sip-Verify-Destination</quote>
		Service-Type.
		</para>
		<example>
		<title><varname>verify_destination_service_type</varname> parameter usage</title>
		<programlisting format="linespecific">
...
modparam("peering", "verify_destination_service_type", 21)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>verify_source_service_type</varname> (integer)</title>
		<para>
		This is the value of the Service-Type AAA attribute to be
		used, when receiver of SIP Request verifies request's
	source using verify_source() function.
		</para>
		<para>
		Default value is dictionary value of <quote>Sip-Verify-Source</quote>
		Service-Type.
		</para>
		<example>
		<title><varname>verify_source_service_type</varname> parameter usage</title>
		<programlisting format="linespecific">
...
modparam("peering", "verify_source_service_type", 22)
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_verify_destination" xreflabel="verify_destination()">
		<title><function moreinfo="none">verify_destination()</function></title>
		<para>
		Function verify_destination() queries from
		broker's AAA server if domain (host part) of Request
	URI is served by a trusted peer.  AAA request contains the
	following attributes/values:
		</para>
		<itemizedlist>
		<listitem>
			<para>User-Name - Request-URI host</para>
		</listitem>
		<listitem>
			<para>SIP-URI-User - Request-URI user</para>
		</listitem>
		<listitem>
			<para>SIP-From-Tag - From tag</para>
		</listitem>
		<listitem>
			<para>SIP-Call-Id - Call id</para>
		</listitem>
		<listitem>
			<para>Service-Type - verify_destination_service_type</para>
		</listitem>
		</itemizedlist>
		<para>
		Function returns value 1 if domain of Request URI is
	served by a trusted peer and -1 otherwise.  In case of positive
	result, AAA server returns a set of SIP-AVP reply attributes.
	Value of each SIP-AVP is of form:
		 </para>
		 <para>
		 [#]name(:|#)value
		 </para>
		 <para>
		 Value of each SIP-AVP reply attribute is mapped to an
		 OpenSIPS AVP.  Prefix # in front of name or value indicates a
	string name or string value, respectively.
		 </para>
		 <para>
		 One of the SIP-AVP reply attributes contains a string
		 that the source peer must include "as is" in a 
		 P-Request-Hash header when it sends the SIP request to
		 the destination peer.  The string value may, for
		 example, be of form hash@timestamp, where hash contains
		 a hash calculated by the broker based on the attributes
		 of the query and some local information and timestamp
		 is the time when the calculation was done.
		 </para>
		 <para>
		 AVP names used in reply attributes are assigned by the
		 broker.
		 </para>
		<para>
		This function can be used from REQUEST_ROUTE and
		FAILURE_ROUTE.
		</para>
		<example>
		<title><function
	moreinfo="none">verify_destination()</function> usage</title> 
		<programlisting format="linespecific">
...
if (verify_destination()) {
   append_hf("P-Request-Hash: $avp(prh)\r\n");
}
...
</programlisting>
		</example>
	</section>
	<section id="func_verify_source" xreflabel="verify_source()">
		<title><function moreinfo="none">verify_source()</function></title>
		<para>
		Function verify_source() queries from
		broker's AAA server if SIP request was received from
	a trusted peer.  AAA request contains the
	following attributes/values:
		</para>
		<itemizedlist>
		<listitem>
			<para>User-Name - Request-URI host</para>
		</listitem>
		<listitem>
			<para>SIP-URI-User - Request-URI user</para>
		</listitem>
		<listitem>
			<para>SIP-From-Tag - From tag</para>
		</listitem>
		<listitem>
			<para>SIP-Call-Id - Call id</para>
		</listitem>
		<listitem>
			<para>SIP-Request-Hash - body of P-Request-Hash header</para>
		</listitem>
		<listitem>
			<para>Service-Type - verify_source_service_type</para>
		</listitem>
		</itemizedlist>
		<para>
		Function returns value 1 if SIP request was received
	from a trusted peer and -1 otherwise.  In case of positive
	result, AAA server may return a set of SIP-AVP reply
	attributes.  Value of each SIP-AVP is of form:
		 </para>
		 <para>
		 [#]name(:|#)value
		 </para>
		 <para>
		 Value of each SIP-AVP reply attribute is mapped to an
		 OpenSIPS 
		 AVP.  Prefix # in front of name or value indicates a
	string name or string value, respectively.
		 </para>
		 <para>
		 AVP names used in reply attributes are
		 assigned by the broker.
		 </para>
		<para>
		This function can be used from REQUEST_ROUTE and
		FAILURE_ROUTE.
		</para>
		<example>
		<title><function
	moreinfo="none">verify_source()</function> usage</title>  
		<programlisting format="linespecific">
...
if (is_present_hf("P-Request-Hash")) {
   if (verify_source()) {
      xlog("L_INFO", "Request came from trusted peer\n")
   }
}
...
</programlisting>
		</example>
	</section>

	</section>
</chapter>
