kamailio/modules/auth_identity/doc/auth_identity.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"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>

<section id="auth_identity" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Gergely</firstname>
		<surname>Kovacs</surname>
		<affiliation><orgname>Iptel.org</orgname></affiliation>
		<address>
		    <email>gergo@iptel.org</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2007</year>
	    <holder>Iptel.org</holder>
	</copyright>
    </sectioninfo>

    <title>SIP Authenticated Identity Module</title>

    <section>
	<title>Overview</title>
	<para>
		Auth Identity module provides functionalities for securely identifying
		originators of SIP messages. This module has two basic service:
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>authorizer</emphasis> - authorizes a message and adds Identity and
				Identity-Info headers
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>verifier</emphasis> - verifies an authorized message
			</para>
		</listitem>
		</itemizedlist>
	</para>
	<para>
	    Known limitations in this version:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
			authorizer and verifier support all SIP requests except for
			<emphasis>CANCEL</emphasis> and <emphasis>REGISTER</emphasis>
		</para>
	    </listitem>
		<listitem>
			<para>
				verifier does not support the subjectAltName extension of
				certificates
			</para>
		</listitem>
	</itemizedlist>
    </section>

    <section id="auth_identity.dep">
	<title>Dependencies</title>
	<para>
		This module does not depend any other module.
	</para>
    </section>

	<section id="auth_identity.compilation">
		<title>Compilation</title>
		<para>
		This module needs the following headers and libraries:
		<itemizedlist>
			<listitem>
				<para>
					<emphasis>OpenSSL</emphasis> (version 0.9.8 or higher) for cryptographic functions
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>libcurl</emphasis> for HTTP, HTTPS functions
				</para>
			</listitem>
		</itemizedlist>
		If you'd like to use <emphasis>TLS</emphasis> module too then use the
		corresponding LIB line in auth_identity's Makefile
		</para>
	</section>

	<section id="auth_identity.install_and_run">
	<title>Installation And Running</title>
	<para>
		the <emphasis>Authorizer</emphasis> service needs to make the public key,
		which conveyed in a certificate, available over HTTPS or HTTP for
		verifiers. The domain the authorizer is responsible for and the
		domain part of the URL of the certificate must be the same. This
		service needs access to the private key too.
	</para>
    </section>


    <xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>


	<section>
		<title>Authorizer service examples</title>

			<programlisting><![CDATA[
...
route[INIT]
{
	# we process new transactions only
	if (!t_newtran()) {
		sl_reply("500", "Internal error newtran");
		drop;
	}
...
route[OUTBOUND]
{
	# If we are responsible for the domain of the sender of this message
	if ($f.did && !$t.did) {
		# Authentication service
		if (method=="INVITE" || method=="BYE"
			|| method=="OPTION" || method=="ACK") {
			# Identity and Identity-info headers must not exist
			if (@identity) {
				t_reply("403", "Invalid Identity header");
				drop;
			}
			if (@identity_info) {
				t_reply("403", "Invalid Identity-info header");
				drop;
			}

			if (!auth_date_proc()) {
				t_reply("403", "Invalid Date value");
				drop;
			}

			if (!auth_add_identity()) {
				t_reply("480", "Authentication error");
				drop;
			}
		}
		route(FORWARD);
	}
}
...
]]></programlisting>
	</section>


	<section>
		<title>Verifier service examples</title>

		<programlisting><![CDATA[
...
route[INIT]
{
	# we process new transactions only
	if (!t_newtran()) {
		sl_reply("500", "Internal error newtran");
		drop;
	}
...
route[VERIFY]
{
	# if we've already processed this message then we drop it
	if (!t_newtran()) {
		sl_reply("500", "Internal error newtran");
		drop;
	}

	if (method=="INVITE" || method=="BYE"
		|| method=="OPTION" || method=="ACK") {
		# Identity and Identity-info are required for verification
		if (!@identity) {
			t_reply("428", "Use Identity Header");
			drop;
		}
		if (!@identity_info) {
			t_reply("436", "Bad Identity-Info");
			drop;
		}

		if (!vrfy_check_date()) {
			t_reply("403", "Outdated Date header value");
			drop;
		}

		if (!vrfy_get_certificate()) {
			t_reply("436", "Bad Identity-Info");
			drop;
		}

		if (!vrfy_check_certificate()) {
			t_reply("437", "Unsupported Certificate");
			drop;
		}

		if (!vrfy_check_msgvalidity()) {
			t_reply("438", "Invalid Identity Header");
			drop;
		}

		if (!vrfy_check_callid()) {
			t_reply("403", "Message is replayed");
			drop;
		}
	}
}
...
]]></programlisting>
	</section>
</section>