Browse code

ims_ipsec_pcscf: added README file

Daniel-Constantin Mierla authored on 02/08/2018 08:43:28
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,244 @@
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_client_port (int)
48
+              3.3. ipsec_server_port (int)
49
+              3.4. ipsec_spi_id_start (int)
50
+              3.5. ipsec_spi_id_range (int)
51
+
52
+        4. Functions
53
+
54
+              4.1. ipsec_create(domain)
55
+              4.2. ipsec_forward(domain)
56
+              4.3. ipsec_destroy(domain)
57
+
58
+   List of Examples
59
+
60
+   1.1. ipsec_listen_addr parameter usage
61
+   1.2. ipsec_client_port parameter usage
62
+   1.3. ipsec_server_port parameter usage
63
+   1.4. ipsec_spi_id_start parameter usage
64
+   1.5. ipsec_spi_id_range parameter usage
65
+   1.6. ipsec_create
66
+   1.7. ipsec_forward
67
+   1.8. ipsec_forward
68
+
69
+Chapter 1. Admin Guide
70
+
71
+   Table of Contents
72
+
73
+   1. Overview
74
+   2. Dependencies
75
+
76
+        2.1. Kamailio Modules
77
+        2.2. External Libraries or Applications
78
+
79
+   3. Parameters
80
+
81
+        3.1. ipsec_listen_addr (string)
82
+        3.2. ipsec_client_port (int)
83
+        3.3. ipsec_server_port (int)
84
+        3.4. ipsec_spi_id_start (int)
85
+        3.5. ipsec_spi_id_range (int)
86
+
87
+   4. Functions
88
+
89
+        4.1. ipsec_create(domain)
90
+        4.2. ipsec_forward(domain)
91
+        4.3. ipsec_destroy(domain)
92
+
93
+1. Overview
94
+
95
+   This module contains methods for IPSec initialisation/deinitialisation
96
+   related for usage of Kamailio as a Proxy-CSCF.
97
+
98
+   Important notice!!! Currently the module doesn't clear the IPSec
99
+   tunnels( Policies and Security associations, in XFRM terms) on startup
100
+   and shutdown. This will be fixed in future releases. For the moment the
101
+   following command can be used to clear the tunnels manually:
102
+
103
+   ip xfrm state deleteall
104
+
105
+   ip xfrm policy deleteall
106
+
107
+   Please note that this will clear ALL xfrm states and policies. This
108
+   means that it will interfere with other IPSec applications on the
109
+   machine. If this is the case, Kamailio's states and policies should be
110
+   cleared manually.
111
+
112
+2. Dependencies
113
+
114
+   2.1. Kamailio Modules
115
+   2.2. External Libraries or Applications
116
+
117
+2.1. Kamailio Modules
118
+
119
+   The Following modules must be loaded before this module:
120
+     * Usrloc PCSCF
121
+     * TM
122
+
123
+2.2. External Libraries or Applications
124
+
125
+   This modules requires the internal IMS library and libmnl for operating
126
+   with netlink sockets.
127
+
128
+3. Parameters
129
+
130
+   3.1. ipsec_listen_addr (string)
131
+   3.2. ipsec_client_port (int)
132
+   3.3. ipsec_server_port (int)
133
+   3.4. ipsec_spi_id_start (int)
134
+   3.5. ipsec_spi_id_range (int)
135
+
136
+3.1. ipsec_listen_addr (string)
137
+
138
+   IP address which the Proxy-CSCF will use for incoming/outgoing SIP
139
+   traffic over IPSec.
140
+
141
+   Default value is "127.0.0.1"
142
+
143
+   Example 1.1. ipsec_listen_addr parameter usage
144
+...
145
+modparam("ims_ipsec_pcscf", "ipsec_listen_addr", "127.0.0.1")
146
+...
147
+
148
+3.2. ipsec_client_port (int)
149
+
150
+   Port number which will be bound for incoming (server) IPSec traffic.
151
+
152
+   Default value is 5963.
153
+
154
+   Example 1.2. ipsec_client_port parameter usage
155
+...
156
+modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
157
+...
158
+
159
+3.3. ipsec_server_port (int)
160
+
161
+   Port number which will be bound for incoming (server) IPSec traffic.
162
+
163
+   Default value is 5063.
164
+
165
+   Example 1.3. ipsec_server_port parameter usage
166
+...
167
+modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
168
+...
169
+
170
+3.4. ipsec_spi_id_start (int)
171
+
172
+   Each IPSec tunnel has a unique system-wide identifier. This and the
173
+   following option allows to tune the SPIs used by Kamailio in order to
174
+   avoid collisions with other IPSec useres. If Kamailio is the only
175
+   process on the system which uses IPSec, don't bother with this option.
176
+
177
+   Default value is 100.
178
+
179
+   Example 1.4. ipsec_spi_id_start parameter usage
180
+...
181
+modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
182
+...
183
+
184
+3.5. ipsec_spi_id_range (int)
185
+
186
+   How many SPIs to be allocated for the process. E.g. if
187
+   ipsec_spi_id_start = 100 and ipsec_spi_id_range = 1000, SPIs between
188
+   100 and 1100 will be used.
189
+
190
+   Default value is 1000.
191
+
192
+   Example 1.5. ipsec_spi_id_range parameter usage
193
+...
194
+modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
195
+...
196
+
197
+4. Functions
198
+
199
+   4.1. ipsec_create(domain)
200
+   4.2. ipsec_forward(domain)
201
+   4.3. ipsec_destroy(domain)
202
+
203
+4.1. ipsec_create(domain)
204
+
205
+   This function creates IPSec SA and Policy based on the parameters sent
206
+   in Security-Client header in the REGISTER message. It's called when OK
207
+   is received. The function also adds Security-Server header to the
208
+   REGISTER.
209
+
210
+   Meaning of the parameters is as follows:
211
+     * domain - Logical domain within the registrar. If a database is used
212
+       then this must be name of the table which stores the contacts.
213
+
214
+   Example 1.6. ipsec_create
215
+...
216
+ipsec_create("location");
217
+...
218
+
219
+4.2. ipsec_forward(domain)
220
+
221
+   The function processes redirects outgoing message via the IPSec tunnel
222
+   initiated with ipsec_create().
223
+
224
+   Meaning of the parameters is as follows:
225
+     * domain - Logical domain within the registrar. If a database is used
226
+       then this must be name of the table which stores the contacts.
227
+
228
+   Example 1.7. ipsec_forward
229
+...
230
+ipsec_forward("location");
231
+...
232
+
233
+4.3. ipsec_destroy(domain)
234
+
235
+   The function destroys IPSec tunnel, created with ipsec_create.
236
+
237
+   Meaning of the parameters is as follows:
238
+     * domain - Logical domain within the registrar. If a database is used
239
+       then this must be name of the table which stores the contacts.
240
+
241
+   Example 1.8. ipsec_forward
242
+...
243
+ipsec_destroy("location");
244
+...