Debian Codegraph @

src/modules/ims_auth/README

raw
1 ims_auth Module
2
3 Dragos Vingarzan
4
5 FhG Fokus
6 <[email protected]>
7
8 Jason Penton
9
10 Smile Communications
11 <[email protected]>
12
13 Richard Good
14
15 Smile Communications
16 <[email protected]>
17
18 Edited by
19
20 Carsten Bock
21
22 ng-voice GmbH
23
24 Copyright © 2007 FhG FOKUS
25
26 Copyright © 2012 Smile Communications
27
28 Copyright © 2015 ng-voice GmbH
29 __________________________________________________________________
30
31 Table of Contents
32
33 1. Admin Guide
34
35 1. Overview
36 2. Dependencies
37
38 2.1. Kamailio Modules
39 2.2. External Libraries or Applications
40
41 3. Parameters
42
43 3.1. name (string)
44 3.2. auth_data_hash_size (integer)
45 3.3. auth_vector_timeout (integer)
46 3.4. auth_data_timeout (int)
47 3.5. av_request_at_once (integer)
48 3.6. av_request_at_sync (integer)
49 3.7. registration_default_algorithm (string)
50 3.8. registration_qop (string)
51 3.9. cxdx_forced_peer (string)
52 3.10. cxdx_dest_realm (string)
53 3.11. cxdx_dest_host (string)
54 3.12. max_nonce_reuse (integer)
55 3.13. add_authinfo_hdr (integer)
56 3.14. ignore_failed_auth (integer)
57 3.15. av_check_only_impu (integer)
58 3.16. av_mode (integer)
59
60 4. Functions
61
62 4.1. ims_www_authorize(realm, table)
63 4.2. ims_www_authenticate(realm)
64 4.3. ims_www_challenge(route_block, realm)
65 4.4. ims_www_challenge(route_block, realm, algorithm)
66 4.5. ims_proxy_challenge(route_block, realm, table)
67 4.6. ims_proxy_authenticate(realm, table)
68 4.7. ims_auth_data_set(key, op, op_c, amf)
69 4.8. ims_auth_data_reset()
70
71 5. Statistics
72
73 5.1. MAR Timeouts (mar_timeouts)
74 5.2. Average MAR Response Time (mar_avg_response_time)
75
76 List of Examples
77
78 1.1. name parameter usage
79 1.2. auth_data_hash_size parameter usage
80 1.3. auth_vector_timeout parameter usage
81 1.4. password_column parameter usage
82 1.5. av_request_at_once parameter usage
83 1.6. av_request_at_sync parameter usage
84 1.7. registration_default_algorithm parameter usage
85 1.8. registration_qop parameter usage
86 1.9. cxdx_forced_peer parameter usage
87 1.10. cxdx_dest_realm parameter usage
88 1.11. cxdx_dest_host parameter usage
89 1.12. max_nonce_reuse parameter usage
90 1.13. add_authinfo_hdr parameter usage
91 1.14. ignore_failed_auth parameter usage
92 1.15. av_check_only_impu parameter usage
93 1.16. av_mode parameter usage
94 1.17. www_authorize usage
95 1.18. ims_www_challenge usage
96 1.19. ims_www_challenge usage
97 1.20. proxy_authorize usage
98 1.21. ims_auth_data_set
99 1.22. ims_auth_data_reset
100
101 Chapter 1. Admin Guide
102
103 Table of Contents
104
105 1. Overview
106 2. Dependencies
107
108 2.1. Kamailio Modules
109 2.2. External Libraries or Applications
110
111 3. Parameters
112
113 3.1. name (string)
114 3.2. auth_data_hash_size (integer)
115 3.3. auth_vector_timeout (integer)
116 3.4. auth_data_timeout (int)
117 3.5. av_request_at_once (integer)
118 3.6. av_request_at_sync (integer)
119 3.7. registration_default_algorithm (string)
120 3.8. registration_qop (string)
121 3.9. cxdx_forced_peer (string)
122 3.10. cxdx_dest_realm (string)
123 3.11. cxdx_dest_host (string)
124 3.12. max_nonce_reuse (integer)
125 3.13. add_authinfo_hdr (integer)
126 3.14. ignore_failed_auth (integer)
127 3.15. av_check_only_impu (integer)
128 3.16. av_mode (integer)
129
130 4. Functions
131
132 4.1. ims_www_authorize(realm, table)
133 4.2. ims_www_authenticate(realm)
134 4.3. ims_www_challenge(route_block, realm)
135 4.4. ims_www_challenge(route_block, realm, algorithm)
136 4.5. ims_proxy_challenge(route_block, realm, table)
137 4.6. ims_proxy_authenticate(realm, table)
138 4.7. ims_auth_data_set(key, op, op_c, amf)
139 4.8. ims_auth_data_reset()
140
141 5. Statistics
142
143 5.1. MAR Timeouts (mar_timeouts)
144 5.2. Average MAR Response Time (mar_avg_response_time)
145
146 1. Overview
147
148 This module contains all authentication related functions for an IMS
149 environment. The module does not depend on the base Kamailio auth
150 modules as other auth modules do. Instead ims_auth is dependent on the
151 CDP (C Diameter Peer) modules for communicating with HSS as specified
152 in 3GPP specs.
153
154 2. Dependencies
155
156 2.1. Kamailio Modules
157 2.2. External Libraries or Applications
158
159 2.1. Kamailio Modules
160
161 The Following modules must be loaded before this module:
162 * TM - Transaction Manager
163 * CDP - C Diameter Peer (for av_mode=0)
164 * CDP_AVP - CDP AVP Applications (for av_mode=0)
165 * GCRYPT - GNU Crypto functions (for av_mode=1)
166
167 2.2. External Libraries or Applications
168
169 This module requires the internal IMS library.
170
171 3. Parameters
172
173 3.1. name (string)
174 3.2. auth_data_hash_size (integer)
175 3.3. auth_vector_timeout (integer)
176 3.4. auth_data_timeout (int)
177 3.5. av_request_at_once (integer)
178 3.6. av_request_at_sync (integer)
179 3.7. registration_default_algorithm (string)
180 3.8. registration_qop (string)
181 3.9. cxdx_forced_peer (string)
182 3.10. cxdx_dest_realm (string)
183 3.11. cxdx_dest_host (string)
184 3.12. max_nonce_reuse (integer)
185 3.13. add_authinfo_hdr (integer)
186 3.14. ignore_failed_auth (integer)
187 3.15. av_check_only_impu (integer)
188 3.16. av_mode (integer)
189
190 3.1. name (string)
191
192 This is the name of the SCSCF as identified in communication with the
193 HSS (Server-Name AVP of MAR).
194
195 Default value is 'sip:scscf.ims.smilecoms.com:6060'.
196
197 Example 1.1. name parameter usage
198 ...
199 modparam("ims_auth", "name", "sip:scscf3.ims.smilecoms.com:6060")
200 ...
201
202 3.2. auth_data_hash_size (integer)
203
204 This is the size of the hash table used to store auth vectors (AV).
205 Default value is fine for most people. Use the parameter if you really
206 need to change it.
207
208 Default value is “1024”.
209
210 Example 1.2. auth_data_hash_size parameter usage
211 ...
212 modparam("ims_auth", "auth_data_hash_size", 1024)
213 ...
214
215 3.3. auth_vector_timeout (integer)
216
217 This is the time, in seconds, that a SENTauth vector is valid for. If
218 there is no response ...
219
220 Default value is “60”.
221
222 Example 1.3. auth_vector_timeout parameter usage
223 ...
224 modparam("ims_auth", "auth_vector_timeout", "domain")
225 ...
226
227 3.4. auth_data_timeout (int)
228
229 Time, in seconds, a used auth vector is valid for.
230
231 Default value is “60”.
232
233 Example 1.4. password_column parameter usage
234 ...
235 modparam("ims_auth", "auth_data_timeout", 60)
236 ...
237
238 3.5. av_request_at_once (integer)
239
240 How many auth vectors to request in MAR.
241
242 Default value is 1
243
244 Example 1.5. av_request_at_once parameter usage
245 ...
246 modparam("ims_auth", "av_request_at_once", 1)
247 ...
248
249 3.6. av_request_at_sync (integer)
250
251 How many auth vectors to request at sync. Default value is 1.
252
253 Example 1.6. av_request_at_sync parameter usage
254 ...
255 modparam("ims_auth", "av_request_at_sync", 1)
256 ...
257
258 3.7. registration_default_algorithm (string)
259
260 The default authentication algorithm to use for registration if one is
261 not specified.
262
263 Options are:
264 * AKAV1-MD5
265 * AKAV2-MD5
266 * MD5
267 * HSS-Selected - HSS will decide on auth algorithm
268
269 Default value is “AKAv1-MD5”.
270
271 Example 1.7. registration_default_algorithm parameter usage
272 ...
273 modparam("ims_auth", "registration_default_algorithm", "HSS-Selected")
274 ...
275
276 3.8. registration_qop (string)
277
278 The QOP options to put in the authorisation challenges.
279
280 Default value of this parameter is “auth,auth-int”.
281
282 Example 1.8. registration_qop parameter usage
283 ...
284 modparam("ims_auth", "registration_qop", "auth-int")
285 ...
286
287 3.9. cxdx_forced_peer (string)
288
289 FQDN of Diameter Peer (HSS) to use for communication (MAR). If you use
290 this, the routing defined in your diameter xml configuration file (CDP)
291 will be ignored and as a result you will lose the benefits of load
292 balancing and failover.
293
294 Default value is “”.
295
296 Example 1.9. cxdx_forced_peer parameter usage
297 ...
298 modparam("ims_auth", "cxdx_forced_peer", "hss.ims.smilecoms.com")
299 ...
300
301 3.10. cxdx_dest_realm (string)
302
303 Destination realm to be used in Diameter messages to HSS
304
305 Default value is “ims.smilecoms.com”.
306
307 Example 1.10. cxdx_dest_realm parameter usage
308 ...
309 modparam("ims_auth", "cxdx_dest_realm", "ims.smilecoms.com")
310 ...
311
312 3.11. cxdx_dest_host (string)
313
314 Destination Host to be used in Diameter-MAR messages to HSS
315
316 Default value is “” (not set).
317
318 Example 1.11. cxdx_dest_host parameter usage
319 ...
320 modparam("ims_auth", "cxdx_dest_host", "hss.ims.ng-voice.com")
321 ...
322
323 3.12. max_nonce_reuse (integer)
324
325 Defines, how many times a nonce can be reused (provided nc is
326 incremented)
327
328 Default value is “0” (don't allow reuse).
329
330 Example 1.12. max_nonce_reuse parameter usage
331 ...
332 modparam("ims_auth", "max_nonce_reuse", 1)
333 ...
334
335 3.13. add_authinfo_hdr (integer)
336
337 Should an Authentication-Info header be added on 200 OK responses?
338
339 Default value is “1” (add Authentication-Info header).
340
341 Example 1.13. add_authinfo_hdr parameter usage
342 ...
343 modparam("ims_auth", "add_authinfo_hdr", 0)
344 ...
345
346 3.14. ignore_failed_auth (integer)
347
348 Ignore invalid passwords (only IMPI/IMPU is checked).
349
350 It should be used only for testing, e.g. load balancing with SIPP where
351 we don't want to worry about auth.
352
353 Default value is “0” (don't ignore the failed authentication).
354
355 Example 1.14. ignore_failed_auth parameter usage
356 ...
357 modparam("ims_auth", "ignore_failed_auth", 1)
358 ...
359
360 3.15. av_check_only_impu (integer)
361
362 When storing the authentication vectors for an account, use either
363 IMPI/IMPU (=0, default) or IMPU (=1).
364
365 In case the IMPI is different from the IMPU, this option needs to be
366 enabled to allow registration from classic "SIP-clients", such as Snom
367 phones and others, as they do not send an authentication username in
368 the first REGISTER.
369
370 Default value is “0” (store authentication vectors based on IMPI/IMPU).
371
372 Example 1.15. av_check_only_impu parameter usage
373 ...
374 modparam("ims_auth", "av_check_only_impu", 1)
375 ...
376
377 3.16. av_mode (integer)
378
379 Control how authentication vector is generated: 0 - get it from HSS via
380 DIAMETER; 1 - generate it locally. Default is 0.
381
382 Example 1.16. av_mode parameter usage
383 ...
384 modparam("ims_auth", "av_mode", 1)
385 ...
386
387 4. Functions
388
389 4.1. ims_www_authorize(realm, table)
390 4.2. ims_www_authenticate(realm)
391 4.3. ims_www_challenge(route_block, realm)
392 4.4. ims_www_challenge(route_block, realm, algorithm)
393 4.5. ims_proxy_challenge(route_block, realm, table)
394 4.6. ims_proxy_authenticate(realm, table)
395 4.7. ims_auth_data_set(key, op, op_c, amf)
396 4.8. ims_auth_data_reset()
397
398 4.1. ims_www_authorize(realm, table)
399
400 The function verifies credentials according to RFC2617. If the
401 credentials are verified successfully then the function will succeed
402 and mark the credentials as authorized (marked credentials can be later
403 used by some other functions). If the function was unable to verify the
404 credentials for some reason then it will fail and the script should
405 call www_challenge which will challenge the user again.
406
407 Negative codes may be interpreted as follows:
408 * -1 (generic error) - some generic error occurred and no reply was
409 sent out;
410 * -2 (invalid password) - valid user, but wrong password;
411 * -3 (invalid user) - authentication user does not exist.
412
413 Meaning of the parameters is as follows:
414 * realm - Realm is a opaque string that the user agent should present
415 to the user so he can decide what username and password to use.
416 Usually this is domain of the host the server is running on.
417 It must not be empty string “”. In case of REGISTER requests To
418 header field domain (e.g., variable $td) can be used (because this
419 header field represents the user being registered), for all other
420 messages From header field domain can be used (e.g., variable $fd).
421 The string may contain pseudo variables.
422 * table - Table to be used to lookup usernames and passwords (usually
423 subscribers table).
424
425 This function can be used from REQUEST_ROUTE.
426
427 Example 1.17. www_authorize usage
428 ...
429 if (!www_authorize("kamailio.org", "subscriber")) {
430 www_challenge(""REG_MAR_REPLY"", "kamailio.org", "1");
431 };
432 ...
433
434 4.2. ims_www_authenticate(realm)
435
436 It is the same function as www_authenticate(realm, table). This name is
437 kept for backward compatibility, since it was named this way first time
438 by it actually does user authentication.
439
440 4.3. ims_www_challenge(route_block, realm)
441
442 Name alias: proxy_authorize(realm, table)
443
444 The function verifies credentials according to RFC2617. If the
445 credentials are verified successfully then the function will succeed
446 and mark the credentials as authorized (marked credentials can be later
447 used by some other functions). If the function was unable to verify the
448 credentials for some reason then it will fail and the script should
449 call proxy_challenge which will challenge the user again.
450
451 Negative return codes have the same meaning as for www_authenticate().
452
453 Meaning of the parameters is as follows:
454 * Route block to resume after async MAR Diameter reply.
455 * realm - Realm is a opaque string that the user agent should present
456 to the user so he can decide what username and password to use.
457 Usually this is domain of the host the server is running on.
458 It must not be empty string “”. Apart of a static string, typical
459 value is From header field domain (e.g., variable $fd).
460 If an empty string “” is used then the server will generate it from
461 the request. From header field domain will be used as realm.
462 The string may contain pseudo variables.
463
464 This function can be used from REQUEST_ROUTE.
465
466 Example 1.18. ims_www_challenge usage
467 ...
468 if (!proxy_authorize("$fd", "subscriber)) {
469 proxy_challenge(""REG_MAR_REPLY","$fd"); # Realm will be autogenerated
470 };
471 ...
472 ...
473 route[REG_MAR_REPLY]
474 {
475 #this is async so to know status we have to check the reply avp
476 xlog("L_DBG","maa_return code is $avp(s:maa_return_code)\n");
477
478 switch ($avp(s:maa_return_code)){
479 case 1: #success
480 xlog("L_DBG", "MAR success - 401/407 response sent from mod
481 ule\n");
482 break;
483 case -1: #failure
484 xlog("L_ERR", "MAR failure - error response sent from modul
485 e\n");
486 break;
487 case -2: #error
488 xlog("L_ERR", "MAR error - sending error response now\n");
489 t_reply("500", "MAR failed");
490 break;
491 default:
492 xlog("L_ERR", "Unknown return code from MAR, value is [$avp
493 (s:uaa_return_code)]\n");
494 t_reply("500", "Unknown response code from MAR");
495 break;
496 }
497 exit;
498 }
499
500 4.4. ims_www_challenge(route_block, realm, algorithm)
501
502 Same as 4.3 except here there is the additional option to specify the
503 authorisation algorithm
504 * algorithm - The algorithm to be used when challenging the client.
505 Can be AKAv1-MD5, AKAv2-MD5, MD5, or HSS-Selected. If left as an
506 empty string, the default algorithm will be chosen according to the
507 parameter registration_default_algorithm (see section 3.7)
508
509 This function can be used from REQUEST_ROUTE.
510
511 Example 1.19. ims_www_challenge usage
512 ...
513 if (!ims_www_authenticate(NETWORKNAME)) {
514 #user has not been authenticated. Lets send a challenge via 401
515 Unauthorized
516 if ($? == -2) {
517 t_reply("403", "Authentication Failed");
518 exit;
519 } else if ($? == -3) {
520 t_reply("400", "Bad Request");
521 exit;
522 } else if ($? == -9) {
523 xlog("L_DBG", "Authentication re-sync requested\n");
524 ims_www_resync_auth("REG_RESYNC_REPLY", "$td");
525 exit;
526 } else {
527 xlog("L_DBG","About to challenge! auth_ims\n");
528 ims_www_challenge("REG_MAR_REPLY", "$td", "MD5");
529 exit;
530 }
531 }
532
533 4.5. ims_proxy_challenge(route_block, realm, table)
534
535 Name alias: proxy_authorize(realm, table)
536
537 The function verifies credentials according to RFC2617. If the
538 credentials are verified successfully then the function will succeed
539 and mark the credentials as authorized (marked credentials can be later
540 used by some other functions). If the function was unable to verify the
541 credentials for some reason then it will fail and the script should
542 call proxy_challenge which will challenge the user again.
543
544 Negative return codes have the same meaning as for www_authenticate().
545
546 Meaning of the parameters is as follows:
547 * Route block to resume after async MAR Diameter reply.
548 * realm - Realm is a opaque string that the user agent should present
549 to the user so he can decide what username and password to use.
550 Usually this is domain of the host the server is running on.
551 It must not be empty string “”. Apart of a static string, typical
552 value is From header field domain (e.g., variable $fd).
553 If an empty string “” is used then the server will generate it from
554 the request. From header field domain will be used as realm.
555 The string may contain pseudo variables.
556 * table - Table to be used to lookup usernames and passwords (usually
557 subscribers table).
558
559 This function can be used from REQUEST_ROUTE.
560
561 Example 1.20. proxy_authorize usage
562 ...
563 if (!proxy_authorize("$fd", "subscriber)) {
564 proxy_challenge("REG_MAR_REPLY","$fd", "1"); # Realm will be autogenera
565 ted
566 };
567 ...
568 route[REG_MAR_REPLY]
569 {
570 #this is async so to know status we have to check the reply avp
571 xlog("L_DBG","maa_return code is $avp(s:maa_return_code)\n");
572
573 switch ($avp(s:maa_return_code)){
574 case 1: #success
575 xlog("L_DBG", "MAR success - 401/407 response sent from mod
576 ule\n");
577 break;
578 case -1: #failure
579 xlog("L_ERR", "MAR failure - error response sent from modul
580 e\n");
581 break;
582 case -2: #error
583 xlog("L_ERR", "MAR error - sending error response now\n");
584 t_reply("500", "MAR failed");
585 break;
586 default:
587 xlog("L_ERR", "Unknown return code from MAR, value is [$avp
588 (s:uaa_return_code)]\n");
589 t_reply("500", "Unknown response code from MAR");
590 break;
591 }
592 exit;
593 }
594 ...
595
596 4.6. ims_proxy_authenticate(realm, table)
597
598 It is same function as proxy_authenticate(realm, table). This name is
599 kept for backward compatibility, since it was named this way first time
600 but it actually does user authentication.
601
602 4.7. ims_auth_data_set(key, op, op_c, amf)
603
604 Set the key, op, op_c and amf to be used for AKAv1-MD5 authentication
605 when av_mode parameter is set to 1 (authentication vector generated
606 locally). It has to be used before the function for doing
607 authentication.
608
609 The parameters can be variables, their values can be retrieved from a
610 backend (e.g., from database using sqlops module or from a REST API
611 server using http_client module).
612 * key - the SIM key
613 op - the operator key (can be empty if op_c is set)
614 op_c - the derived operator key (can be empty if op is set)
615 amf - the amf code
616
617 This function can be used from REQUEST_ROUTE.
618
619 Example 1.21. ims_auth_data_set
620 ...
621 ims_auth_data_set("...", "...", "...", "...");
622 ...
623
624 4.8. ims_auth_data_reset()
625
626 Reset the authentication attributes when av_mode parameter is set to 1.
627
628 This function can be used from REQUEST_ROUTE.
629
630 Example 1.22. ims_auth_data_reset
631 ...
632 ims_auth_data_reset();
633 ...
634
635 5. Statistics
636
637 5.1. MAR Timeouts (mar_timeouts)
638 5.2. Average MAR Response Time (mar_avg_response_time)
639
640 5.1. MAR Timeouts (mar_timeouts)
641
642 The number of timeouts on sending a MAR. i.e. no response to MAR.
643
644 5.2. Average MAR Response Time (mar_avg_response_time)
645
646 The average response time in milliseconds for MAR-MAA transaction.