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