<?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 "../../../../doc/docbook/entities.xml">
%docentities;

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

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		This module provides a custom mechanism to authenticate a SIP entity
		using a list of shared keys.
	</para>
	<para>
		It is similar to the API key based authentication used by many web
		services. In short, the sender adds a particular header with a hash
		token computed with the shared key and some values from the SIP
		request (e.g., local IP, From/To/R-URI username, Call-ID, CSeq). The
		receiver will check the hash value and decide whether the SIP message
		is authenticated or not. The sender and receiver have to agree
		beforehand on the name of the server, shared secret, algorithm to be
		used and what data is going to be hashed.
	</para>
	<para>
		The module is designed to work with many shared keys on the same
		group, for more flexibility in adding/removing keys. The last added
		key in the group is used to add the header, but older ones are used
		for matching the hash value. That allows to change the active shared
		key without affecting ongoing traffic. If one decides to use a new
		share key, add it first to receiver (it will still authenticate with
		older key) and then to the sender. Once both nodes are provisioned
		with the new key, the older one can be removed.
	</para>
	<para>
		For proper protection, it is recommended to use this
		authentication mechanism over a secure channel (e.g., TLS, VPN,
		private network).
	</para>
	<para>
		The benefit is avoiding the extra traffic and processing required
		by WWW-Digest authentication schema (no more 401/407 and a follow up
		request with credentials).
	</para>
	<para>
		Another goal is to provide more elasticity for scalability needs of
		the core SIP network nodes. Most of the nodes in the core network or
		the interconnecting peers trust each other based on IP address. But
		adding a new node requires updates to the exiting ones to trust the
		IP address of the new node. On large deployments, that can become
		rather complex. For example, as a replacement for IP trust
		relationships, the sender can hash the local IP with the secret
		shared key, add it in the header and the receiver will check if the
		source ip hashed with the key results in the same value.
	</para>
	<para>
		Not being a challenge-reply mechanism, this can be used to authenticate
		SIP responses from trusted peers.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</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:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="auth_xkeys.p.xkey">
		<title><varname>xkey</varname> (str)</title>
		<para>
			Specify the attributes for a shared secret. The value is in
			the format 'name1=value1;name2=value2;...'. The attributes can be:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>id</emphasis> - the id of the group for keys
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>name</emphasis> - the name of the key within group
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>value</emphasis> - the value of the key
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>expires</emphasis> - expiration time (seconds)
			</para>
			</listitem>
			</itemizedlist>
		<para>
		<emphasis>
			Default value is empty.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xkey</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("auth_xkeys", "xkey", "id=abc;name=xyz;value=secret;expires=72000")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="auth_xkeys.f.auth_xkeys_add">
	    <title>
		<function moreinfo="none">auth_xkeys_add(hdr, kid, alg, data)</function>
	    </title>
	    <para>
		Add a header computed with the first key in the group kid, hashing with
		algorithm alg over the content of parameter data. The parameters can
		include variables.
		</para>
		<para>
		The algorithm can be: sha256, sha384, sha512.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>auth_xkeys_add</function> usage</title>
		<programlisting format="linespecific">
...
auth_xkeys_add("X-My-Key", "abc", "sha256", "$Ri:$fu:$ru:$hdr(CSeq)");
...
</programlisting>
	    </example>
	</section>

	<section id="auth_xkeys.f.auth_xkeys_check">
	    <title>
		<function moreinfo="none">auth_xkeys_check(hdr, kid, alg, data)</function>
	    </title>
	    <para>
		Check if the value of header hdr matches the value computed with the
		first key in the group kid, hashing with algorithm alg over the content
		of parameter data. The parameters can include variables.
		</para>
		<para>
		The algorithm can be: sha256, sha384, sha512.
		</para>
		<para>
		Note that the header is not removed by the function, it is recommended
		to remove it if sending to untrusted destination.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>auth_xkeys_check</function> usage</title>
		<programlisting format="linespecific">
...
if(!auth_xkeys_check("X-My-Key", "abc", "sha256", "$si:$fu:$ru:$hdr(CSeq)")) {
    send_reply("403", "Forbidden");
    exit;
}
remove_hf("X-My-Key");
...
</programlisting>
	    </example>
	</section>

	</section>
</chapter>