auth_user.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.5.2.1 $</revnumber>
		<date>$Date: 2005/06/22 23:12:01 $</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>
	<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>Exported Parameters</title>
	<section>
	    <title><varname>secret</varname> (string)</title>
	    <para>
	    </para>
	    <para>
		Default value is randomly generated string.
	    </para>
	    <example>
		<title>Setting secret module parameter</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 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</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_prefix", "Whatever <")
</programlisting>
	    </example>
	</section>	

	<section>
	    <title><varname>realm_prefix</varname> (string)</title>
	    <para>
		The prefix to be stripped off the realm before any
		processing is done. Useful when you have a user agent that
		cannot be configured with different values for the hostname of
		the proxy server and domain to be used in From and To header fields.
	    </para>
	    <para>
		Default value is "".
	    </para>
	    <example>
		<title>realm_prefix</title>
		<programlisting format="linespecific">
modparam("auth", "realm_prefix", "sip.")
</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</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_suffix", "@1.2.3.4>")
</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>
		</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>
	    <example>
		<title>www_challenge usage</title>
		<programlisting format="linespecific">
...
if (www_authorize("iptel.org", "subscriber")) {
    www_challenge("iptel.org", "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>
		</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>
	    <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>
	    <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>
	    <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>
	    <example>
		<title>append_rpid_hf</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>
	    <example>
		<title>append_rpid_hf(prefix, suffix)</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:
-->