kamailio/modules/auth/auth.xml

<?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
  -->