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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.5 $</revnumber>
		<date>$Date: 2006/05/22 14:13:00 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>

	<section>
	<title>Overview</title>
	<para>
		This is a generic module that itself doesn't provide all functions 
		necessary for authentication but provides functions that are needed 
		by all other authentication related modules (so called authentication 
		backends).
	</para>
	<para>
		We decided to break the authentication code into several modules 
		because there are now more than one backends (currently database 
		authentication and radius are supported). This allows us to create 
		separate packages so uses can install and load only required 
		functionality. This also allows us to avoid unnecessary dependencies 
		in the binary packages.
	</para>
	</section>

	<section>
		<title>Dependencies</title>
		<section>
			<title>&ser; 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>sl</emphasis> -- Stateless replies</para>
			</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
			The following libraries or applications must be installed 
			before running &ser; with this module loaded:
			<itemizedlist>
				<listitem>
				<para><emphasis>none</emphasis></para>
				</listitem>
			</itemizedlist>
		</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>secret</varname> (string)</title>
		<para>
		Secret phrase.
		</para>
		<para>
		Default value is randomly generated string.
		</para>
		<example>
		<title>secret parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "secret", "johndoessecretphrase")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>nonce_expire</varname> (integer)</title>
		<para>
		Nonces have limited lifetime. After a given period of time nonces 
		will be considered invalid. This is to protect replay attacks. 
		Credentials containing a stale nonce will be not authorized, but the 
		user agent will be challenged again. This time the challenge will 
		contain <varname>stale</varname> parameter which will indicate to the
		client that it doesn't have to disturb user by asking for username 
		and password, it can recalculate credentials using existing username 
		and password.
		</para>
		<para>
		The value is in seconds and default value is 300 seconds.
		</para>
		<example>
		<title>nonce_expire parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rpid_prefix</varname> (string)</title>
		<para>
		Prefix to be added to Remote-Party-ID header field just before 
		the URI returned from either radius or database.
		</para>
		<para>
		Default value is <quote></quote>.
		</para>
		<example>
		<title>rpid_prefix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_prefix", "Whatever <")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rpid_suffix</varname> (string)</title>
		<para>
		Suffix to be added to Remote-Party-ID header field after the URI 
		returned from either radius or database.
		</para>
		<para>
		Default value is 
			<quote>;party=calling;id-type=subscriber;screen=yes</quote>.
		</para>
		<example>
		<title>rpid_suffix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_suffix", "@1.2.3.4>")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>realm_prefix</varname> (string)</title>
		<para>
			Prefix to be automatically strip from realm. As an alternative to
			SRV records (not all SIP clients support SRV lookup), a subdomain
			of the master domain can be defined for SIP purposes (like 
			sip.mydomain.net pointing to same IP address as the SRV
			record for mydomain.net). By ignoring the realm_prefix 
			<quote>sip.</quote>, at authentication, sip.mydomain.net will be
			equivalent to mydomain.net .
		</para>
		<para>
		Default value is empty string.
		</para>
		<example>
		<title>realm_prefix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "realm_prefix", "sip.")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rpid_avp</varname> (string)</title>
		<para>
			Full AVP specification (ID, Name, Alias) for the AVP which 
			stores the RPID value. It used to transport the RPID value from
			authntication backend modules (auth_db or auth_radius) or from 
			script to the auth function append_rpid_hf and is_rpid_user_e164.
		</para>
		<para>
			If defined to NULL string, all RPID functions will fail at 
			runtime.
		</para>
		<para>
		Default value is <quote>rpid</quote> (Name AVP - e.g, 'i:number',
		's:string' or 'avp_alias_string').
		</para>
		<example>
		<title>rpid_avp parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_avp", "i:13")
		</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
			<function moreinfo="none">www_challenge(realm, qop)</function>
		</title>
		<para>
		The function challenges a user agent. It will generate a 
		WWW-Authorize header field containing a digest challenge, it will 
		put the header field into a response generated from the request the 
		server is processing and send the reply. Upon reception of such a 
		reply the user agent should compute credentials and retry the
		request. For more information regarding digest authentication 
		see RFC2617.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>realm</emphasis> - Realm is a opaque string that 
			the user agent should present to the user so he can decide what 
			username and password to use. Usually this is domain of the host 
			the server is running on.
			</para>
			<para>
			If an empty string <quote></quote> is used then the server will 
			generate it from the request. In case of REGISTER requests To 
			header field domain will be used (because this header field 
			represents a user being registered), for all other messages From 
			header field domain will be used.
			</para>
			<para>
			The string may contain pseudo variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>qop</emphasis> - Value of this parameter can be 
			either <quote>1</quote> or <quote>0</quote>. When set to 1 then 
			the server will put qop parameter in the challenge. When set to 0 
			then the server will not put qop parameter in the challenge. It 
			is strongly recommended to use qop parameter, however there are 
			still some user agents that cannot handle qop parameter properly 
			so we made this optional. On the other hand there are still some 
			user agents that cannot handle request without qop parameter too.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>

		<example>
		<title>www_challenge usage</title>
		<programlisting format="linespecific">
...
if (www_authorize("siphub.net", "subscriber")) {
	www_challenge("siphub.net", "1");
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
			<function moreinfo="none">proxy_challenge(realm, qop)</function>
		</title>
		<para>
		The function challenges a user agent. It will generate a 
		Proxy-Authorize header field containing a digest challenge, it will 
		put the header field into a response generated from the request the 
		server is processing and send the reply. Upon reception of such a 
		reply the user agent should compute credentials and retry the request.
		For more information regarding digest authentication see RFC2617.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>realm</emphasis> - Realm is a opaque string that 
			the user agent should present to the user so he can decide what 
			username and password to use. Usually this is domain of the host 
			the server is running on.
			</para>
			<para>
			If an empty string <quote></quote> is used then the server will 
			generate it from the request. From header field domain will be 
			used as realm.
			</para>
			<para>
			The string may contain pseudo variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>qop</emphasis> - Value of this parameter can be 
			either <quote>1</quote> or <quote>0</quote>. When set to 1 then 
			the server will put qop parameter in the challenge. When set to 0 
			then the server will not put qop parameter in the challenge. It 
			is strongly recommended to use qop parameter, however there are 
			still some user agents that cannot handle qop parameter properly 
			so we made this optional. On the other hand there are still some 
			user agents that cannot handle request without qop parameter too.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>proxy_challenge usage</title>
		<programlisting format="linespecific">
...
if (!proxy_authorize("", "subscriber)) {
	proxy_challenge("", "1");  # Realm will be autogenerated
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
			<function moreinfo="none">consume_credentials()</function>
		</title>
		<para>
		This function removes previously authorized credentials from the 
		message being processed by the server. That means that the downstream 
		message will not contain credentials there were used by this server. 
		This ensures that the proxy will not reveal information about 
		credentials used to downstream elements and also the message will be 
		a little bit shorter. The function must be called after 
		<function moreinfo="none">www_authorize</function> or 
		<function moreinfo="none">proxy_authorize</function>. 
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>consume_credentials example</title>
		<programlisting format="linespecific">
...
if (www_authorize("", "subscriber)) {
    consume_credentials();
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
			<function moreinfo="none">is_rpid_user_e164()</function>
		</title>
		<para>
		The function checks if the SIP URI received from the database or 
		radius server and will potentially be used in Remote-Party-ID header 
		field contains an E164 number (+followed by up to 15 decimal digits) 
		in its user part.  Check fails, if no such SIP URI exists 
		(i.e. radius server or database didn't provide this information).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>is_rpid_user_e164 usage</title>
		<programlisting format="linespecific">
...
if (is_rpid_user_e164()) {
    # do something here
};
...
</programlisting>
		</example>
	</section>
	<section id="append-rpid-hf-no-params">
		<title>
			<function moreinfo="none">append_rpid_hf()</function></title>
		<para>
		Appends to the message a Remote-Party-ID header that contains header
		'Remote-Party-ID: ' followed by the saved value of the SIP URI 
		received from the database or radius server followed by the value of 
		module parameter radius_rpid_suffix.  The function does nothing if 
		no saved SIP URI exists.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>append_rpid_hf usage</title>
		<programlisting format="linespecific">
...
append_rpid_hf();  # Append Remote-Party-ID header field
...
</programlisting>
		</example>
	</section>
	<section id="append-rpid-hf-params">
		<title>
			<function moreinfo="none">append_rpid_hf(prefix, suffix)</function>
		</title>
		<para>
		This function is the same as 
		<xref linkend="append-rpid-hf-no-params">. The only difference is
		that it accepts two parameters--prefix and suffix to be added to 
		Remote-Party-ID header field. This function ignores rpid_prefix and 
		rpid_suffix parameters, instead of that allows to set them in every 
		call.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>prefix</emphasis> - Prefix of the 
			Remote-Party-ID URI. The string will be added at the begining of 
			body of the header field, just before the URI.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>suffix</emphasis> - Suffix of the Remote-Party-ID 
			header field. The string will be appended at the end of the 
			header field. It can be used to set various URI parameters, 
			for example.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>append_rpid_hf(prefix, suffix) usage</title>
		<programlisting format="linespecific">
...
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");  # Append Remote-Party-ID header field
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("auth.sgml" "Book" "chapter")
End:
-->