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

    <title>Functions</title>
    
    <section id="radius_www_authorize">
	<title><function>radius_www_authorize(realm)</function></title>
	<para>
	    The function verifies credentials according to <ulink
		url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If
	    the credentials are verified successfully then the function
	    will succeed and mark the credentials as authorized (marked
	    credentials can be later used by some other functions). If the
	    function was unable to verify the credentials for some reason
	    then it will fail and the script should call
	    <function>www_challenge</function> which will challenge the
	    user again.
	</para>
	<para>
	    This function will, in fact, perform sanity checks over the
	    received credentials and then pass them along to the radius server
	    which will verify the credentials and return whether they are valid
	    or not.
	</para>
	<para>Meaning of the parameter 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>
	</itemizedlist>
	<example>
	    <title><function>radius_www_authorize</function> usage</title>
	    <programlisting>
...
if (!radius_www_authorize("iptel.org")) {
    www_challenge("iptel.org", "1");
};
...
	    </programlisting>
	</example>
    </section>
    
    <section id="radius_proxy_authorize">
	<title><function moreinfo="none">radius_proxy_authorize(realm)</function></title>
	<para>
	    The function verifies credentials according to <ulink
		url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If
	    the credentials are verified successfully then the function
	    will succeed and mark the credentials as authorized (marked
	    credentials can be later used by some other functions). If the
	    function was unable to verify the credentials for some reason
	    then it will fail and the script should call
	    <function>proxy_challenge</function> which will challenge the
	    user again.
	</para>
	<para>
	    This function will, in fact, perform sanity checks over the
	    received credentials and then pass them along to the radius server
	    which will verify the credentials and return whether they are valid
	    or not.
	</para>
	<para>Meaning of the parameter 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>
	</itemizedlist>
	<example>
	    <title>proxy_authorize usage</title>
	    <programlisting>
...
if (!radius_proxy_authorize("")) {
    proxy_challenge("", "1");  # Realm will be autogenerated
};
...
	    </programlisting>
	</example>
    </section>
</section>
