1permissions Module 2 3Miklos Tirpak 4 5Edited by 6 7Miklos Tirpak 8 9Bogdan-Andrei Iancu 10 11Juha Heinanen 12 13Emmanuel Schmidbauer 14 15 Copyright © 2003 Miklos Tirpak 16 17 Copyright © 2006-2008 Juha Heinanen 18 __________________________________________________________________ 19 20 Table of Contents 21 22 1. Admin Guide 23 24 1. Overview 25 26 1.1. Call Routing 27 1.2. Registration Permissions 28 1.3. URI Permissions 29 1.4. Address Permissions 30 1.5. Trusted Requests 31 32 2. Dependencies 33 34 2.1. Kamailio Modules 35 2.2. External Libraries or Applications 36 37 3. Parameters 38 39 3.1. default_allow_file (string) 40 3.2. default_deny_file (string) 41 3.3. check_all_branches (integer) 42 3.4. allow_suffix (string) 43 3.5. deny_suffix (string) 44 3.6. address_file (string) 45 3.7. db_url (string) 46 3.8. address_table (string) 47 3.9. grp_col (string) 48 3.10. ip_addr_col (string) 49 3.11. mask_col (string) 50 3.12. port_col (string) 51 3.13. db_mode (integer) 52 3.14. trusted_table (string) 53 3.15. source_col (string) 54 3.16. proto_col (string) 55 3.17. from_col (string) 56 3.18. ruri_col (string) 57 3.19. tag_col (string) 58 3.20. priority_col (string) 59 3.21. peer_tag_avp (AVP string) 60 3.22. peer_tag_mode (integer) 61 3.23. max_subnets (int) 62 3.24. load_backends (int) 63 64 4. Functions 65 66 4.1. allow_routing() 67 4.2. allow_routing(basename) 68 4.3. allow_routing(allow_file,deny_file) 69 4.4. allow_register(basename) 70 4.5. allow_register(allow_file, deny_file) 71 4.6. allow_uri(basename, pvar) 72 4.7. allow_address(group_id, ip_addr_pvar, port_pvar) 73 4.8. allow_source_address([group_id]) 74 4.9. allow_source_address_group() 75 4.10. allow_address_group(addr, port) 76 4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar]) 77 78 5. RPC Commands 79 80 5.1. permissions.addressReload 81 5.2. permissions.addressDump 82 5.3. permissions.subnetDump 83 5.4. permissions.domainDump 84 5.5. permissions.testUri 85 5.6. permissions.allowUri 86 5.7. permissions.trustedReload 87 5.8. permissions.trustedDump 88 89 6. Address File Format 90 91 List of Examples 92 93 1.1. Set default_allow_file parameter 94 1.2. Set default_deny_file parameter 95 1.3. Set check_all_branches parameter 96 1.4. Set allow_suffix parameter 97 1.5. Set deny_suffix parameter 98 1.6. Set address_file parameter 99 1.7. Set db_url parameter 100 1.8. Set address_table parameter 101 1.9. Set grp_col parameter 102 1.10. Set ip_addr_col parameter 103 1.11. Set mask_col parameter 104 1.12. Set port_col parameter 105 1.13. Set db_mode parameter 106 1.14. Set trusted_table parameter 107 1.15. Set source_col parameter 108 1.16. Set proto_col parameter 109 1.17. Set from_col parameter 110 1.18. Set ruri_col parameter 111 1.19. Set tag_col parameter 112 1.20. Set priority_col parameter 113 1.21. Set peer_tag_avp parameter 114 1.22. Set peer_tag_mode parameter 115 1.23. Set max_subnets parameter 116 1.24. Set load_backends parameter 117 1.25. allow_routing usage 118 1.26. allow_routing(basename) usage 119 1.27. allow_routing(allow_file, deny_file) usage 120 1.28. allow_register(basename) usage 121 1.29. allow_register(allow_file, deny_file) usage 122 1.30. allow_uri(basename, pvar) usage 123 1.31. allow_address() usage 124 1.32. allow_source_address(group_id) usage 125 1.33. allow_source_address_group() usage 126 1.34. allow_source_address_group() usage 127 1.35. allow_trusted() usage 128 1.36. Address File Sample 129 130Chapter 1. Admin Guide 131 132 Table of Contents 133 134 1. Overview 135 136 1.1. Call Routing 137 1.2. Registration Permissions 138 1.3. URI Permissions 139 1.4. Address Permissions 140 1.5. Trusted Requests 141 142 2. Dependencies 143 144 2.1. Kamailio Modules 145 2.2. External Libraries or Applications 146 147 3. Parameters 148 149 3.1. default_allow_file (string) 150 3.2. default_deny_file (string) 151 3.3. check_all_branches (integer) 152 3.4. allow_suffix (string) 153 3.5. deny_suffix (string) 154 3.6. address_file (string) 155 3.7. db_url (string) 156 3.8. address_table (string) 157 3.9. grp_col (string) 158 3.10. ip_addr_col (string) 159 3.11. mask_col (string) 160 3.12. port_col (string) 161 3.13. db_mode (integer) 162 3.14. trusted_table (string) 163 3.15. source_col (string) 164 3.16. proto_col (string) 165 3.17. from_col (string) 166 3.18. ruri_col (string) 167 3.19. tag_col (string) 168 3.20. priority_col (string) 169 3.21. peer_tag_avp (AVP string) 170 3.22. peer_tag_mode (integer) 171 3.23. max_subnets (int) 172 3.24. load_backends (int) 173 174 4. Functions 175 176 4.1. allow_routing() 177 4.2. allow_routing(basename) 178 4.3. allow_routing(allow_file,deny_file) 179 4.4. allow_register(basename) 180 4.5. allow_register(allow_file, deny_file) 181 4.6. allow_uri(basename, pvar) 182 4.7. allow_address(group_id, ip_addr_pvar, port_pvar) 183 4.8. allow_source_address([group_id]) 184 4.9. allow_source_address_group() 185 4.10. allow_address_group(addr, port) 186 4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar]) 187 188 5. RPC Commands 189 190 5.1. permissions.addressReload 191 5.2. permissions.addressDump 192 5.3. permissions.subnetDump 193 5.4. permissions.domainDump 194 5.5. permissions.testUri 195 5.6. permissions.allowUri 196 5.7. permissions.trustedReload 197 5.8. permissions.trustedDump 198 199 6. Address File Format 200 2011. Overview 202 203 1.1. Call Routing 204 1.2. Registration Permissions 205 1.3. URI Permissions 206 1.4. Address Permissions 207 1.5. Trusted Requests 208 209 The Permissions module provides functions for handling IP based access 210 control lists (ACL) in a number of ways. 211 * Call Routing 212 * Registration permissions 213 * URI permissions 214 * Address permissions 215 * Trusted Requests 216 217 The Address permissions and Trusted request handling supports using a 218 database to load ACLs into RAM for fast processing. 219 2201.1. Call Routing 221 222 The module can be used to determine if a call has appropriate 223 permission to be established. Permission rules are stored in plaintext 224 configuration files similar to hosts.allow and hosts.deny files used by 225 tcpd. 226 227 When allow_routing function is called it tries to find a rule that 228 matches selected fields of the message. 229 230 Kamailio is a forking proxy and therefore a single message can be sent 231 to different destinations simultaneously. When checking permissions all 232 the destinations must be checked and if one of them fails, the 233 forwarding will fail. 234 235 The matching algorithm is as follows, first match wins: 236 * Create a set of pairs of form (From, R-URI of branch 1), (From, 237 R-URI of branch 2), etc. 238 * Routing will be allowed when all pairs match an entry in the allow 239 file. 240 * Otherwise routing will be denied when one of pairs matches an entry 241 in the deny file. 242 * Otherwise, routing will be allowed. 243 244 A non-existing permission control file is treated as if it were an 245 empty file. Thus, permission control can be turned off by providing no 246 permission control files. 247 248 From header field and Request-URIs are always compared with regular 249 expressions! For the syntax see the sample file: 250 config/permissions.allow. 251 2521.2. Registration Permissions 253 254 In addition to call routing it is also possible to check REGISTER 255 messages and decide--based on the configuration files--whether the 256 message should be allowed and the registration accepted or not. 257 258 Main purpose of the function is to prevent registration of "prohibited" 259 IP addresses. One example, when a malicious user registers a contact 260 containing IP address of a PSTN gateway, he might be able to bypass 261 authorization checks performed by the SIP proxy. That is undesirable 262 and therefore attempts to register IP address of a PSTN gateway should 263 be rejected. Files config/register.allow and config/register.deny 264 contain an example configuration. 265 266 The function for registration checking is called allow_register and the 267 algorithm is very similar to the algorithm described in Section 1.1, 268 “Call Routing”. The only difference is in the way how pairs are 269 created. 270 271 Instead of the From header field the function uses the To header field 272 because th To header field in REGISTER messages contains the URI of the 273 person being registered. Instead of the Request-URI of branches the 274 function uses the Contact header field. 275 276 Thus, the pairs used in matching will look like this: (To, Contact 1), 277 (To, Contact 2), (To, Contact 3), and so on.. 278 279 The algorithm of matching is the same as described in Section 1.1, 280 “Call Routing”. 281 2821.3. URI Permissions 283 284 The module can be used to determine if a request to a destination is 285 allowed, based on an URI stored in a pvar. Permission rules are stored 286 in plaintext configuration files similar to hosts.allow and hosts.deny 287 used by tcpd. 288 289 When the allow_uri function is called, it tries to find a rule that 290 matches selected fields of the message. The matching algorithm is as 291 follows, where the first match wins: 292 * Create a pair <From URI, URI stored in pvar>. 293 * Request will be allowed when the pair matches an entry in the allow 294 file. 295 * Request will be denied when the pair matches an entry in the deny 296 file. 297 * Otherwise, request will be allowed. 298 299 A non-existing permission control file is treated as if it were an 300 empty file. Thus, permission control can be turned off by providing no 301 permission control files. 302 303 The From URI and the URI stored in pvar are always compared with 304 regular expressions! For the syntax see the sample file: 305 config/permissions.allow. 306 3071.4. Address Permissions 308 309 The module can be used to determine if an address (IP address and port 310 or DNS domain name) matches any of the addresses stored in a cached 311 Kamailio database table or file. IP addresses in the database table or 312 file can be subnet addresses. Port 0 matches any port. The address and 313 port to be matched can be either taken from the source of IP packet of 314 the request (allow_source_address) or given as a variable argument 315 (allow_address). 316 317 Addresses stored in the database table or file can be grouped together 318 into one or more groups specified by a group identifier (positive 319 integer value, i.e., equal or greater than 1). The group identifier is 320 given as an argument to the allow_address() and allow_source_address() 321 functions. One group can contain all of the three types of addresses: 322 exact IP address, subnet IP address or DNS domain name. 323 324 When the argument is an IP address, it is tried to be matched with the 325 records from that group that are of type exact IP or subnet. If the 326 argument is not an IP it is tried to be matched with the records that 327 are DNS domain names. No DNS lookup is performed, only strict matching. 328 329 As a side effect of matching the address, non-NULL tag (see tag_col 330 module parameter) is added as value to peer_tag AVP if peer_tag_avp 331 module parameter has been defined. 332 3331.5. Trusted Requests 334 335 The module can be used to determine if an incoming request can be 336 trusted without authentication. 337 338 When the allow_trusted function is called, it tries to find a rule that 339 matches the request. Rules contain the following fields: <source 340 address, transport protocol, regular expression>. 341 342 A requests is accepted if there exists a rule, where 343 * source address is equal to the source address of the request or the 344 source address given in pvar, 345 * transport protocol is either "ANY" or equal to the transport 346 protocol of request or the transport protocol given in pvar, and 347 * regular expression is either empty (NULL in database) or matches 348 the request's From (or optionally provided) URI. 349 350 Otherwise the request is rejected. 351 352 As a side effect of accepting the request, the peer's non-NULL tag (see 353 tag_col module parameter) is added as value to peer_tag AVP if the 354 peer_tag_avp module parameter has been defined. 355 356 Rules are stored in a database table specified by the module 357 parameters. There is a module parameter called db_mode that determines 358 if the rules are cached into memory for faster matching or if the 359 database is consulted for each invocation of the allow_trusted() 360 function call. 361 3622. Dependencies 363 364 2.1. Kamailio Modules 365 2.2. External Libraries or Applications 366 3672.1. Kamailio Modules 368 369 The following modules must be loaded before this module: 370 * No dependencies on other Kamailio modules. 371 3722.2. External Libraries or Applications 373 374 The following libraries or applications must be installed before 375 running Kamailio with this module loaded: 376 * None. 377 3783. Parameters 379 380 3.1. default_allow_file (string) 381 3.2. default_deny_file (string) 382 3.3. check_all_branches (integer) 383 3.4. allow_suffix (string) 384 3.5. deny_suffix (string) 385 3.6. address_file (string) 386 3.7. db_url (string) 387 3.8. address_table (string) 388 3.9. grp_col (string) 389 3.10. ip_addr_col (string) 390 3.11. mask_col (string) 391 3.12. port_col (string) 392 3.13. db_mode (integer) 393 3.14. trusted_table (string) 394 3.15. source_col (string) 395 3.16. proto_col (string) 396 3.17. from_col (string) 397 3.18. ruri_col (string) 398 3.19. tag_col (string) 399 3.20. priority_col (string) 400 3.21. peer_tag_avp (AVP string) 401 3.22. peer_tag_mode (integer) 402 3.23. max_subnets (int) 403 3.24. load_backends (int) 404 4053.1. default_allow_file (string) 406 407 Default allow file used by the functions with no parameters. If you 408 don't specify a full pathname then the directory in which is the main 409 config file is located will be used. 410 411 Default value is “permissions.allow”. 412 413 Example 1.1. Set default_allow_file parameter 414... 415modparam("permissions", "default_allow_file", "/etc/permissions.allow") 416... 417 4183.2. default_deny_file (string) 419 420 Default file containing deny rules. The file is used by functions with 421 no parameters. If you don't specify a full pathname then the directory 422 in which the main config file is located will be used. 423 424 Default value is “permissions.deny”. 425 426 Example 1.2. Set default_deny_file parameter 427... 428modparam("permissions", "default_deny_file", "/etc/permissions.deny") 429... 430 4313.3. check_all_branches (integer) 432 433 If set then allow_routing functions will check Request-URI of all 434 branches (default). If disabled then only Request-URI of the first 435 branch will be checked. 436 437Warning 438 439 Do not disable this parameter unless you really know what you are 440 doing. 441 442 Default value is 1. 443 444 Example 1.3. Set check_all_branches parameter 445... 446modparam("permissions", "check_all_branches", 0) 447... 448 4493.4. allow_suffix (string) 450 451 Suffix to be appended to basename to create filename of the allow file 452 when version with one parameter of either allow_routing or 453 allow_register is used. 454 455Note 456 457 Including leading dot. 458 459 Default value is “.allow”. 460 461 Example 1.4. Set allow_suffix parameter 462... 463modparam("permissions", "allow_suffix", ".allow") 464... 465 4663.5. deny_suffix (string) 467 468 Suffix to be appended to basename to create filename of the deny file 469 when version with one parameter of either allow_routing or 470 allow_register is used. 471 472Note 473 474 Including leading dot. 475 476 Default value is “.deny”. 477 478 Example 1.5. Set deny_suffix parameter 479... 480modparam("permissions", "deny_suffix", ".deny") 481... 482 4833.6. address_file (string) 484 485 This is the name of full path to the file that store rules used by 486 allow_address function (and its variants). If it is only the file name, 487 it is expected to be in the same folder as Kamailio.cfg file. 488 489 If set, this parameter has priority over the database backend, so the 490 address matching records are loaded from the file, not from database. 491 492 To see the format of the file see the section "Address File Format". 493 494 Default value is “NULL”. 495 496 Example 1.6. Set address_file parameter 497... 498modparam("permissions", "address_file", "address.list") 499... 500 5013.7. db_url (string) 502 503 This is URL of the database to be used to store rules used by 504 allow_trusted or allow_address functions. 505 506 Default value is “NULL”. 507 508 Example 1.7. Set db_url parameter 509... 510modparam("permissions", "db_url", "dbdriver://username:password@dbhost/dbname") 511... 512 5133.8. address_table (string) 514 515 The name of the database table containing IP subnets and DNS domain 516 names used by allow_address and allow_source_address functions. 517 518 Default value is “address”. 519 520 Example 1.8. Set address_table parameter 521... 522modparam("permissions", "address_table", "addr") 523... 524 5253.9. grp_col (string) 526 527 Name of address table column containing the group identifier of the 528 address. 529 530 Default value is “grp”. 531 532 Example 1.9. Set grp_col parameter 533... 534modparam("permissions", "grp_col", "group_id") 535... 536 5373.10. ip_addr_col (string) 538 539 Name of address table column containing the IP address part of the 540 address. 541 542 Default value is “ip_addr”. 543 544 Example 1.10. Set ip_addr_col parameter 545... 546modparam("permissions", "ip_addr_col", "ip_address") 547... 548 5493.11. mask_col (string) 550 551 Name of address table column containing the network mask of the 552 address. Possible values are 0-32 for IPv4 and 0-128 for IPv6 553 addresses. If the value is 0, the network mask is set to 32 for IPv4 554 addresses and to 128 for IPv6 addresses. 555 556 Default value is “mask”. 557 558 Example 1.11. Set mask_col parameter 559... 560modparam("permissions", "mask_col", "subnet_length") 561... 562 5633.12. port_col (string) 564 565 Name of address table column containing the port part of the address. 566 567 Default value is “port”. 568 569 Example 1.12. Set port_col parameter 570... 571modparam("permissions", "port_col", "port") 572... 573 5743.13. db_mode (integer) 575 576 Database mode. 0 means non-caching, 1 means caching. Valid only for the 577 allow_trusted function. 578 579 Default value is 0 (non-caching). 580 581 Example 1.13. Set db_mode parameter 582... 583modparam("permissions", "db_mode", 1) 584... 585 5863.14. trusted_table (string) 587 588 Name of database table containing the matching rules used by the 589 allow_trusted function. 590 591 Default value is “trusted”. 592 593 Example 1.14. Set trusted_table parameter 594... 595modparam("permissions", "trusted_table", "pbx") 596... 597 5983.15. source_col (string) 599 600 Name of column in the “trusted” table containing the source IP address 601 that is matched against source IP address of received request. 602 603 Default value is “src_ip”. 604 605 Example 1.15. Set source_col parameter 606... 607modparam("permissions", "source_col", "source_ip_address") 608... 609 6103.16. proto_col (string) 611 612 Name of column in the “trusted” table containing the transport protocol 613 that is matched against transport protocol of the received request. 614 Possible values that can be stored in proto_col are “any”, “udp”, 615 “tcp”, “tls”, “sctp”, “ws”, “wss”, and “none”. Value “any” matches 616 always and value “none” never. 617 618 Default value is “proto”. 619 620 Example 1.16. Set proto_col parameter 621... 622modparam("permissions", "proto_col", "transport") 623... 624 6253.17. from_col (string) 626 627 Name of the column trusted table containing a regular expression that 628 is matched against the From URI. 629 630 Default value is “from_pattern”. 631 632 Example 1.17. Set from_col parameter 633... 634modparam("permissions", "from_col", "regexp") 635... 636 6373.18. ruri_col (string) 638 639 Name of the column trusted table containing a regular expression that 640 is matched against the Request URI. 641 642 Default value is “ruri_pattern”. 643 644 Example 1.18. Set ruri_col parameter 645... 646modparam("permissions", "ruri_col", "regexp") 647... 648 6493.19. tag_col (string) 650 651 Name of the column in the “address” or “trusted” table containing a 652 string that is added as value to peer_tag AVP if peer_tag AVP has been 653 defined and if the address or peer matches. 654 655 Default value is “tag”. 656 657 Example 1.19. Set tag_col parameter 658... 659modparam("permissions", "tag_col", "peer_tag") 660... 661 6623.20. priority_col (string) 663 664 The column name used to store the priority of the corresponding rule 665 from the database row. Priority values should be integer. When db_mode 666 is set to 1 (caching), priorities are ordered from highest to lowest. 667 In non-caching mode, priority order (ASC vs DESC) is determined by 668 database. 669 670 Default value is “priority”. 671 672 Example 1.20. Set priority_col parameter 673... 674modparam("permissions", "priority_col", "column_name") 675... 676 6773.21. peer_tag_avp (AVP string) 678 679 If defined, the AVP will be set as a side effect of allow_trusted call 680 to not NULL tag column value of the matching peer. 681 682 Default value is “undefined”. 683 684 Example 1.21. Set peer_tag_avp parameter 685... 686modparam("permissions", "peer_tag_avp", "$avp(i:707)") 687... 688 6893.22. peer_tag_mode (integer) 690 691 Tag mode for allow_trusted. “0” sets only the tag of the first match. 692 “1” adds the tags of all matches to the avp. In addition the return 693 value of allow_trusted is the number of matches. This parameter is not 694 used for address table matching functions. 695 696 Default value is “0”. 697 698 Example 1.22. Set peer_tag_mode parameter 699... 700modparam("permissions", "peer_tag_mode", 1) 701... 702 7033.23. max_subnets (int) 704 705 The maximum number of subnet addresses to be loaded from address table. 706 707 Default value is “512”. 708 709 Example 1.23. Set max_subnets parameter 710... 711modparam("permissions", "max_subnets", 1024) 712... 713 7143.24. load_backends (int) 715 716 Control what backends should be loaded: 1 - address table; 2 - trusted 717 table; 4 - allow file; 8 - deny file. 718 719 It can be a combination (sum) of the options to load many backends 720 (e.g., 3 - loads address and trusted tables). 721 722 Default value is “0xffff” (load all backends). 723 724 Example 1.24. Set load_backends parameter 725... 726modparam("permissions", "load_backends", 1) 727... 728 7294. Functions 730 731 4.1. allow_routing() 732 4.2. allow_routing(basename) 733 4.3. allow_routing(allow_file,deny_file) 734 4.4. allow_register(basename) 735 4.5. allow_register(allow_file, deny_file) 736 4.6. allow_uri(basename, pvar) 737 4.7. allow_address(group_id, ip_addr_pvar, port_pvar) 738 4.8. allow_source_address([group_id]) 739 4.9. allow_source_address_group() 740 4.10. allow_address_group(addr, port) 741 4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar]) 742 7434.1. allow_routing() 744 745 Returns true if all pairs constructed as described in Section 1.1, 746 “Call Routing” have appropriate permissions according to the 747 configuration files. This function uses default configuration files 748 specified in default_allow_file and default_deny_file. 749 750 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 751 752 Example 1.25. allow_routing usage 753... 754if (allow_routing()) { 755 t_relay(); 756}; 757... 758 7594.2. allow_routing(basename) 760 761 Returns true if all pairs constructed as described in Section 1.1, 762 “Call Routing” have appropriate permissions according to the 763 configuration files given as parameters. 764 765 Meaning of the parameters is as follows: 766 * basename - Basename from which allow and deny filenames will be 767 created by appending contents of allow_suffix and deny_suffix 768 parameters. 769 If the parameter doesn't contain full pathname then the function 770 expects the file to be located in the same directory as the main 771 configuration file of the server. 772 773 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 774 775 Example 1.26. allow_routing(basename) usage 776... 777if (allow_routing("basename")) { 778 t_relay(); 779}; 780... 781 7824.3. allow_routing(allow_file,deny_file) 783 784 Returns true if all pairs constructed as described in Section 1.1, 785 “Call Routing” have appropriate permissions according to the 786 configuration files given as parameters. 787 788 Meaning of the parameters is as follows: 789 * allow_file - File containing allow rules. 790 If the parameter doesn't contain full pathname then the function 791 expects the file to be located in the same directory as the main 792 configuration file of the server. 793 * deny_file - File containing deny rules. 794 If the parameter doesn't contain full pathname then the function 795 expects the file to be located in the same directory as the main 796 configuration file of the server. 797 798 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 799 800 Example 1.27. allow_routing(allow_file, deny_file) usage 801... 802if (allow_routing("rules.allow", "rules.deny")) { 803 t_relay(); 804}; 805... 806 8074.4. allow_register(basename) 808 809 The function returns true if all pairs constructed as described in 810 Section 1.2, “Registration Permissions” have appropriate permissions 811 according to the configuration files given as parameters. 812 813 Meaning of the parameters is as follows: 814 * basename - Basename from which allow and deny filenames will be 815 created by appending contents of allow_suffix and deny_suffix 816 parameters. 817 If the parameter doesn't contain full pathname then the function 818 expects the file to be located in the same directory as the main 819 configuration file of the server. 820 821 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 822 823 Example 1.28. allow_register(basename) usage 824... 825if (method=="REGISTER") { 826 if (allow_register("register")) { 827 save("location"); 828 exit; 829 } else { 830 sl_send_reply("403", "Forbidden"); 831 }; 832}; 833... 834 8354.5. allow_register(allow_file, deny_file) 836 837 The function returns true if all pairs constructed as described in 838 Section 1.2, “Registration Permissions” have appropriate permissions 839 according to the configuration files given as parameters. 840 841 Meaning of the parameters is as follows: 842 * allow_file - File containing allow rules. 843 If the parameter doesn't contain full pathname then the function 844 expects the file to be located in the same directory as the main 845 configuration file of the server. 846 * deny_file - File containing deny rules. 847 If the parameter doesn't contain full pathname then the function 848 expects the file to be located in the same directory as the main 849 configuration file of the server. 850 851 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 852 853 Example 1.29. allow_register(allow_file, deny_file) usage 854... 855if (method=="REGISTER") { 856 if (allow_register("register.allow", "register.deny")) { 857 save("location"); 858 exit; 859 } else { 860 sl_send_reply("403", "Forbidden"); 861 }; 862}; 863... 864 8654.6. allow_uri(basename, pvar) 866 867 Returns true if the pair constructed as described in Section 1.3, “URI 868 Permissions” have appropriate permissions according to the 869 configuration files specified by the parameter. 870 871 Meaning of the parameter is as follows: 872 * basename - Basename from which allow and deny filenames will be 873 created by appending contents of allow_suffix and deny_suffix 874 parameters. 875 If the parameter doesn't contain full pathname then the function 876 expects the file to be located in the same directory as the main 877 configuration file of the server. 878 * pvar - Any pseudo-variable defined in Kamailio. 879 880 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 881 882 Example 1.30. allow_uri(basename, pvar) usage 883... 884if (allow_uri("basename", "$rt")) { // Check Refer-To URI 885 t_relay(); 886}; 887if (allow_uri("basename", "$avp(i:705)") { // Check URI stored in $avp(i:705) 888 t_relay(); 889}; 890... 891 8924.7. allow_address(group_id, ip_addr_pvar, port_pvar) 893 894 Returns true if the address and port given as values of pvar arguments 895 belonging to a group given as group_id argument matches an IP subnet or 896 a DNS domain name found in cached address table. 897 898 When matching is done if the argument is an IP address, it is matched 899 with the records from that group that are of type exact IP or subnet. 900 If the argument is not an IP it is tried to be matched with the records 901 that are DNS domain names. No DNS lookup is performed, only strict 902 matching. Cached address table entry containing port value “0” matches 903 any port. The “group_id” argument can be an integer string or a pseudo 904 variable. 905 906 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 907 908 Example 1.31. allow_address() usage 909... 910 911// Check if source address/port is in group 1 912if (!allow_address("1", "$si", "$sp")) { 913 sl_send_reply("403", "Forbidden"); 914}; 915// Check address/port stored in AVPs src_adr/src_port is in group 2 916$avp(dst_adr) = "sipdomain.com"; 917$avp(dst_port) = "0"; 918if (!allow_address("2", "$avp(dst_adr)", "$avp(dst_port)") { 919 sl_send_reply("403", "Forbidden"); 920}; 921... 922 9234.8. allow_source_address([group_id]) 924 925 Equal to “allow_address(group_id, "$si", "$sp")”. If 'group_id' is 926 missing, the function is equal to allow_address("1", "$si", "$sp"). 927 928 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 929 930 Example 1.32. allow_source_address(group_id) usage 931... 932 933// Check source address/port of request 934if (!allow_source_address("1")) { 935 sl_send_reply("403", "Forbidden"); 936}; 937... 938 9394.9. allow_source_address_group() 940 941 Checks if source address/port is found in cached address or subnet 942 table in any group. If yes, returns that group. If not returns -1. Port 943 value 0 in cached address and group table matches any port. 944 945 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 946 947 Example 1.33. allow_source_address_group() usage 948... 949 950$var(group) = allow_source_address_group(); 951if ($var(group) != -1) { 952 # do something with $var(group) 953}; 954... 955 9564.10. allow_address_group(addr, port) 957 958 Checks if address/port is found in cached address or subnet table in 959 any group. If yes, returns that group. If not returns -1. Port value 0 960 in cached address and group table matches any port. The parameters can 961 be pseudo-variables. 962 963 This function can be used from ANY_ROUTE. 964 965 Example 1.34. allow_source_address_group() usage 966... 967 968$var(group) = allow_address_group("1.2.3.4", "5060"); 969if ($var(group) != -1) { 970 # do something with $var(group) 971}; 972... 973 9744.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar]) 975 976 Checks based either on request's source address and transport protocol 977 or source address and transport protocol given in pvar arguments, and 978 From URI of request (or furi_pvar if provided) if request can be 979 trusted without authentication. Returns “1” if a match is found as 980 described in Section 1.5, “Trusted Requests” and “-1” otherwise. If a 981 match is found and peer_tag_avp has been defined, adds a non-NULL tag 982 column value of the matching peer to AVP peer_tag_avp. 983 984 NOTE: source IP is matched using string comparison. Be careful if the 985 IP can have different forms, for a safer alternative for matching IP 986 addresses, look at allow_source_address or allow_address(). 987 988 Source address, transport protocol and uri given in the arguments must 989 be in string format and they can contain script variables. Valid 990 transport protocol values are (ignoring case) "any", "udp, "tcp", 991 "tls", "ws", "wss" and "sctp". 992 993 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. 994 995 Example 1.35. allow_trusted() usage 996... 997if (allow_trusted()) { 998 t_relay(); 999} 1000... 1001if (allow_trusted("$si", "$proto")) { 1002 t_relay(); 1003} 1004... 1005if (allow_trusted("$si", "any", "$ai")) { 1006 t_relay(); 1007} 1008... 1009 10105. RPC Commands 1011 1012 5.1. permissions.addressReload 1013 5.2. permissions.addressDump 1014 5.3. permissions.subnetDump 1015 5.4. permissions.domainDump 1016 5.5. permissions.testUri 1017 5.6. permissions.allowUri 1018 5.7. permissions.trustedReload 1019 5.8. permissions.trustedDump 1020 10215.1. permissions.addressReload 1022 1023 Causes the permissions module to re-read the contents of address 1024 database table into cache memory. In cache memory the entries are for 1025 performance reasons stored in two different tables: address table and 1026 subnet table depending on the value of the mask field (IPv6: 64 or 1027 smaller, IPv4: 32 or smaller). 1028 1029 Parameters: none 1030 10315.2. permissions.addressDump 1032 1033 Causes the permissions module to dump the contents of cache memory 1034 address table. (Not the subnet table). 1035 1036 Parameters: none 1037 10385.3. permissions.subnetDump 1039 1040 Causes permissions module to dump contents of cache memory subnet 1041 table. 1042 1043 Parameters: none 1044 10455.4. permissions.domainDump 1046 1047 Causes permissions module to dump contents of cache memory domain 1048 table. 1049 1050 Parameters: none 1051 10525.5. permissions.testUri 1053 1054 Tests if the (URI, Contact) pair is allowed according to allow/deny 1055 files. The files must already have been loaded by Kamailio. 1056 1057 Parameters: 1058 * basename - Basename from which allow and deny filenames will be 1059 created by appending contents of the allow_suffix and deny_suffix 1060 parameters. 1061 * URI - URI to be tested 1062 * Contact - Contact to be tested 1063 10645.6. permissions.allowUri 1065 10665.7. permissions.trustedReload 1067 1068 Causes the permissions module to re-read the contents of the trusted 1069 database table into cache memory. 1070 1071 Parameters: none 1072 10735.8. permissions.trustedDump 1074 1075 Causes the permissions module to dump contents of the trusted database 1076 table from cache memory. 1077 1078 Parameters: none 1079 10806. Address File Format 1081 1082 It is a text file with one record per line. Line starting with '#' are 1083 considered comments and ignored. Comments can be also at the end of 1084 records, by using '#' to start the comment part of the line. 1085 1086 Each record line has the format: 1087... 1088(groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o) 1089... 1090 1091 The groupid, address, netmask, port and tag are the names of the 1092 attributes whose values are expected in the respective order. The 'int' 1093 indicates that the value has to be an integer number. The 'str' 1094 indicates that the value has to be a string. The 'o' indicates that the 1095 attribute is optional. If netmask is not provided, it is set to 32 for 1096 IPv4 addresses and 128 for IPv6 addresses. If port is not provided, it 1097 is set to 0. The tag attribute is not set, if not provided. When 1098 provided, the tag value has to be a single token, without whitespaces 1099 (other punctuation signs can be in its value, like ',', '=', ';', ...). 1100 1101 Example 1.36. Address File Sample 1102... 1103# address file - records to match with allow_address(...) and variants 1104# * file format details 1105# - comments start with # and go to end of line 1106# - each line corresponds to a record with following attributes: 1107# 1108# (groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o) 1109# 1110# * description of the tokens used to describe line format 1111# - int: expected integer value 1112# - str: expected string value 1113# - o: optional field 1114 11151 127.0.0.1 32 0 tag1 11161 10.0.0.10 1117 11182 192.168.1.0 24 0 tag2 11192 192.168.2.0 24 0 tag3 1120 11213 [1:5ee::900d:c0de] 1122... 1123