"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/domainpolicy/README" (1 Oct 2019, 20387 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 Domain Policy Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. Dependencies
   10         1.3. Exported Parameters
   11 
   12               1.3.1. db_url (string)
   13               1.3.2. dp_table (string)
   14               1.3.3. dp_col_rule (string)
   15               1.3.4. dp_col_type (string)
   16               1.3.5. dp_col_att (string)
   17               1.3.6. dp_col_val (string)
   18               1.3.7. port_override_avp (string)
   19               1.3.8. transport_override_avp (string)
   20               1.3.9. domain_replacement_avp (string)
   21               1.3.10. domain_prefix_avp (string)
   22               1.3.11. domain_suffix_avp (string)
   23               1.3.12. send_socket_avp (string)
   24 
   25         1.4. Exported Functions
   26 
   27               1.4.1. dp_can_connect()
   28               1.4.2. dp_apply_policy()
   29 
   30         1.5. FIFO Commands
   31         1.6. Usage Scenarios
   32 
   33               1.6.1. TLS Based Federation
   34               1.6.2. SIP Hub based Federation
   35               1.6.3. Walled Garden Federation
   36 
   37         1.7. Known Limitations
   38 
   39    2. Contributors
   40 
   41         2.1. By Commit Statistics
   42         2.2. By Commit Activity
   43 
   44    3. Documentation
   45 
   46         3.1. Contributors
   47 
   48    List of Tables
   49 
   50    2.1. Top contributors by DevScore^(1), authored commits^(2) and
   51           lines added/removed^(3)
   52 
   53    2.2. Most recently active contributors^(1) to this module
   54 
   55    List of Examples
   56 
   57    1.1. Setting db_url parameter
   58    1.2. Setting dp_table parameter
   59    1.3. Setting dp_col_rule parameter
   60    1.4. Setting dp_col_rule parameter
   61    1.5. Setting dp_col_att parameter
   62    1.6. Setting dp_col_val parameter
   63    1.7. Setting port_override_avp parameter
   64    1.8. Setting transport_override_avp parameter
   65    1.9. Setting domain_replacement_avp parameter
   66    1.10. Setting domain_prefix_avp parameter
   67    1.11. Setting domain_suffix_avp parameter
   68    1.12. Setting send_socket_avp parameter
   69    1.13. dp_can_connect usage
   70    1.14. dp_apply_policy usage
   71 
   72 Chapter 1. Admin Guide
   73 
   74 1.1. Overview
   75 
   76    The Domain Policy module implements
   77    draft-lendl-domain-policy-ddds-02 in combination with
   78    draft-lendl-speermint-federations-02 and
   79    draft-lendl-speermint-technical-policy-00. These drafts define
   80    DNS records with which a domain can announce its federation
   81    memberships. A local database can be used to map policy rules
   82    to routing policy decisions. This database can also contain
   83    rules concerning destination domains independently of
   84    draft-lendl-domain-policy-ddds-02.
   85 
   86    This module requires a database. No caching is implemented.
   87 
   88 1.2. Dependencies
   89 
   90    The module depends on the following modules (in the other words
   91    the listed modules must be loaded before this module):
   92      * database -- Any database module
   93 
   94 1.3. Exported Parameters
   95 
   96 1.3.1. db_url (string)
   97 
   98    This is URL of the database to be used.
   99 
  100    Default value is
  101    “mysql://opensipsro:opensipsro@localhost/opensips”
  102 
  103    Example 1.1. Setting db_url parameter
  104 modparam("domainpolicy", "db_url", "postgresql://user:pass@db_host/opens
  105 ips")
  106 
  107 1.3.2. dp_table (string)
  108 
  109    Name of table containing the local support domain policy setup.
  110 
  111    Default value is “domainpolicy”.
  112 
  113    Example 1.2. Setting dp_table parameter
  114 modparam("domainpolicy", "dp_table", "supportedpolicies")
  115 
  116 1.3.3. dp_col_rule (string)
  117 
  118    Name of column containing the domain policy rule name which is
  119    equal to the URI as published in the domain policy NAPTRs.
  120 
  121    Default value is “rule”.
  122 
  123    Example 1.3. Setting dp_col_rule parameter
  124 modparam("domainpolicy", "dp_col_rule", "rules")
  125 
  126 1.3.4. dp_col_type (string)
  127 
  128    Name of column containing the domain policy rule type. In the
  129    case of federation names, this is "fed". For standard referrals
  130    according to draft-lendl-speermint-technical-policy-00, this is
  131    "std". For direct domain lookups, this is "dom".
  132 
  133    Default value is “type”.
  134 
  135    Example 1.4. Setting dp_col_rule parameter
  136 modparam("domainpolicy", "dp_col_type", "type")
  137 
  138 1.3.5. dp_col_att (string)
  139 
  140    Name of column containing the AVP's name. If the rule stored in
  141    this row triggers, than dp_can_connect() will add an AVP with
  142    that name.
  143 
  144    Default value is “att”.
  145 
  146    Example 1.5. Setting dp_col_att parameter
  147 modparam("domainpolicy", "dp_col_att", "attribute")
  148 
  149 1.3.6. dp_col_val (string)
  150 
  151    Name of column containing the value for AVPs created by
  152    dp_can_connect().
  153 
  154    Default value is “val”.
  155 
  156    Example 1.6. Setting dp_col_val parameter
  157 modparam("domainpolicy", "dp_col_val", "values")
  158 
  159 1.3.7. port_override_avp (string)
  160 
  161    This parameter defines the name of the AVP where
  162    dp_apply_policy() will look for an override port number.
  163 
  164    Default value is “portoverride”.
  165 
  166    Example 1.7. Setting port_override_avp parameter
  167 # string named AVP
  168 modparam("domainpolicy", "port_override_avp", "portoverride")
  169 
  170 1.3.8. transport_override_avp (string)
  171 
  172    Name of the AVP which contains the override transport setting.
  173 
  174    Default value is “transportoverride”.
  175 
  176    Example 1.8. Setting transport_override_avp parameter
  177 # string named AVP
  178 modparam("domainpolicy", "transport_override_avp", "transportoverride")
  179 
  180 1.3.9. domain_replacement_avp (string)
  181 
  182    Name of the AVP which contains a domain replacement.
  183 
  184    Default value is “domainreplacement”.
  185 
  186    Example 1.9. Setting domain_replacement_avp parameter
  187 # string named AVP
  188 modparam("domainpolicy", "domain_replacement_avp", "domainreplacement")
  189 
  190 1.3.10. domain_prefix_avp (string)
  191 
  192    Name of the AVP which contains a domain prefix.
  193 
  194    Default value is “domainprefix”.
  195 
  196    Example 1.10. Setting domain_prefix_avp parameter
  197 # string named AVP
  198 modparam("domainpolicy", "domain_prefix_avp", "domainprefix")
  199 
  200 1.3.11. domain_suffix_avp (string)
  201 
  202    Name of the AVP which contains a domain suffix.
  203 
  204    Default value is “domainsuffix”.
  205 
  206    Example 1.11. Setting domain_suffix_avp parameter
  207 # string named AVP
  208 modparam("domainpolicy", "domain_suffix_avp", "domainsuffix")
  209 
  210 1.3.12. send_socket_avp (string)
  211 
  212    Name of the AVP which contains a send_socket. The format of the
  213    send socket (the payload of this AVP) must be in the format
  214    [proto:]ip_address[:port]. The function dp_apply_policy will
  215    look for this AVP and if defined, it will force the send socket
  216    to its value (smilar to the force_send_socket core function).
  217 
  218    Default value is “sendsocket”.
  219 
  220    Example 1.12. Setting send_socket_avp parameter
  221 # string named AVP
  222 modparam("domainpolicy", "send_socket_avp", "sendsocket")
  223 
  224 1.4. Exported Functions
  225 
  226 1.4.1. dp_can_connect()
  227 
  228    Checks the interconnection policy of the caller. It uses the
  229    domain in the request URI to perform the DP-DDDS algorithm
  230    according to draft-lendl-domain-policy-ddds-02 to retrieve the
  231    domain's policy announcements. As of this version, only records
  232    conforming to draft-lendl-speermint-federations-02 and
  233    draft-lendl-speermint-technical-policy-00 are supported.
  234 
  235    Non-terminal NAPTR records will cause recursion to the
  236    replacement domain. dp_can_connect() will thus look for policy
  237    rules in the referenced domain. Furthermore, an AVP for
  238    "domainreplacement" (containing the new domain) will be added
  239    to the call. This will redirect SRV/A record lookups to the new
  240    domain.
  241 
  242    In order to simplify direct domain-based peerings all
  243    destination domains are treated as if they contain a top
  244    priority "D2P+SIP:dom" rule with the domain itself as the value
  245    of the rule. Thus any database row with type = 'dom' and rule =
  246    'example.com' will override any dynamic DNS-discovered rules.
  247 
  248    For NAPTRs with service-type "D2P+SIP:fed", the federation IDs
  249    (as extracted from the regexp field) are used to retrieve
  250    policy records from a local local database (basically: "SELECT
  251    dp_col_att, dp_col_val FROM dp_table WHERE dp_col_rule =
  252    '[federationID]' AND type = 'fed'). If records are found (and
  253    all other records with the same order value are fulfillable)
  254    then AVPs will be created from the dp_col_att and dp_col_val
  255    columns.
  256 
  257    For NAPTRs with service-type "D2P+SIP:std", the same procedure
  258    is performed. This time, the database lookup searched for type
  259    = 'std', though.
  260 
  261    "D2P+SIP:fed" and "D2P+SIP:std" can be mixed freely. If two
  262    rules with the same "order" match and try to set the same AVP,
  263    then the behaviour is undefined.
  264 
  265    The dp_col_att column specifies the AVP's name. If the AVP
  266    start with "s:" or "i:", the corresponding AVP type (string
  267    named or integer named) will be generated. If the excat
  268    specifier is omited, the AVP type will be guessed.
  269 
  270    The dp_col_val column will always be interpreted as string.
  271    Thus, the AVP's value is always string based.
  272 
  273    dp_can_connect returns:
  274      * -2: on errors during the evaluation. (DNS, DB, ...)
  275      * -1: D2P+SIP records were found, but the policy is not
  276        fullfillable.
  277      * 1: D2P+SIP records were found and a call is possible
  278      * 2: No D2P+SIP records were found. The destination domain
  279        does not announce a policy for incoming SIP calls.
  280 
  281    This function can be used from REQUEST_ROUTE.
  282 
  283    Example 1.13. dp_can_connect usage
  284 ...
  285 dp_can_connect();
  286 switch(retcode) {
  287         case -2:
  288                 xlog("L_INFO","Errors during the DP evaluation\n");
  289                 sl_send_reply("404", "We can't connect you.");
  290                 break;
  291         case -1:
  292                 xlog("L_INFO","We can't connect to that domain\n");
  293                 sl_send_reply("404", "We can't connect you.");
  294                 break;
  295         case 1:
  296                 xlog("L_INFO","We found matching policy records\n");
  297                 avp_print();
  298                 dp_apply_policy();
  299                 t_relay();
  300                 break;
  301         case 2:
  302                 xlog("L_INFO","No DP records found\n");
  303                 t_relay();
  304                 break;
  305 }
  306 ...
  307 
  308 1.4.2. dp_apply_policy()
  309 
  310    This function sets the destination URI according to the policy
  311    returned from the dp_can_connect() function. Parameter exchange
  312    between dp_can_connect() and dp_apply_policy() is done via
  313    AVPs. The AVPs can be configured in the module's parameter
  314    section.
  315 
  316    Note: The name of the AVPs must correspond with the names in
  317    the att column in the domainpolicy table.
  318 
  319    Setting the following AVPs in dp_can_connect() (or by any other
  320    means) cause the following actions in dp_apply_policy():
  321      * port_override_avp: If this AVP is set, the port in the
  322        destination URI is set to this port. Setting an override
  323        port disables NAPTR and SRV lookups according to RFC 3263.
  324 
  325      * transport_override_avp: If this AVP is set, the transport
  326        parameter in the destination URI is set to the specified
  327        transport ("udp", "tcp", "tls"). Setting an override
  328        transport also disables NAPTR lookups, but retains an SRV
  329        lookup according to RFC 3263.
  330 
  331      * domain_replacement_avp: If this AVP is set, the domain in
  332        the destination URI will be replaced by this domain.
  333        A non-terminal NAPTR and thus a referral to a new domain
  334        implicitly sets domain_replacement_avp to the new domain.
  335 
  336      * domain_prefix_avp: If this AVP is set, the domain in the
  337        destination URI will be prefixed with this "subdomain".
  338        E.g. if the domain in the request URI is "example.com" and
  339        the domain_prefix_avp contains "inbound", the domain in the
  340        destinaton URI is set to "inbound.example.com".
  341 
  342      * domain_suffix_avp: If this AVP is set, the domain in the
  343        destination URI will have the content of the AVP appended
  344        to it. E.g. if the domain in the request URI is
  345        "example.com" and the domain_suffix_avp contains
  346        "myroot.com", the domain in the destination URI is set to
  347        "example.com.myroot.com".
  348 
  349      * send_socket_avp: If this AVP is set, the sending socket
  350        will be forced to the socket in the AVP. The payload format
  351        of this AVP must be [proto:]ip_address[:port].
  352 
  353    If both prefix/suffix and domain replacements are used, then
  354    the replacement is performed first and the prefix/suffix are
  355    applied to the new domain.
  356 
  357    This function can be used from REQUEST_ROUTE.
  358 
  359    Example 1.14. dp_apply_policy usage
  360 ...
  361 if (dp_apply_policy()) {
  362         t_relay();
  363 }
  364 ...
  365 
  366 1.5. FIFO Commands
  367 
  368 1.6. Usage Scenarios
  369 
  370    This section describes how this module can be use to implement
  371    selective VoIP peerings.
  372 
  373 1.6.1. TLS Based Federation
  374 
  375    This example shows how a secure peering fabric can be
  376    configured based on TLS and Domain Policies.
  377 
  378    Let's assume that an organization called "TLSFED.org" acts as
  379    an umbrella for VoIP providers who want to peer with each other
  380    but don't want to run open SIP proxies. TLSFED.org's secretary
  381    acts as an X.509 Certification Authority that signs the TLS
  382    keys of all member's SIP proxies. Each member should
  383    automatically allow incoming calls from other members. On the
  384    other hand, the configuration for this federation must not
  385    interfere with a member's participation in other VoIP peering
  386    fabrics. All this can be achieved by the following
  387    configuration for a participating VoIP operation called
  388    example.com:
  389      * Incoming SIP configuration
  390        Calls from other members are expected to use TLS and
  391        authenticate using a client-CERT. To implement this, we
  392        cannot share a TCP/TLS port with other incoming connection.
  393        Thus we need to use tls_server_domain[] to dedicate a TCP
  394        port for this federation.
  395 
  396 tls_server_domain[1.2.3.4:5066] {
  397  tls_certificate   = "/path/to/tlsfed/example-com.key"
  398  tls_private_key   = "/path/to/tlsfed/example-com.crt"
  399  tls_ca_list       = "/path/to/tlsfed/ca.pem"
  400  tls_method        = tlsv1
  401  tls_verify_client = 1
  402  tls_require_cleint_certificate = 1
  403 }
  404 
  405 
  406      * Outgoing SIP configuration
  407        Calls to other members also must use the proper client
  408        cert. Therefore, a TLS client domain must be configured. We
  409        use the federation name as TLS client domain identifier.
  410        Therefore, the content of the "tls_client_domain_avp" must
  411        be set to this identifier (e.g. by putting it as rule into
  412        the domainpolicy table).
  413 
  414 tls_client_domain["tlsfed"] {
  415  tls_certificate   = "/path/to/tlsfed/example-com.key"
  416  tls_private_key   = "/path/to/tlsfed/example-com.crt"
  417  tls_ca_list       = "/path/to/tlsfed/ca.pem"
  418  tls_method        = tlsv1
  419  tls_verify_server = 1
  420 }
  421 
  422 1.6.2. SIP Hub based Federation
  423 
  424    This example shows how a peering fabric based on a central SIP
  425    hub can be configured.
  426 
  427    Let's assume that an organization called "HUBFED.org" acts as
  428    an umbrella for VoIP providers who want to peer with each other
  429    but don't want to run open SIP proxies. Instead, HUBFED.org
  430    operates a central SIP proxy which will relay calls between all
  431    participating members. Each member thus only needs to allow
  432    incoming calls from that central hub (which could be done by
  433    firewalling). All this can be achieved by the following
  434    configuration for a participating VoIP operation called
  435    example.com:
  436      * DNS configuration
  437        The destination network announces its membership in this
  438        federation.
  439 
  440 $ORIGIN destination.example.org
  441 @ IN NAPTR 10 50   "U"  "D2P+SIP:fed" (
  442                  "!^.*$!http://HUBFED.org/!" . )
  443 
  444 
  445      * Outgoing SIP configuration
  446        Calls to other members need to be redirected to the central
  447        proxy. The domainpolicy table just needs to list the
  448        federation and link it to the central proxy's domain name:
  449 
  450 mysql> select * from domainpolicy;
  451 +----+--------------------+------+-------------------+----------------+
  452 | id | rule               | type | att               | val            |
  453 +----+--------------------+------+-------------------+----------------+
  454 | 1  | http://HUBFED.org/ | fed  | domainreplacement | sip.HUBFED.org |
  455 +----+--------------------+------+-------------------+----------------+
  456 
  457 
  458 1.6.3. Walled Garden Federation
  459 
  460    This example assumes that a set of SIP providers have
  461    established a secure Layer 3 network between their proxies. It
  462    does not matter whether this network is build by means of
  463    IPsec, a private Layer 2 network, or by simple firewalling. We
  464    will use the 10.x network (for the walled garden net) and
  465    "http://l3fed.org/" (as federation identifier) in this example.
  466 
  467    A member of this federation (e.g. example.com) can not announce
  468    its SIP proxy's 10.x address in the standard SRV / A records of
  469    his domain, as this address is only meaningful for other
  470    members of this federation. In order to facilite different IP
  471    address resolution paths within the federation vs. outside the
  472    federation, all members of "http://l3fed.org/" agree to prefix
  473    the destination domains with "l3fed" before the SRV (or A)
  474    lookup.
  475 
  476    Here is the configuration for example.com:
  477      * DNS configuration
  478        The destination network announces its membership in this
  479        federation.
  480 
  481 $ORIGIN example.com
  482 @ IN NAPTR 10 50   "U"  "D2P+SIP:fed" (
  483                  "!^.*$!http://l3fed.org/!" . )
  484 _sip._udp      IN SRV 10 10 5060 publicsip.example.com.
  485 _sip._udp.l3fe IN SRV 10 10 5060 l3fedsip.example.com.
  486 
  487 publicsip      IN A   193.XXX.YYY.ZZZ
  488 l3fedsip       IN A   10.0.0.42
  489 
  490 
  491      * Outgoing SIP configuration
  492        The domainpolicy table just needs to link the federation
  493        identifier to the agreed apon prefix:
  494 
  495 mysql> select * from domainpolicy;
  496 +----+-------------------+------+--------------+-------+
  497 | id | rule              | type | att          | val   |
  498 +----+-------------------+------+--------------+-------+
  499 | 1  | http://l3fed.org/ | fed  | domainprefix | l3fed |
  500 +----+-------------------+------+--------------+-------+
  501 
  502 
  503 1.7. Known Limitations
  504 
  505 Chapter 2. Contributors
  506 
  507 2.1. By Commit Statistics
  508 
  509    Table 2.1. Top contributors by DevScore^(1), authored
  510    commits^(2) and lines added/removed^(3)
  511      Name DevScore Commits Lines ++ Lines --
  512    1. Bogdan-Andrei Iancu (@bogdan-iancu) 21 15 178 214
  513    2. Klaus Darilion 21 1 2456 0
  514    3. Razvan Crainea (@razvancrainea) 13 8 59 171
  515    4. Liviu Chircu (@liviuchircu) 11 8 37 62
  516    5. Daniel-Constantin Mierla (@miconda) 10 8 19 21
  517    6. Henning Westerholt (@henningw) 6 4 25 25
  518    7. Vlad Patrascu (@rvlad-patrascu) 4 2 6 4
  519    8. Konstantin Bokarius 3 1 2 5
  520    9. Peter Lemenkov (@lemenkov) 3 1 1 1
  521    10. UnixDev 3 1 1 1
  522 
  523    All remaining contributors: Edson Gellert Schubert.
  524 
  525    (1) DevScore = author_commits + author_lines_added /
  526    (project_lines_added / project_commits) + author_lines_deleted
  527    / (project_lines_deleted / project_commits)
  528 
  529    (2) including any documentation-related commits, excluding
  530    merge commits. Regarding imported patches/code, we do our best
  531    to count the work on behalf of the proper owner, as per the
  532    "fix_authors" and "mod_renames" arrays in
  533    opensips/doc/build-contrib.sh. If you identify any
  534    patches/commits which do not get properly attributed to you,
  535    please submit a pull request which extends "fix_authors" and/or
  536    "mod_renames".
  537 
  538    (3) ignoring whitespace edits, renamed files and auto-generated
  539    files
  540 
  541 2.2. By Commit Activity
  542 
  543    Table 2.2. Most recently active contributors^(1) to this module
  544                       Name                   Commit Activity
  545    1.  Razvan Crainea (@razvancrainea)     Jun 2011 - Sep 2019
  546    2.  Bogdan-Andrei Iancu (@bogdan-iancu) Dec 2006 - Apr 2019
  547    3.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
  548    4.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
  549    5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
  550    6.  UnixDev                             Feb 2009 - Feb 2009
  551    7.  Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008
  552    8.  Konstantin Bokarius                 Mar 2008 - Mar 2008
  553    9.  Edson Gellert Schubert              Feb 2008 - Feb 2008
  554    10. Henning Westerholt (@henningw)      Jul 2007 - Jan 2008
  555 
  556    All remaining contributors: Klaus Darilion.
  557 
  558    (1) including any documentation-related commits, excluding
  559    merge commits
  560 
  561 Chapter 3. Documentation
  562 
  563 3.1. Contributors
  564 
  565    Last edited by: Peter Lemenkov (@lemenkov), Liviu Chircu
  566    (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu),
  567    Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
  568    Gellert Schubert, Klaus Darilion.
  569 
  570    Documentation Copyrights:
  571 
  572    Copyright © 2002,2003,2006 Juha Heinanen, Otmar Lendl, Klaus
  573    Darilion