Man pages for auth and avp.

modules_s/auth/auth.xml

@@ -0,0 +1,685 @@
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbookid/id/g/4.5/docbookx.dtd">
+
+<refentry id="module.auth"
+          xmlns:serdoc="http://sip-router.org/xml/serdoc">
+  <refmeta>
+    <refentrytitle>auth</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>auth</refname>
+    <refpurpose>Basic Functionality for Digest Authentication</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      The <command>auth</command> SER module provides basic functionality
+      for digest authentication. However, it does not provide access to
+      the user information and therefore relies on another module. These
+      modules are <serdoc:module>auth_db</serdoc:module>,
+      <serdoc:module>auth_diameter</serdoc:module>,
+      <serdoc:module>auth_identity</serdoc:module>, and
+      <serdoc:module>auth_radius</serdoc:module>.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Functions</title>
+
+    <refsect2 xml:id="function.consume_credentials">
+      <title>
+        <function>consume_credentials</function> ()
+      </title>
+      <para>
+        Allowed in request processing only.
+      </para>
+      <para>
+        The <function>consume_credentials()</function> function
+        removes previously authorized credentials from the request.
+        This means that forwarded or relayed requests
+        will not contain credentials that were checked by this server
+        and ensures that the proxy will not reveal information about
+        credentials used to downstream elements. In addition, the
+        message will be shorter.
+      </para>
+      <para>
+        The function must be called after a call to an authorization
+        function such as
+        <serdoc:func>www_authenticate</serdoc:func>.
+      </para>
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Module Parameters</title>
+
+    <refsect2 xml:id="module.auth.auth_checks_in_dlg">
+      <title><parameter>auth_checks_in_dlg</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>0</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>auth_checks_in_dlg</parameter> parameter controls
+        which integrity checks are performed on requests within a dialog,
+        ie., requests that carry a To tag. The default value of
+        <literal>0</literal> turns off any checks. Otherwise, the value
+        indicates which checks are run.
+      </para>
+      <para>
+        See <serdoc:link linkend="module.auth.integrity_checks">Additional
+        Integrity Checks</serdoc:link> below for more details.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.auth_checks_no_dlg">
+      <title><parameter>auth_checks_no_dlg</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>0</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>auth_checks_no_dlg</parameter> parameter controls
+        which integrity checks are performed on out-of-dialog requests,
+        ie., requests that do not carry a To tag. The default value of
+        <literal>0</literal> turns off any checks. Otherwise, the value
+        indicates which checks are run.
+      </para>
+      <para>
+        See <serdoc:link linkend="module.auth.integrity_checks">Additional
+          Integrity Checks</serdoc:link> below for more details.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.auth_checks_register">
+      <title><parameter>auth_checks_register</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>0</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>auth_checks_register</parameter> parameter
+        controls which integrity checks are performed on a REGISTER
+        message. If the parameter is changed from its default value
+        of <literal>0</literal>, it activates those checks and defines,
+        which checks are run.
+      </para>
+      <para>
+        See <serdoc:link linkend="module.auth.integrity_checks">Additional
+          Integrity Checks</serdoc:link> below for more details.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.challenge_attr">
+      <title><parameter>challenge_attr</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>attriubte name</serdoc:paramtype>
+        <serdoc:paramdefault>$digest_challenge</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>challenge_attr</parameter> parameter names the
+        attribute which will contain the complete header field with the
+        authentication challenge. The content if this attribute has to
+        be added to the response in order to transmit the challenge
+        to the client.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nc_array_order">
+      <title><parameter>nc_array_order</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>20</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nc_array_order</parameter> parameter is an
+        alternative way to set the maximum number of nonces for the nonce
+        check enabled by the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        parameter. Its meaning is identical to that of the
+        <serdoc:modparam module="auth">nc_array_size</serdoc:modparam>
+        parameter but the size is given by stating the power of 2.
+        See <serdoc:modparam module="auth">nc_array_size</serdoc:modparam>
+        and <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        for more details.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nc_array_size">
+      <title><parameter>nc_array_size</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>1048576</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nc_array_size</parameter> parameter sets the
+        maximum number of in-flight nonces for the nonce
+        count check enabled by the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        parameter. It represents the maximum number of nonces for which
+        state will be kept. When this number is exceeded, state for older
+        nonces will be discarded to make space for new ones. See
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam> for
+        more details.
+      </para>
+      <para>
+        The value should be a power of 2. If it is not, it will be rounded
+        down to such a number. For example a value of 1000000 will be
+        rounded down to 524288. The
+        <serdoc:modparam module="auth">nc_array_order</serdoc:modparam>
+        parameter can be used to directly specify the power of 2. For
+        instance, a value for 
+        <serdoc:modparam module="auth">nc_array_order</serdoc:modparam>
+        of 20 is equivalent to a <parameter>nc_array_size</parameter>
+        of 1048576.
+      </para>
+      <para>
+        The memory used to keep the nonce state will be
+        equal to the value of <parameter>nc_array_size</parameter> in
+        bytes.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nid_pool_no">
+      <title><parameter>nid_pool_no</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>1</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nid_pool_no</parameter> parameter controls the number
+        of partitions for the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam> and
+        <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>
+        arrays. It is common to both of them to reduce the nonce size.
+      </para>
+      <para>
+        Instead of using single arrays for keeping nonce state, these arrays
+        can be divided into several partitions. Each SER process is assigned
+        to one of these partitions, allowing for higher concurrency on
+        multi-CPU machines. Besides increasing performance, increasing
+        <parameter>nid_pool_no</parameter> has also a negative effect: it
+        could decrease the maximum supported in-flight nonces in certain
+        conditions.  In the worst case, when only one SER process receives
+        most of the traffic (e.g. very busy TCP connection between two
+        proxies), the in-flight nonces could be limited to the array size
+        (<serdoc:modparam module="auth">nc_array_size</serdoc:modparam>
+        for <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        and <serdoc:modparam module="auth">otn_in_flight_no</serdoc:modparam>
+        for <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>)
+        divided by the partitions number
+        (<parameter>nid_pool_no</parameter>). However for normal traffic,
+        where
+        the process receiving a message is either random or chosen in a
+        round-robin fashion, the maximum number of in-flight nonces will be
+        influenced to a very small degree by
+        <parameter>nid_pool_no</parameter>, since the messages
+        will be close to equally distributed to processes using different
+        partitions.
+      </para>
+      <para>
+        The <parameter>nid_pool_no</parameter> value should be one of:
+        1, 2, 4, 8, 16, 32 or 64 (the maximum value is 64 and all values
+        should be a power of 2 or else they will be rounded down to such
+        a value).
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nonce_auth_max_drift">
+      <title><parameter>nonce_auth_max_drift</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>3</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nonce_auth_max_drift</parameter> parameter
+        specifies the maximum difference in seconds between a nonce
+        creation time and the current time, if the nonce creation time
+        appears to be in the future.
+      </para>
+      <para>
+        In some cases, like shortly after a system time backward
+        adjustment or when the current proxy is part of a cluster which is
+        not time-synchronized, it's possible to receive a nonce with
+        a creation time in the future. In this case if the difference is
+        greater then the value of <parameter>nonce_auth_max_drift</parameter>
+        in seconds, the nonce is  considered stale and the request
+        re-challenged. If this were not done, a dramatic time change
+        backwards may lead to nonces having been generated before the
+        cange being valid for too long.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nonce_count">
+      <title><parameter>nonce_count</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>boolean</serdoc:paramtype>
+        <serdoc:paramdefault>no</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nonce_count</parameter> parameter controls, whether
+        tracking of nounce count is enabled. If it is set to
+        <literal>yes</literal>, the received <parameter>nc</parameter> value
+        is remembered and checked against the value used in the previous
+        digest response. For a successful authentication the received
+        <parameter>nc</parameter> must be greater then the previously
+        received one (See RFC 2617 for more details). This will	provide
+        protection against replay attacks while still allowing credentials
+        caching at the UA side.
+      </para>
+      <para>
+        In order for this to work, the
+        <serdoc:modparam module="auth">qop</serdoc:modparam> parameter
+        must not be set to an empty string. It it is, the challenges won’t
+        include the <parameter>qop</parameter> parameter and the user agent
+        will probably not include the <parameter>qop</parameter> or
+        <parameter>nc</parameter> parameters in its response.
+      </para>
+      <para>
+        If a response doesn’t include <parameter>qop</parameter> or
+        <parameter>nc</parameter> (for example obsolete UAs that don't
+        support them) the response will be checked according to the other
+        enabled nonce checks, in this order:
+        <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam> and
+        the applicable of the additional integrity checks. If a response
+        includes <parameter>nc</parameter> only the normal
+        <serdoc:modparam module="auth">nonce_expire</serdoc:modparam>
+        checks and the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam> checks
+        will be performed, all the other checks will be ignored.
+      </para>
+      <para>
+        The <parameter>nonce_count</parameter> checks work by tracking a
+        limited number of nonces. The maximum number of tracked nonces is
+        set using the
+        <serdoc:modparam module="auth">nc_array_size</serdoc:modparam> or
+        <serdoc:modparam module="auth">nc_array_order</serdoc:modparam>
+        parameters. If this number is exceeded, older entries will be
+        overwritten. As long as the maximum rate of challengeable messages
+        per average response time is lower then
+        <serdoc:modparam module="auth">nc_array_size</serdoc:modparam>,
+        the nonce count check should work flawlessly. For optimal
+        performance (maximum reuse of cache credentials)
+        <serdoc:modparam module="auth">nc_array_size</serdoc:modparam>
+        divided by
+        <serdoc:modparam module="auth">nid_pool_no</serdoc:modparam>
+        should be lower then the message rate multiplied by the desired
+        <serdoc:modparam module="auth">nonce_expire</serdoc:modparam>.
+        <!-- XXX: Give an example with default nonce_expire and typical
+                  RTT. -->
+      </para>
+      <para>
+        The maximum accepted <parameter>nc</parameter> value is 255. If
+        <parameter>nc</parameter> becomes greater then this, the nonce will
+        be considered stale and the UA will be re-challenged.
+      </para>
+      <para>
+        <emphasis>Note:</emphasis> If the <parameter>nonce_count</parameter>
+        parameter is enabled, all challenges should be done in stateful
+        mode, ie., a transaction should be created prior to the
+        authentication check, for instance by using the function
+        <serdoc:func>t_newtran</serdoc:func>, to absorb possible
+        retransmissions. All the replies need to be sent statefuly,
+        using <serdoc:func>t_reply()</serdoc:func>). Otherwise,
+        all retransmissions will be challenged which may cause the user
+        agent to believe the password supplied by the user to be wrong.
+      </para>
+      <para>
+        For more information on stateful processing, see
+        <serdoc:module>tm</serdoc:module>. An example on how to implement
+        a stateful registrar can be found in
+        <serdoc:module>registrar</serdoc:module>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.nonce_expire">
+      <title><parameter>nonce_expire</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>300</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>nonce_exipre</parameter> parameter determines the
+        time in seconds before a nonce is considered stale.
+      </para>
+      <para>
+        Nonces have a limited lifetime after which they 
+        will be considered stale.
+        This is to protect replay attacks. Credentials containing a stale
+        nonce will be not authorized. The user agent will be challenged
+        again instead. This new challenge will not only contain a newly
+        generated nonce, but also the <parameter>stale</parameter>
+        parameter which indicates to the client the failure was not due
+        to a wrong username or password and it doesn't need to disturb
+        the user asking for them. It can simply recalculate its answer 
+	using existing username and password.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.one_time_nonce">
+      <title><parameter>one_time_nonce</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>boolean</serdoc:paramtype>
+        <serdoc:paramdefault>no</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>one_time_nonce</parameter> controls whether digist
+        responses with a reused nonce will be rejected. If it is set to
+        <literal>yes</literal>, nonces cannot be reused by user agents.
+      </para>
+      <para>
+        This results in each request being challenged. To avoid retransmits
+        being challenged, it should only be used in stateful mode, ie., by
+        creating a transaction before authentication, for instance trough
+        a call to the <serdoc:func>t_newtran</serdoc:func> function. For
+        more information on stateful mode see
+        <serdoc:module>tm</serdoc:module>. An example on how to implement
+        a stateful registrar can be found in
+        <serdoc:module>registrar</serdoc:module>.
+      </para>
+      <para>
+        The one time nonce provides enhanced replay protections at the cost
+        of invalidating UA side credentials
+        caching and causing extra round trips. Therefore, the nonce chount
+        check enabled through the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        parameter should be preferred.
+      </para>
+      <para>
+        The one time nonce provides the same protection as the nonce count
+        check but requiring more messages. The advantages are that it uses
+        less memory for the same supported number of maximum in-flight
+        nonces (by a factor of 8) and that it works
+        with user agents that do not support <parameter>qop</parameter>
+        and <parameter>nc</parameter>. It shoud thus be used if such
+        user agents are in use and the checks described in section
+        <serdoc:link linkend="module.auth.integrity_checks">Additional
+          Integrity Checks</serdoc:link> are not deemed sufficient.
+      </para>
+      <para>
+        Like the nonce count check, one time nonces works by tracking a
+        limited number of nonces. The maximum number of tracked nonces is
+        set using the
+        <serdoc:modparam module="auth">otn_in_flight_no</serdoc:modparam>
+        or
+        <serdoc:modparam module="auth">otn_in_flight_order</serdoc:modparam>
+        parameters. If this number is exceeded, older entries will be
+        overwritten. As long as the maximum rate of challengeable messages
+        per average response time is lower then
+        <serdoc:modparam module="auth">otn_in_flight_no</serdoc:modparam>,
+        the one time nonce check should work flawlessly.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.otn_in_flight_no">
+      <title><parameter>otn_in_flight_no</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>1048576</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>otn_in_flight_no</parameter> parameter specifies
+        the maximum number of in-flight nonces for the one time nonce
+        check enabled by the
+        <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>
+        parameter. It represents the maximum number of nonces remembered
+        for the one time nonce check. When this number is exceeded,
+        information about older nonces will be discarded and overwritten
+        with information about newly generated nonces. See
+        <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>
+        for more details.
+      </para>
+      <para>
+        The value should be a power of 2. If it is not, it will be rounded
+        down to such a value. The
+        <serdoc:modparam module="auth">otn_in_flight_order</serdoc:modparam>
+        parameter can be used to directly specify the power of 2.
+      </para>
+      <para>
+        The memory used to keep the nonce information will be identical to
+        the value of <parameter>otn_in_flight_no</parameter> divided by 8
+        since only 1 bit of state is kept per nonce.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.otn_in_flight_order">
+      <title><parameter>otn_in_flight_order</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>20</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>otn_in_flight_order</parameter> parameter is an
+        alternative way to set the maximum number of nonces for the
+        one time nonce check enabled by the
+        <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>
+        parameter. Its meaning is identical to that of the
+        <serdoc:modparam module="auth">otn_in_flight_no</serdoc:modparam>
+        parameter but the size is given by stating the power of 2.
+        See <serdoc:modparam module="auth">otn_in_flight_no</serdoc:modparam>
+        and <serdoc:modparam module="auth">one_time_nonce</serdoc:modparam>
+        for more details.
+      </para>
+    </refsect2>
+
+
+    <refsect2 xml:id="module.auth.protect_contacts">
+      <title><parameter>protect_contacts</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>boolean</serdoc:paramtype>
+        <serdoc:paramdefault>no</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        If the <parameter>protect_contacts</parameter> parameter is set
+        to <literal>yes</literal>, the contacts are included when creating
+        a nonce.
+      </para>
+      <!-- XXX What does this exactly mean? -->
+    </refsect2>
+
+
+    <refsect2 xml:id="module.auth.proxy_challenge_header">
+      <title><parameter>proxy_challenge_header</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>string</serdoc:paramtype>
+        <serdoc:paramdefault>"Proxy-Authenticate"</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>proxy_challenge_header</parameter> parameter
+        contains the name of the header field that should be used to
+        include the proxy-to-user challenge.
+      </para>
+    </refsect2> 
+
+    <refsect2 xml:id="module.auth.qop">
+      <title><parameter>qop</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>string</serdoc:paramtype>
+        <serdoc:paramdefault>"auth"</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>qop</parameter> parameter determines, which value
+        for the <parameter>qop</parameter> parameter should be included
+        in a challenge. The parameter was optional in the SIP revision
+        described by RFC 2543. The current version from RFC 3261 states,
+        however, that the parameter must be included in all challenges.
+      </para>
+      <para>
+        In digest authentication, the <parameter>qop</parameter>
+        parameter, short for ‘quality of protection’, indicates which
+        parts of a request should be used for the calculation of the
+        digest response. If the value is <literal>auth</literal>,
+        only authentication should be done and the response is solely
+        calculated using information from the challenge plus the user’s
+        password. A value of <literal>auth-int</literal> indicates that
+        in addition the integrity of the request body is to be verified.
+        For this purpose, a hash over the body is additionally included
+        in the calculation.
+      </para>
+      <para>
+        In a challenge the parameter indicates, which of these methods
+        the server supports. This can either be one of them or both,
+        separated by a comma. For challenges generated by SER, this
+        is given by the <parameter>qop</parameter> module. It may also
+        be an empty string, in which case no <parameter>qop</parameter>
+        parameter will be present in challenges created by SER. This may
+        be necessary for compatibility with some old clients but will
+        make your SER not comply with RFC 3261.
+      </para>
+      <para>
+        Protection against nonce replay attacks can be achieved by
+        additionally enabling the
+        <serdoc:modparam module="auth">nonce_count</serdoc:modparam>
+        parameter. See there for more information.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.secret">
+      <title><parameter>secret</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>string</serdoc:paramtype>
+        <serdoc:paramdefault>random value</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>secret</parameter> parameter
+        sets the secret used for the calculation of the nonce and for
+        message integrity checks. If not set, a random secret will be
+        chosen upon start.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="module.auth.www_challenge_header">
+      <title><parameter>www_challenge_header</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>string</serdoc:paramtype>
+        <serdoc:paramdefault>"WWW-Authenticate</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>www_challenge_header</parameter> parameter
+        contains the name of the header field that should be used to
+        transmit a user-to-user challenge for authentication.
+      </para>
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1 id="module.auth.integrity_checks">
+    <title>Additional Integrity Checks</title>
+    <para>
+      The auth module can perform additional integrity checks on the
+      authentication response inclued in a request by the client.
+    </para>
+    <para>
+      Without the extra checks, the nonce value will be used only to
+      store the expire time (see <parameter>nonce_expire</parameter>),
+      plus an MD5 hash over it and some secret to prevent tampering
+      with the expire time. With this arrangement, some replay attacks
+      are still possible in the expire "window".
+    </para>
+    <para>
+      A
+      possible workaround is to always force qop authentification and
+      always check the URI from the authorization header, but this does not
+      work if an upstream proxy rewrites the URI and it will also not work
+      with a lot of UA implementations.
+    </para>
+    <para>
+      When the extra checks are enabled, the nonce will include and extra
+      MD5 hash over some selected parts of the message and another secret.
+      This will be used to check if these parts of the message are the same
+      when a UA retries the request with the authentication response, thus 
+      protecting from replay attacks or at least severly limiting their
+      possibility.
+    </para>
+    <para>
+      Three module parameters control which parts of the message will be
+      included for different types of requests. The parameter
+      <parameter>auth_checks_register</parameter> sets them for REGISTER
+      requests. The parameter <parameter>auth_checks_no_dlg</parameter> 
+      does the same for requests that to not have a
+      <parameter>tag</parameter> parameter in the To header field or have
+      no To header field altogether (in other words requests sent outside
+      of an existing dialog). And, finally, the parameter
+      <parameter>auth_checks_in_dlg</parameter> controls the checks for
+      SIP requests sent within dialogs, such as BYEs or re-INVITEs.
+    </para>
+    <para>
+      The default value for all three parameters is 0, in which case no
+      extra checks are performed and the module behaves as it did before
+      their introduction. Otherwise the parameter is a bit field. The
+      message parts to be included in the check can be determined by adding
+      any of the following values together:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term><literal>1</literal></term>
+        <listitem>
+          <para>
+            check the full Request-URI,
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>2</literal></term>
+        <listitem>
+          <para>
+            check the Call-ID,
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>4</literal></term>
+        <listitem>
+          <para>
+            check the <parameter>tag</parameter> parameter of the From
+            header field,
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>9</literal></term>
+        <listitem>
+          <para>
+            check the source IP address the request was received from.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <para> 
+      For example, setting <parameter>auth_checks_register</parameter> to
+      <literal>6</literal> would check if the Call-ID or the From tag
+      have changed from the REGISTER message for which the nonce was
+      generated. This allows nonce reuse only within the same UA and
+      for the expire time.  Note that enabling the extra checks will
+      limit nonce caching by UAs, requiring extra challenges and
+      round trips, but will provide much better protection.
+    </para>
+    <para>
+      When the <parameter>secret</parameter> parameter is set and the
+      extra checks are enabled, the first half of the secret will be used
+      for the expire time hash and the other half for the hash on the
+      extra checks, so make sure you have a long secret. At least 32 
+      characterss are recommended.
+    </para>
+  </refsect1> 
+
+  <refsect1>
+    <title>See Also</title>
+    <simplelist type="inline">
+      <member><serdoc:sbin>ser</serdoc:sbin></member>
+      <member><serdoc:file>ser.cfg</serdoc:file></member>
+      <member><serdoc:module>auth_db</serdoc:module></member>
+      <member><serdoc:module>auth_diameter</serdoc:module></member>
+      <member><serdoc:module>auth_identity</serdoc:module></member>
+      <member><serdoc:module>auth_radius</serdoc:module></member>
+    </simplelist>
+  </refsect1>
+
+</refentry>
+
+<!-- vim:sw=2 sta et sts=2 ai tw=76
+  -->

modules_s/auth_identity/auth_identity.c

@@ -174,7 +174,7 @@ static int mod_init(void)
 	}
 	if (!glb_authservice_disabled && glb_sservercerturl[0]==0) {
 		LOG(L_WARN, "AUTH_IDENTITY:mod_init: URL of certificate of the server is missing! Authorization service is disabled\n");
-		glb_authservice_disabled=1;
+		glb_authservice_disabled=1;openssl verify -CAfile cacert.pem alicecert.pem
 	}
 	if (!glb_authservice_disabled && glb_sservercertpath[0]==0) {
 		LOG(L_WARN, "AUTH_IDENTITY:mod_init: Path of certificate of the server is missing! Authorization service is disabled\n");

modules_s/avp/avp.xml

@@ -0,0 +1,532 @@
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbookid/id/g/4.5/docbookx.dtd">
+
+<refentry id="module.avp"
+          xmlns:serdoc="http://sip-router.org/xml/serdoc">
+  <refmeta>
+    <refentrytitle>avp</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>avp</refname>
+    <refpurpose>Manipulation of Attributes</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      The <command>avp</command> module provides various functions for
+      the manipulation of attributes.
+    </para>
+    <para>
+      The name is a left-over from earlier versions of SER where attributes
+      were called ‘attribute-value pairs’ or AVPs for short.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Functions</title>
+
+    <refsect2 xml:id="function.append_attr_hf">
+      <title>
+        <function>append_attr_hf</function>
+        (<symbol>hf</symbol>,
+         <optional><symbol>attribute</symbol></optional>)
+      </title>
+      <para>
+        Allowed in request and failure processing.
+      </para>
+      <para>
+        The <function>append_attr_hf()</function> function appends a
+        new header field value to the header field named by the argument
+        <symbol>hf</symbol>. The new value will be populated with the
+        content of the attribute named by the argument
+        <symbol>attribute</symbol>. If the argument is missing, the content
+        is taken from the attribute with same name as the header field.
+      </para>
+     </refsect2>
+
+    <refsect2 xml:id="function.attr2uri">
+      <title>
+        <function>attr2uri</function>
+        (<symbol>attribute</symbol>,
+        <serdoc:optional><symbol>part</symbol></serdoc:optional>)
+       </title>
+      <para>
+        Allowed in request and failure processing.
+      </para>
+      <para>
+        The <function>attr2uri()</function> function sets the Request-URI
+        to the content of the attribute named by the argument
+        <symbol>attribute</symbol>. If the argument <symbol>part</symbol>
+        is present, only the part of the Request-URI identified by it
+        will be changed. This mimiks the behavior of many of the core
+        functions that allow manipulation of the Request-URI.
+      </para>
+      <para>
+        The following values are allowed for the <symbol>part</symbol>
+        argument:
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term><literal>domain</literal>, <literal>host</literal></term>
+          <listitem>
+            replace the host part of the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <literal>domainport</literal>, <literal>hostport</literal>
+          </term>
+          <listitem>
+            replace the host and port parts of the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>port</literal></term>
+          <listitem>
+            replace the port part of the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>prefix</literal></term>
+          <listitem>
+            prefix the content of the attribute to the username part of
+            the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>strip</literal></term>
+          <listitem>
+            the attribute contains an integer specifying the number of
+            characters to be stripped off the beginning of the username
+            part of the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>strip_tail</literal></term>
+          <listitem>
+            the attribute contains an integer specifyin the number of
+            characters to be stripped off the end of the username part of
+            the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>uri</literal></term>
+          <listitem>
+            replace the entire Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>user</literal>, <literal>username</literal></term>
+          <listitem>
+            replace the username part of the Request-URI,
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <literal>userpass</literal>,
+            <literal>usernamepassword</literal>
+          </term>
+          <listitem>
+            replace the username and password parts of the Request-URI.
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2 xml:id="function.attr_destination">
+      <title>
+        <function>attr_destination</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request and failure processing.
+      </para>
+      <para>
+        The <function>attr_destination()</function> function sets the
+        destination URI to the content of the attribute named by the
+        argument <symbol>attribute</symbol>.
+      </para>
+      <para>
+        If the destination URI is set, the request will be send to the
+        address determined from that URI instead of the Request-URI. It
+        will carried over into branches together with the Request-URI when a
+        call to <serdoc:func>append_branch</serdoc:func> is made.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.attr_equals">
+      <title>
+        <function>attr_equals</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>attr_equals()</function> function checks whether
+        the attribute identified by the argument <symbol>attribute</symbol>
+        exists and its value is identical the the value given by the
+        argument <symbol>value</symbol>. If so, it returns
+        <literal>true</literal> and <literal>false</literal> otherwise.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.attr_equals_xl">
+      <title>
+        <function>attr_equals_xl</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>attr_equals()</function> function checks whether
+        the attribute identified by the argument <symbol>attribute</symbol>
+        exists and its value is identical to the xl string given by the
+        argument <symbol>value</symbol>.  If so, it returns
+        <literal>true</literal> and <literal>false</literal> otherwise.
+      </para>
+      <para>
+        For more information on xl strings, see
+        <serdoc:module>xlog</serdoc:module>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.attr_exists">
+      <title>
+        <function>attr_exists</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>attr_exists()</function> function checks whether
+        an attribute by the name given by the name of
+        <symbol>attribute</symbol> exists and returns
+        <literal>true</literal> in this case or <literal>false</literal>
+        otherwise.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.attr_to_reply">
+      <title>
+        <function>attr_to_reply</function>
+        (<symbol>hf</symbol>,
+        <serdoc:optional><symbol>attribute</symbol></serdoc:optional>)
+      </title>
+      <para>
+        Allowed in request and failure processing.
+      </para>
+      <para>
+        The <function>attr_to_reply()</function> function adds a new
+        header fields value to the final response that will eventually
+        be sent upstream. The name of the header field is given by the
+        argument <symbol>hf</symbol>. The content will be taken from an
+        attribute. If the argument <symbol>attribute</symbol> is present,
+        it contains the name of the attribute. Otherwise, the header field
+        name from the argument <symbol>hf</symbol> will be taken as the
+        name.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.del_attr">
+      <title>
+        <function>del_attr</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>del_attr</function> function deletes the attribute
+        identified by the argument <symbol>attribute</symbol>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.del_attrs">
+      <title>
+        <function>del_attrs</function>
+        (<symbol>group</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>del_attrs()</function> function deletes all
+        attributes from the group of attributes identified by the
+        attribute prefix given through the argument <symbol>group</symbol>.
+        For example, to delete all attributes of the From user, call
+      </para>
+      <programlisting>
+        del_attrs("$fu");
+      </programlisting>
+    </refsect2>
+
+    <refsect2 xml:id="function.dump_attrs">
+      <title>
+        <function>dump_attrs</function>
+        (<serdoc:optional><symbol>group</symbol></serdoc:optional>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>dump_attrs()</function> dumps a list of the existing
+        attributes and their values to the system log. If the
+        <symbol>group</symbol> argument is present, it contains an
+        attribute namespace prefix and limits the output to the attrbutes
+        in that namespace.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.flags2attr">
+      <title>
+        <function>flags2attr</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>flags2attr()</function> function stores the current
+        state of all the flags in compact form in the attribute identified
+        by the argument <symbol>attribute</symbol>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.insert_attr_hf">
+      <title>
+        <function>insert_attr_hf</function>
+        (<symbol>hf</symbol>,
+         <serdoc:optional><symbol>attribute</symbol></serdoc:optional>)
+       </title>
+       <para>
+         Allowed in request and failure processing.
+       </para>
+       <para>
+         The <function>insert_attr_hf()</function> function inserts a
+         header field value to the header field named by the argument
+         <symbol>hf</symbol> with the value of the attribute identified
+         by the argument <symbol>attribute</symbol>. If there are already
+         values for that header field, the new value will be prepended
+         before any existing value.
+       </para>
+       <para>
+         If the optional argument <symbol>attribute</symbol> is missing,
+         the name of the attribute is taken from the name of the header
+         field in argument <symbol>hf</symbol>.
+       </para>
+     </refsect2>
+
+    <refsect2 xml:id="function.print_attr">
+      <title>
+        <function>print_attr</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>print_attr()</function> function prints the content
+        of the attribute identified by the argument
+        <symbol>attribute</symbol> to the system log.
+      </para>
+      <para>
+        For a more flexible way of printing messages to the system log
+        that allows to print extra information together with the attribute
+        value, see the <serdoc:module>xlog</serdoc:module> module.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.replace_attr_hf">
+      <title>
+        <function>replace_attr_hf</function>
+        (<symbol>hf</symbol>,
+        <serdoc:optional><symbol>attribute</symbol></serdoc:optional>)
+      </title>
+      <para>
+        Allowed in request and failure processing.
+      </para>
+      <para>
+        The <function>replace_attr_hf()</function> function removes all
+        header field values of the header field named by the argument
+        <symbol>hf</symbol> and adds a new header field value with the
+        content of the attribute identified by the argument
+        <symbol>attribute</symbol>. If the argument
+        <symbol>attribute</symbol> is missing, the content of the new
+        header field value will be taken from an argument with the same
+        name as the header field.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.set_attr">
+      <title>
+        <function>set_attr</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>set_attr()</function> function is a synonym for
+        the <serdoc:func>set_sattr</serdoc:func> function and sets the
+        attribute identified by the argument <symbol>attribute</symbol>
+        to the string contained in the argument <symbol>value</symbol>.
+      </para>
+      <para>
+        Like <serdoc:func>set_sattr</serdoc:func>, it is identical to
+        assinging an string using the assignment operator and is
+        deprecated.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.set_iattr">
+      <title>
+        <function>set_iattr</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>set_iattr()</function> function sets the attribute
+        identified by the argument <symbol>attribute</symbol> to the
+        integer value contained in the argument <symbol>value</symbol>.
+        If the attribute does not yet exist, it is created.
+      </para>
+      <para>
+        This function is identical to assinging an integer using the
+        assignment operator and
+        is only kept to retain compatibility with earlier versions of SER.
+        It therefore is deprecated and may be removed in the future.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.set_sattr">
+      <title>
+        <function>set_sattr</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>set_sattr()</function> function sets the attribute
+        identified by the argument <symbol>attribute</symbol> to the
+        string contained in the argument <symbol>value</symbol>. If the
+        attribute does not yet exist, it is created.
+      </para>
+      <para>
+        This function is identical to assinging an string using the
+        assignment operator and
+        is only kept to retain compatibility with earlier versions of SER.
+        It therefore is deprecated and may be removed in the future.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.subst_attr">
+      <title>
+        <function>subst_attr</function>
+        (<symbol>attribute</symbol>, <symbol>subst</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>subst_attr()</function> function manipulates the
+        content of the attribute identified by the argument
+        <symbol>attribute</symbol> using a subst expression.
+      </para>
+      <para>
+        A subst expression is identical to the expression used by the
+        <serdoc:bin>sed</serdoc:bin> program’s s command.
+      </para>
+      <!-- XXX We should either explain them in detail here, or in textops
+               or in the admin guide. In any case, there needs to be a
+               reference to the explanation.
+        -->
+    </refsect2>
+
+    <refsect2 xml:id="function.xlfix_attr">
+      <title>
+        <function>xlfix_attr</function>
+        (<symbol>attribute</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>xlfix_attr()</function> function evaluates the xl
+        string contained in the attributed identified by the argument
+        <symbol>attribute</symbol> and stores the result of the evaluation
+        in the same attribute.
+      </para>
+      <para>
+        For more information on xl strings, see
+        <serdoc:module>xlog</serdoc:module>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.xlset_attr">
+      <title>
+        <function>xlset_attr</function>
+        (<symbol>attribute</symbol>, <symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request, reply, and failure processing.
+      </para>
+      <para>
+        The <function>xlset_attr()</function> function sets the attribute
+        identified by the argument <symbol>attribute</symbol> to the
+        evaluated xl string given by the argument <symbol>value</symbol>.
+      </para>
+      <para>
+        For more information on xl strings, see
+        <serdoc:module>xlog</serdoc:module>.
+      </para>
+    </refsect2>
+
+    <refsect2 xml:id="function.xlset_destination">
+      <title>
+        <function>xlset_destination</function>
+        (<symbol>value</symbol>)
+      </title>
+      <para>
+        Allowed in request processing only.
+      </para>
+      <para>
+        The <function>xlset_destination()</function> function sets the
+        destination URI to the evaluated content of the xl string given
+        by the argument <symbol>value</symbol>.
+      </para>
+      <para>
+        For details on xl strings, see <serdoc:module>xlog</serdoc:module>.
+      </para>
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Module Parameters</title>
+
+    <refsect2 xml:id="module.avp.xlbuf_size">
+      <title><parameter>xlbuf_size</parameter></title>
+      <serdoc:paraminfo>
+        <serdoc:paramtype>integer</serdoc:paramtype>
+        <serdoc:paramdefault>256</serdoc:paramdefault>
+      </serdoc:paraminfo>
+      <para>
+        The <parameter>xlbuf_size</parameter> parameter defines the size
+        of the buffer that used for evaluation of xl strings. The evaluated
+        string cannot be larger than the size given by this parameter.
+      </para>
+    </refsect2>
+  </refsect1>
+</refentry>
+
+<!-- vim:sw=2 sta et sts=2 ai tw=76
+  -->