<?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="auth.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.2 $</revnumber>
		<date>$Date: 2005/08/24 13:24:29 $</date>
	    </revision>
	</revhistory>
    </sectioninfo>

    <title>Functions</title>
    
    <section id="www_challenge">
	<title><function>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
	    <ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>.
	</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 "" 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>
		</listitem>
	    <listitem>
		<para>
		    <emphasis>qop</emphasis> - Value of this parameter can be
		    either "1" or "0". 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>
	<example>
	    <title>www_challenge usage</title>
	    <programlisting>
...
if (www_authorize("iptel.org", "subscriber")) {
    www_challenge("iptel.org", "1");
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="proxy_challenge">
	<title><function>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
	    <ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>.
	</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 "" is used then the server will generate
		    it from the request. From header field domain will be used
		    as realm.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    <emphasis>qop</emphasis> - Value of this parameter can be
		    either "1" or "0". 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>
	<example>
	    <title>proxy_challenge usage</title>
	    <programlisting>
...
if (!proxy_authorize("", "subscriber)) {
    proxy_challenge("", "1");  # Realm will be autogenerated
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="consume_credentials">
	<title><function>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>www_authorize</function> or
	    <function>proxy_authorize</function>.
	</para>
	<example>
	    <title>consume_credentials example</title>
	    <programlisting>
...
if (www_authorize("", "subscriber)) {
    consume_credentials();
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="is_rpid_user_e164">
	<title><function>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>
	<example>
	    <title>is_rpid_user_e164 usage</title>
	    <programlisting>
...
if (is_rpid_user_e164()) {
    # do something here
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="append_rpid_hf0">
	<title><function>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>
	<example>
	    <title>append_rpid_hf usage</title>
	    <programlisting>
...
append_rpid_hf();  # Append Remote-Party-ID header field
...
	    </programlisting>
	</example>
    </section>
    
    <section id="append_rpid_hf2">
	<title><function>append_rpid_hf(prefix, suffix)</function></title>
	<para>
	    This function is the same as the function described in <xref
		linkend="append_rpid_hf0"/>. 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
		for 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>
	<example>
	    <title>append_rpid_hf(prefix, suffix) usage</title>
	    <programlisting>
...
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");  # Append Remote-Party-ID header field
...
	    </programlisting>
	</example>
    </section>
</section>
