Merge remote branch 'origin/sr_3.0'
[sip-router] / modules / sanity / README
1 1. Sanity Module
2
3 Nils Ohlmeier
4
5    iptelorg GmbH
6
7    Copyright © 2006 iptelorg GmbH
8    Revision History
9    Revision $Revision$ $Date$
10      __________________________________________________________________
11
12    1.1. Overview
13    1.2. Dependencies
14    1.3. Parameters
15
16         1.3.1. default_checks (integer)
17         1.3.2. uri_checks (integer)
18         1.3.3. proxy_require (string)
19
20    1.4. Functions
21
22         1.4.1. sanity_check()
23
24 1.1. Overview
25
26    This module aims to implement several sanity checks on incoming
27    requests which are suggested or even required by a RFC, but are not
28    available yet in the core of SIP-router.
29
30    This checks are not required by SIP-router itself for its
31    functionality. But on the other side it makes not much sence if a
32    broken request traverses through a SIP network if it is rejected sooner
33    or later by a SIP device any way. As every sanity cost extra
34    performance because of additional parsing and evaluation it is now with
35    this module up to the SIP-router adminstrator which checks should be
36    done on which request.
37
38    The following checks are available:
39      * ruri sip version - (1) - checks if the SIP version in the request
40        URI is supported, currently only 2.0.
41      * ruri scheme - (2) - checks if the URI scheme of the request URI is
42        supported (sip[s]|tel[s]) by SIP-router.
43      * required headers - (4) -checks if the minimum set of required
44        headers to, from, cseq, callid and via is present in the request.
45      * via sip version - (8) - not working because parser fails already
46        when another version then 2.0 is present.
47      * via protocol - (16) - not working because parser fails already if
48        an unsupported transport is present.
49      * cseq method - (32) - checks if the method from the cseq header is
50        equal to the request method.
51      * cseq value - (64) - checks if the number in the cseq header is a
52        valid unsigend integer.
53      * content length - (128) - checks if the size of the body matches
54        with the value from the content length header.
55      * expires value - (256) - checks if the value of the expires header
56        is a valid unsigned integer.
57      * proxy require - (512) - checks if all items of the proxy require
58        header are present in the list of the extensions from the module
59        parameter proxy_require.
60      * parse uri's - (1024) - checks if the specified URIs are present and
61        parseable by the SIP-router parsers
62      * digest credentials (2048) Check all instances of digest credentials
63        in a message. The test checks whether there are all required digest
64        parameters and have meaningful values.
65
66 1.2. Dependencies
67
68    The following modules must be loaded before this module:
69      * sl - Stateless replies.
70
71 1.3. Parameters
72
73    Revision History
74    Revision $Revision$ $Date$
75
76 1.3.1. default_checks (integer)
77
78    This parameter determines which of the checks from the sanity module
79    are executed if no parameter was given to the sanity_check function
80    call. By default all implemented checks are included in the execution
81    of the sanity_check function. The integer value is the sum of the check
82    numbers which should be executed by default.
83
84    Default value is 999. This resolves to the following list of checks:
85    ruri_sip_version (1), ruri_scheme (2), required_headers (4),
86    cseq_method (32), cseq_value (64), cotent_length (128), expires_value
87    (256), proxy_require (512).
88
89    Example 1. Set default_checks parameter
90 ...
91 modparam("sanity", "default_checks", "1")
92 ...
93
94 1.3.2. uri_checks (integer)
95
96    This parameter determines which URIs are going to be checked if the
97    'parse uri' will be executed.
98
99    Default value is 7. This resolves to the following list of parsed URIs:
100    Request RUI (1), From URI (2) and To URI (4).
101
102 1.3.3. proxy_require (string)
103
104    This parameter set the list of supported extensions for this
105    SIP-router. The value is expected as comma separated list of the
106    extensions. This list is separated into single tokens. Each token from
107    a proxy require header will be compare to the tokens from this list.
108
109    Example 2. Set proxy_require parameter
110 ...
111 modparam("sanity", "proxy_require", "foo, bar")
112 ...
113
114 1.4. Functions
115
116    Revision History
117    Revision $Revision$ $Date$
118
119 1.4.1. sanity_check()
120
121    This function makes a row of sanity checks on the given request. The
122    function returns true if one of the checks failed. If one of the checks
123    fails the module sends a precise error reply via sl_send_reply. Thus
124    their is no need to reply with a generic error message.
125
126    Example 3. sanity_check usage
127 ...
128 if (sanity_check()) {
129         break;
130 }
131 ...
132
133    Optionally the function takes an integer argument which overwrites the
134    global module parameter default_checks. This allows to make certain
135    test from script regions. The integer value is again the sum of the
136    checks (like for the module parameter) which should be executed at this
137    function call.
138
139    Example 4. sanity_check usage with parameter
140 ...
141 if (method=="REGISTER" && sanity_check("256")) {
142         /* the register contains an invalid expires value and is replied with a
143 400 */
144         break;
145 }
146 ...
147
148    Optionally the function takes a second integer argument which
149    overwrites the global module parameter uri_checks and thus determines
150    which URIs will be checked if the parse uri test will be executed.
151
152    Example 5. sanity_check usage with two parameters
153 ...
154 if (method=="INVITE" && sanity_check("1024", "6")) {
155         /* the INVITE contains an invalid From or To header and is replied with
156 a 400 */
157         break;
158 }
159 ...