The Sanity Module - SIP syntax checking

Nils Ohlmeier

   iptelorg GmbH

   Copyright © 2006 iptelorg GmbH
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies
        3. Parameters

              3.1. default_checks (integer)
              3.2. uri_checks (integer)
              3.3. proxy_require (string)
              3.4. autodrop (integer)
              3.5. noreply (int)
              3.6. size_checks (int)
              3.7. size_message (int)
              3.8. size_headers (int)
              3.9. size_body (int)
              3.10. size_header (int)
              3.11. size_method (int)
              3.12. size_ruri (int)
              3.13. size_from_uri (int)
              3.14. size_to_uri (int)
              3.15. size_contact_uri (int)
              3.16. size_route_uri (int)
              3.17. size_path_uri (int)
              3.18. size_pai_uri (int)

        4. Functions

              4.1. sanity_check([msg_checks [, uri_checks]])
              4.2. sanity_reply()

   List of Examples

   1.1. Set default_checks parameter
   1.2. Set uri_checks parameter
   1.3. Set proxy_require parameter
   1.4. Set autodrop parameter
   1.5. Set noreply parameter
   1.6. Set size_checks parameter
   1.7. Set size_message parameter
   1.8. Set size_headers parameter
   1.9. Set size_body parameter
   1.10. Set size_header parameter
   1.11. Set size_method parameter
   1.12. Set size_ruri parameter
   1.13. Set size_from_uri parameter
   1.14. Set size_to_uri parameter
   1.15. Set size_contact_uri parameter
   1.16. Set size_route_uri parameter
   1.17. Set size_path_uri parameter
   1.18. Set size_pai_uri parameter
   1.19. sanity_check usage
   1.20. sanity_check usage with parameter
   1.21. sanity_check usage with two parameters
   1.22. sanity_reply usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies
   3. Parameters

        3.1. default_checks (integer)
        3.2. uri_checks (integer)
        3.3. proxy_require (string)
        3.4. autodrop (integer)
        3.5. noreply (int)
        3.6. size_checks (int)
        3.7. size_message (int)
        3.8. size_headers (int)
        3.9. size_body (int)
        3.10. size_header (int)
        3.11. size_method (int)
        3.12. size_ruri (int)
        3.13. size_from_uri (int)
        3.14. size_to_uri (int)
        3.15. size_contact_uri (int)
        3.16. size_route_uri (int)
        3.17. size_path_uri (int)
        3.18. size_pai_uri (int)

   4. Functions

        4.1. sanity_check([msg_checks [, uri_checks]])
        4.2. sanity_reply()

1. Overview

   This module aims to implement several sanity checks on incoming
   requests which are suggested or even required by a RFC, but are not
   available yet in the core of Kamailio.

   These checks are not required by Kamailio itself for its functionality.
   But on the other side it does not make much sense if a broken request
   traverses through a SIP network if it is rejected sooner or later by a
   SIP device any way. As every sanity check cost extra performance
   because of additional parsing and evaluation it is with this module now
   up to the Kamailio administrator what checks should be done on which
   request.

   The following checks are available:
     * ruri sip version - (1 [0x01 / 2^0]) - checks if the SIP version in
       the request URI is supported, currently only 2.0.
     * ruri scheme - (2 [0x02 / 2^1]) - checks if the URI scheme of the
       request URI is supported (sip[s]|tel[s]) by Kamailio
     * required headers - (4 [0x04 / 2^2]) -checks if the minimum set of
       required headers To, From, CSeq, Call-ID and Via is present in the
       request.
     * via sip version - (8 [0x08 / 2^3]) - disabled.
     * via protocol - (16 [0x10 / 2^4]) - disabled.
     * Cseq method - (32 [0x20 / 2^5]) - checks if the method from the
       CSeq header is equal to the request method.
     * Cseq value - (64 [0x40 / 2^6]) - checks if the number in the CSeq
       header is a valid unsigned integer.
     * content length - (128 [0x80 / 2^7]) - checks if the size of the
       body matches with the value from the Content-Length header.
     * expires value - (256 [0x100 / 2^8]) - checks if the value of the
       Expires header is a valid unsigned integer.
     * proxy require - (512 [0x200 / 2^9]) - checks if all items of the
       Proxy-Require header are present in the list of the extensions from
       the module parameter proxy_require.
     * parse uri's - (1024 [0x400 / 2^10]) - checks if the specified URIs
       are present and parseable by the Kamailio parsers
     * digest credentials (2048 [0x800 / 2^11]) - Check all instances of
       digest credentials in a message. The test checks whether there are
       all required digest parameters and that they have meaningful
       values. NOTE: the message will be considered invalid if the
       authorization scheme differs from "digest",
     * duplicated To/From tags (4096 [0x1000 / 2^12]) - checks for the
       presence of duplicated tags in To/From headers.
     * Authorization header (8192 [0x2000 / 2^13]) - checks if the
       Authorization header is valid if the scheme is "digest" (see
       "digest credentials" above), always returns success for other
       schemes.
     * first Via header (16384 [0x4000 / 2^14]) - checks if the first Via
       header is available, can be parsed, has an address value, and the
       branch parameter is present.
     * RFC3261 compliance related checks (32768 [0x8000 / 2^15]) - checks
       if the branch parameter of the first Via header starts with magic
       cookie: 'z9hG4bK'. Also checks that the lr parameter is present in
       Record-Route and Route headers if they are present.
     * size checks (65536 [0x10000 / 2^16]) - do the size checks for SIP
       message attributes (alternative to size_checks module parameter).

2. Dependencies

   The following modules must be loaded before this module:
     * sl - Stateless replies.

3. Parameters

   3.1. default_checks (integer)
   3.2. uri_checks (integer)
   3.3. proxy_require (string)
   3.4. autodrop (integer)
   3.5. noreply (int)
   3.6. size_checks (int)
   3.7. size_message (int)
   3.8. size_headers (int)
   3.9. size_body (int)
   3.10. size_header (int)
   3.11. size_method (int)
   3.12. size_ruri (int)
   3.13. size_from_uri (int)
   3.14. size_to_uri (int)
   3.15. size_contact_uri (int)
   3.16. size_route_uri (int)
   3.17. size_path_uri (int)
   3.18. size_pai_uri (int)

3.1. default_checks (integer)

   This parameter determines which of the checks from the sanity module
   are executed if no parameter was given to the sanity_check function
   call. By default all implemented checks are included in the execution
   of the sanity_check function. The integer value is the sum of the check
   numbers which should be executed by default.

   Default value is “3047”. This resolves to the following list of checks:
   ruri_sip_version (1), ruri_scheme (2), required_headers (4),
   cseq_method (32), cseq_value (64), content_length (128), expires_value
   (256), proxy_require (512), digest credentials (2048).

   Example 1.1. Set default_checks parameter
...
modparam("sanity", "default_checks", 1)
...

3.2. uri_checks (integer)

   This parameter determines which URIs are going to be checked if the
   'parse uri' will be executed.

   Default value is 7. This resolves to the following list of parsed URIs:
   Request URI (1), From URI (2) and To URI (4). Additionally the Contact
   URI can be also checked (8).

   Example 1.2. Set uri_checks parameter
...
modparam("sanity", "uri_checks", 3)
...

3.3. proxy_require (string)

   This parameter sets the list of supported SIP extensions for this
   Kamailio. The value is expected as a comma separated list (leading and
   trailing whitespaces are stripped from each token) of extensions. This
   list is separated into single tokens. Each token from a proxy require
   header will be compared with the tokens from this list.

   Example 1.3. Set proxy_require parameter
...
modparam("sanity", "proxy_require", "foo, bar")
...

3.4. autodrop (integer)

   This parameter controls whether the module drops the SIP message
   automatically if the sanity checks fail. Default value is 1 (auto
   drop). If set to 0, sanity_check() function will return -1 (false) to
   configuration file, allowing to write log messages for example - be
   sure you “exit” execution of config without sending a SIP reply because
   it is sent by module itself.

   Example 1.4. Set autodrop parameter
...
modparam("sanity", "autodrop", 1)
...

3.5. noreply (int)

   If set to 1, then the module does not send a SIP reply internally in
   case there is an error detected when performing the sanity checks.
   There is the option to send the reply from config file with functions
   from sl or tm module as well as sanity_reply() from this module.

   Default value: 0.

   Example 1.5. Set noreply parameter
...
modparam("sanity", "noreply", 1)
...

3.6. size_checks (int)

   If set to 1, then the module performs the size checks for various SIP
   message attributes when using sanity_check() function. The size of each
   attribute can be set by a dedicated parameter, see the next sections.
   If the size is greater than the corresponding parameter value, then the
   sanity check failed.

   This enables the size checks globally, for all uses of sanity_check()
   function. To enable it per function call, set the corresponding flag in
   the sanity_check() parameter.

   Default value: 0.

   Example 1.6. Set size_checks parameter
...
modparam("sanity", "size_checks", 1)
...

3.7. size_message (int)

   Specify the size of the SIP message to do sanity check with. If set to
   0, this size sanity check is not performed.

   Default value: 16384.

   Example 1.7. Set size_message parameter
...
modparam("sanity", "size_message", 8192)
...

3.8. size_headers (int)

   Specify the size of the SIP message headers (all together) to do sanity
   check with. If set to 0, this size sanity check is not performed.

   Default value: 8192.

   Example 1.8. Set size_headers parameter
...
modparam("sanity", "size_headers", 4096)
...

3.9. size_body (int)

   Specify the size of the SIP message body to do sanity check with. If
   set to 0, this size sanity check is not performed.

   Default value: 8192.

   Example 1.9. Set size_body parameter
...
modparam("sanity", "size_body", 4096)
...

3.10. size_header (int)

   Specify the size of the SIP message header to do sanity check with. The
   check is done for each header, including its name and value. If set to
   0, this size sanity check is not performed.

   Default value: 2048.

   Example 1.10. Set size_header parameter
...
modparam("sanity", "size_header", 1024)
...

3.11. size_method (int)

   Specify the size of the SIP method to do sanity check with (taken from
   first line for SIP request and from CSeq for SIP reply). If set to 0,
   this size sanity check is not performed.

   Default value: 32.

   Example 1.11. Set size_method parameter
...
modparam("sanity", "size_method", 16)
...

3.12. size_ruri (int)

   Specify the size of the SIP request URI to do sanity check with. If set
   to 0, this size sanity check is not performed.

   Default value: 256.

   Example 1.12. Set size_ruri parameter
...
modparam("sanity", "size_ruri", 512)
...

3.13. size_from_uri (int)

   Specify the size of the SIP message From-URI to do sanity check with.
   If set to 0, this size sanity check is not performed.

   Default value: 256.

   Example 1.13. Set size_from_uri parameter
...
modparam("sanity", "size_from_uri", 512)
...

3.14. size_to_uri (int)

   Specify the size of the SIP message To-URI to do sanity check with. If
   set to 0, this size sanity check is not performed.

   Default value: 256.

   Example 1.14. Set size_to_uri parameter
...
modparam("sanity", "size_to_uri", 512)
...

3.15. size_contact_uri (int)

   Specify the size of the SIP message Contact-URI to do sanity check
   with. If set to 0, this size sanity check is not performed.

   Default value: 256.

   Example 1.15. Set size_contact_uri parameter
...
modparam("sanity", "size_contact_uri", 512)
...

3.16. size_route_uri (int)

   Specify the size of the SIP message Route-URI and Record-Route-URI to
   do sanity check with. If set to 0, this size sanity check is not
   performed.

   Default value: 256.

   Example 1.16. Set size_route_uri parameter
...
modparam("sanity", "size_route_uri", 512)
...

3.17. size_path_uri (int)

   Specify the size of the SIP message Path-URI to do sanity check with.
   If set to 0, this size sanity check is not performed.

   Default value: 256.

   Example 1.17. Set size_path_uri parameter
...
modparam("sanity", "size_path_uri", 512)
...

3.18. size_pai_uri (int)

   Specify the size of the SIP message P-Asserted-Identity URI to do
   sanity check with. If set to 0, this size sanity check is not
   performed.

   Default value: 256.

   Example 1.18. Set size_pai_uri parameter
...
modparam("sanity", "size_pai_uri", 512)
...

4. Functions

   4.1. sanity_check([msg_checks [, uri_checks]])
   4.2. sanity_reply()

4.1.  sanity_check([msg_checks [, uri_checks]])

   This function makes a row of sanity checks over the given SIP request.
   The behavior of the function is also controlled by autodrop parameter.
   If autodrop=0, the function returns false (-1) if one of the checks
   failed. When autodrop=1, the function stops the execution of
   configuration file. In both cases, if one of the checks fails the
   module sends a precise error reply via SL send_reply(). Thus there is
   no need to reply with a generic error message.

   The parameters can be static integers or variables holding integer
   values.

   Example 1.19. sanity_check usage
...
if (!sanity_check()) {
        exit;
}
...

   Optionally the function takes an integer argument which overwrites the
   global module parameter default_checks. This makes it possible to run
   certain tests from script regions. The integer value is again the sum
   of the checks (like for the module parameter) which should be executed
   at this function call.

   Example 1.20. sanity_check usage with parameter
...
if (method=="REGISTER" && !sanity_check("256")) {
        /* the register contains an invalid expires value and is replied with a
400 */
        exit;
}
...

   Optionally the function takes a second integer argument which
   overwrites the global module parameter uri_checks and thus determines
   which URIs will be checked if the parse uri test will be executed.

   Example 1.21. sanity_check usage with two parameters
...
if (method=="INVITE" && !sanity_check("1024", "6")) {
        /* the INVITE contains an invalid From or To header and is replied with
a 400 */
        exit;
}
...

4.2.  sanity_reply()

   Send a SIP reply using the code and reason text set internally by the
   module when detecting errors while performing the sanity checks. It is
   done only when parameter noreply is set to 1.

   Example 1.22. sanity_reply usage
...
if(!sanity_check("1024", "6")) {
   xdbg("sanity checks failed\n");
   sanity_reply();
   exit;
}
...
