ims_ipsec_pcscf: add back the README file
[sip-router] / src / modules / ims_ipsec_pcscf / README
1 The IMS IPSec-Registrar Module
2
3 Dragos Vingarzan
4
5    FhG Fokus
6    <Dragos.Vingarzan@fokus.fraunhofer.de>
7
8 Jason Penton
9
10    Smile Communications
11    <jason.penton@smilecoms.com>
12
13 Richard Good
14
15    Smile Communications
16    <richard.good@smilecoms.com>
17
18 Carsten Bock
19
20    ng-voice GmbH
21    <carsten@ng-voice.com>
22
23 Tsvetomir Dimitrov
24
25    <tsv.dimitrov@gmail.com>
26
27    Copyright © 2007 FhG FOKUS
28
29    Copyright © 2012 Smile Communications
30
31    Copyright © 2015 ng-voice GmbH
32      __________________________________________________________________
33
34    Table of Contents
35
36    1. Admin Guide
37
38         1. Overview
39         2. Dependencies
40
41               2.1. Kamailio Modules
42               2.2. External Libraries or Applications
43
44         3. Parameters
45
46               3.1. ipsec_listen_addr (string)
47               3.2. ipsec_listen_addr6 (string)
48               3.3. ipsec_client_port (int)
49               3.4. ipsec_server_port (int)
50               3.5. ipsec_spi_id_start (int)
51               3.6. ipsec_spi_id_range (int)
52
53         4. Functions
54
55               4.1. ipsec_create(domain)
56               4.2. ipsec_forward(domain)
57               4.3. ipsec_destroy(domain)
58
59    List of Examples
60
61    1.1. ipsec_listen_addr parameter usage
62    1.2. ipsec_listen_addr6 parameter usage
63    1.3. ipsec_client_port parameter usage
64    1.4. ipsec_server_port parameter usage
65    1.5. ipsec_spi_id_start parameter usage
66    1.6. ipsec_spi_id_range parameter usage
67    1.7. ipsec_create
68    1.8. ipsec_forward
69    1.9. ipsec_forward
70
71 Chapter 1. Admin Guide
72
73    Table of Contents
74
75    1. Overview
76    2. Dependencies
77
78         2.1. Kamailio Modules
79         2.2. External Libraries or Applications
80
81    3. Parameters
82
83         3.1. ipsec_listen_addr (string)
84         3.2. ipsec_listen_addr6 (string)
85         3.3. ipsec_client_port (int)
86         3.4. ipsec_server_port (int)
87         3.5. ipsec_spi_id_start (int)
88         3.6. ipsec_spi_id_range (int)
89
90    4. Functions
91
92         4.1. ipsec_create(domain)
93         4.2. ipsec_forward(domain)
94         4.3. ipsec_destroy(domain)
95
96 1. Overview
97
98    This module contains methods for IPSec initialisation/deinitialisation
99    related for usage of Kamailio as a Proxy-CSCF.
100
101 2. Dependencies
102
103    2.1. Kamailio Modules
104    2.2. External Libraries or Applications
105
106 2.1. Kamailio Modules
107
108    The Following modules must be loaded before this module:
109      * Usrloc PCSCF
110      * TM
111
112 2.2. External Libraries or Applications
113
114    This modules requires the internal IMS library and libmnl for operating
115    with netlink sockets.
116
117 3. Parameters
118
119    3.1. ipsec_listen_addr (string)
120    3.2. ipsec_listen_addr6 (string)
121    3.3. ipsec_client_port (int)
122    3.4. ipsec_server_port (int)
123    3.5. ipsec_spi_id_start (int)
124    3.6. ipsec_spi_id_range (int)
125
126 3.1. ipsec_listen_addr (string)
127
128    IP address which the Proxy-CSCF will use for incoming/outgoing SIP
129    traffic over IPSec.
130
131    Default value is empty string (null) - IPv4 listen interface will not
132    be added
133
134    Example 1.1. ipsec_listen_addr parameter usage
135 ...
136 modparam("ims_ipsec_pcscf", "ipsec_listen_addr", "")
137 ...
138
139 3.2. ipsec_listen_addr6 (string)
140
141    IPv6 address which the Proxy-CSCF will use for incoming/outgoing SIP
142    traffic over IPSec.
143
144    Default value is empty string (null) - IPv6 listen interface will not
145    be added
146
147    Example 1.2. ipsec_listen_addr6 parameter usage
148 ...
149 modparam("ims_ipsec_pcscf", "ipsec_listen_addr6", "")
150 ...
151
152 3.3. ipsec_client_port (int)
153
154    Port number which will be bound for incoming (server) IPSec traffic.
155
156    Default value is 5963.
157
158    Example 1.3. ipsec_client_port parameter usage
159 ...
160 modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
161 ...
162
163 3.4. ipsec_server_port (int)
164
165    Port number which will be bound for incoming (server) IPSec traffic.
166
167    Default value is 5063.
168
169    Example 1.4. ipsec_server_port parameter usage
170 ...
171 modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
172 ...
173
174 3.5. ipsec_spi_id_start (int)
175
176    Each IPSec tunnel has a unique system-wide identifier. This and the
177    following option allows to tune the SPIs used by Kamailio in order to
178    avoid collisions with other IPSec useres. If Kamailio is the only
179    process on the system which uses IPSec, don't bother with this option.
180
181    Default value is 100.
182
183    Example 1.5. ipsec_spi_id_start parameter usage
184 ...
185 modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
186 ...
187
188 3.6. ipsec_spi_id_range (int)
189
190    How many SPIs to be allocated for the process. E.g. if
191    ipsec_spi_id_start = 100 and ipsec_spi_id_range = 1000, SPIs between
192    100 and 1100 will be used.
193
194    Default value is 1000.
195
196    Example 1.6. ipsec_spi_id_range parameter usage
197 ...
198 modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
199 ...
200
201 4. Functions
202
203    4.1. ipsec_create(domain)
204    4.2. ipsec_forward(domain)
205    4.3. ipsec_destroy(domain)
206
207 4.1. ipsec_create(domain)
208
209    This function creates IPSec SA and Policy based on the parameters sent
210    in Security-Client header in the REGISTER message. It's called when OK
211    is received. The function also adds Security-Server header to the
212    REGISTER.
213
214    Meaning of the parameters is as follows:
215      * domain - Logical domain within the registrar. If a database is used
216        then this must be name of the table which stores the contacts.
217
218    Example 1.7. ipsec_create
219 ...
220 ipsec_create("location");
221 ...
222
223 4.2. ipsec_forward(domain)
224
225    The function processes redirects outgoing message via the IPSec tunnel
226    initiated with ipsec_create().
227
228    Meaning of the parameters is as follows:
229      * domain - Logical domain within the registrar. If a database is used
230        then this must be name of the table which stores the contacts.
231
232    Example 1.8. ipsec_forward
233 ...
234 ipsec_forward("location");
235 ...
236
237 4.3. ipsec_destroy(domain)
238
239    The function destroys IPSec tunnel, created with ipsec_create.
240
241    Meaning of the parameters is as follows:
242      * domain - Logical domain within the registrar. If a database is used
243        then this must be name of the table which stores the contacts.
244
245    Example 1.9. ipsec_forward
246 ...
247 ipsec_destroy("location");
248 ...