michael@12: Enum Module
michael@12: 
michael@12: Juha Heinanen
michael@12: 
michael@12:    <jh@song.fi>
michael@12: 
michael@12: Otmar Lendl
michael@12: 
michael@12:    <lendl@nic.at>
michael@12: 
michael@12:    Copyright © 2002, 2003 Juha Heinanen
michael@12:    Revision History
michael@13:    Revision $Revision: 5907 $ $Date: 2010-01-18 10:45:05 +0100
michael@13:                               (Mon, 18 Jan 2010) $
michael@12:      __________________________________________________________
michael@12: 
michael@12:    Table of Contents
michael@12: 
michael@12:    1. Admin Guide
michael@12: 
michael@12:         1.1. Overview
michael@12:         1.2. Dependencies
michael@12:         1.3. Exported Parameters
michael@12: 
michael@12:               1.3.1. domain_suffix (string)
michael@12:               1.3.2. tel_uri_params (string)
michael@12:               1.3.3. i_enum_suffix (string)
michael@13:               1.3.4. isn_suffix (string)
michael@13:               1.3.5. branchlabel (string)
michael@13:               1.3.6. bl_algorithm (string)
michael@12: 
michael@12:         1.4. Exported Functions
michael@12: 
michael@12:               1.4.1. enum_query(["suffix"[,"service"]])
michael@12:               1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
michael@12:               1.4.3. i_enum_query(["suffix"[,"service"]])
michael@13:               1.4.4. isn_query(["suffix"[,"service"]])
michael@13:               1.4.5. is_from_user_enum()
michael@12: 
michael@12:    List of Examples
michael@12: 
michael@12:    1.1. Setting domain_suffix module parameter
michael@12:    1.2. Setting tel_uri_params module parameter
michael@12:    1.3. Setting i_enum_suffix module parameter
michael@13:    1.4. Setting isn_query usage module parameter
michael@13:    1.5. Setting branchlabel module parameter
michael@12:    1.6. Zone file example
michael@13:    1.7. Zone file example
michael@13:    1.8. Setting the bl_algorithm module parameter
michael@13:    1.9. enum_query usage
michael@13:    1.10. enum_pv_query usage
michael@13:    1.11. isn_query usage
michael@13:    1.12. is_from_user_enum usage
michael@12: 
michael@12: Chapter 1. Admin Guide
michael@12: 
michael@12: 1.1. Overview
michael@12: 
michael@12:    Enum module implements [i_]enum_query functions that make an
michael@12:    enum query based on the user part of the current Request-URI.
michael@12:    These functions assume that the user part consists of an
michael@12:    international phone number of the form +decimal-digits, where
michael@12:    the number of digits is at least 2 and at most 15. Out of this
michael@12:    number enum_query forms a domain name, where the digits are in
michael@12:    reverse order and separated by dots followed by domain suffix
michael@12:    that by default is "e164.arpa.". For example, if the user part
michael@12:    is +35831234567, the domain name will be
michael@12:    "7.6.5.4.3.2.1.3.8.5.3.e164.arpa.". i_enum_query operates in a
michael@12:    similar fashion. The only difference is that it adds a label
michael@12:    (default "i") to branch off from the default, user-ENUM tree to
michael@12:    an infrastructure ENUM tree.
michael@12: 
michael@12:    After forming the domain name, enum_query queries DNS for its
michael@12:    NAPTR records. From the possible response enum_query chooses
michael@12:    those records, whose flags field has string value "u", and
michael@12:    whose services field has string value "e2u+[service:]sip" or
michael@12:    "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in
michael@12:    both cases), and whose regexp field is of the form
michael@12:    !pattern!replacement!.
michael@12: 
michael@12:    Then enum_query sorts the chosen NAPTR records based on their
michael@12:    <order, preference>. After sorting, enum_query replaces the
michael@12:    current Request URI by applying regexp of the most preferred
michael@12:    NAPTR record its user part and appends to the request new
michael@12:    branches by applying regexp of each remaining NAPTR record to
michael@12:    the user part of the current Request URI. If a new URI is a tel
michael@12:    URI, enum_query appends to it as tel URI parameters the value
michael@12:    of tel_uri_params module parameter. Finally, enum_query
michael@12:    associates a q value with each new URI based on the <order,
michael@12:    preference> of the corresponding NAPTR record.
michael@12: 
michael@12:    When using enum_query without any parameters, it searches for
michael@12:    NAPTRs with service type "e2u+sip" in the default enum tree.
michael@12:    When using enum_query with a single parameter, this parameter
michael@12:    will be used as enum tree. When using enum_query with two
michael@12:    parameters, the functionality depends on the first letter in
michael@12:    the second parameter. When the first letter is not a '+' sign,
michael@12:    the second parameter will be used to search for NAPTRs with
michael@12:    service type "e2u+parameter:sip". When the second parameter
michael@12:    starts with a '+' sign, the ENUM lookup also supports compound
michael@12:    NAPTRs (e.g. "e2u+voice:sip+video:sip") and searching for
michael@12:    multiple service types within one lookup. Multiple service
michael@12:    types must be separeted by a '+' sign.
michael@12: 
michael@12:    Most of the time you want to route based on the RURI. On rare
michael@12:    occasions you may wish to route based on something else. The
michael@12:    function enum_pv_query mimics the behavior of the enum_query
michael@12:    function except the E.164 number in its pseudo variable
michael@12:    argument is used for the enum lookup instead of the user part
michael@12:    of the RURI. Obviously the user part of the RURI is still used
michael@12:    in the NAPTR regexp.
michael@12: 
michael@12:    Enum query returns 1 if the current Request URI was replaced
michael@12:    and -1 if not.
michael@12: 
michael@12:    Enum module also implements is_from_user_enum function. This
michael@12:    function does an enum lookup on the from user and returns true
michael@12:    if found, false otherwise.
michael@12: 
michael@13:    In addition to standard ENUM, support for ISN (ITAD Subscriber
michael@13:    Numbers) is provided as well. To allow ISN lookups to resolve,
michael@13:    a different formatting algorithm is expected by the DNS server.
michael@13:    Whereas a ENUM NAPTR record expects a DNS query of the form
michael@13:    9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of
michael@13:    the form 6.5.1212.<suffix>. That is, a valid ISN number includes
michael@13:    a prefix of '56' in the example. The rest of the number is a
michael@13:    ITAD (Internet Telephony Administrative Domain) as defined
michael@13:    in RFCs 3872 and 2871, and as allocated by the IANA in
michael@13:    http://www.iana.org/assignments/trip-parameters. The ITAD is
michael@13:    left intact and not refersed as ENUM requires. To learn more
michael@13:    about ISN please refer to documents at www.freenum.org.
michael@13: 
michael@13:    To complete a ISN lookup on the user part of the Request-URI,
michael@13:    isn_query() is used instead of enum_query().
michael@13: 
michael@12: 1.2. Dependencies
michael@12: 
michael@12:    The module depends on the following modules (in the other words
michael@12:    the listed modules must be loaded before this module):
michael@12:      * No dependencies.
michael@12: 
michael@12: 1.3. Exported Parameters
michael@12: 
michael@12: 1.3.1. domain_suffix (string)
michael@12: 
michael@12:    The domain suffix to be added to the domain name obtained from
michael@12:    the digits of an E164 number. Can be overridden by a parameter
michael@12:    to enum_query.
michael@12: 
michael@12:    Default value is "e164.arpa."
michael@12: 
michael@12:    Example 1.1. Setting domain_suffix module parameter
michael@12: modparam("enum", "domain_suffix", "e1234.arpa.")
michael@12: 
michael@12: 1.3.2. tel_uri_params (string)
michael@12: 
michael@12:    A string whose contents is appended to each new tel URI in the
michael@12:    request as tel URI parameters.
michael@12: 
michael@12: Note
michael@12: 
michael@12:    Currently OpenSIPS does not support tel URIs. This means that
michael@12:    at present tel_uri_params is appended as URI parameters to
michael@12:    every URI.
michael@12: 
michael@12:    Default value is ""
michael@12: 
michael@12:    Example 1.2. Setting tel_uri_params module parameter
michael@12: modparam("enum", "tel_uri_params", ";npdi")
michael@12: 
michael@12: 1.3.3. i_enum_suffix (string)
michael@12: 
michael@12:    The domain suffix to be used for i_enum_query() lookups. Can be
michael@12:    overridden by a parameter to i_enum_query.
michael@12: 
michael@12:    Default value is "e164.arpa."
michael@12: 
michael@12:    Example 1.3. Setting i_enum_suffix module parameter
michael@12: modparam("enum", "i_enum_suffix", "e1234.arpa.")
michael@12: 
michael@13: 1.3.4. isn_suffix (string)
michael@13: 
michael@13:    The domain suffix to be used for isn_query() lookups. Can be
michael@13:    overridden by a parameter to isn_query.
michael@13: 
michael@13:    Default value is "freenum.org."
michael@13: 
michael@13:    Example 1.4. Setting isn_suffix module parameter
michael@13: modparam("enum", "isn_suffix", "freenum.org.")
michael@13: 
michael@13: 1.3.5. branchlabel (string)
michael@12: 
michael@12:    This parameter determines which label i_enum_query() will use
michael@12:    to branch off to the infrastructure ENUM tree.
michael@12: 
michael@12:    Default value is ""i""
michael@12: 
michael@13:    Example 1.5. Setting branchlabel module parameter
michael@12: modparam("enum", "branchlabel", "i")
michael@12: 
michael@13: 1.3.6. bl_algorithm (string)
michael@12: 
michael@12:    This parameter determines which algorithm i_enum_query() will
michael@12:    use to select the position in the DNS tree where the
michael@12:    infrastructure tree branches off the user ENUM tree.
michael@12: 
michael@12:    If set to "cc", i_enum_query() will always inserts the label at
michael@12:    the country-code level. Examples: i.1.e164.arpa,
michael@12:    i.3.4.e164.arpa, i.2.5.3.e164.arpa
michael@12: 
michael@12:    If set to "txt", i_enum_query() will look for a TXT record at
michael@12:    [branchlabel].[reverse-country-code].[i_enum_suffix] to
michael@12:    indicate after how many digits the label should in inserted.
michael@12: 
michael@13:    Example 1.6. Zone file example
michael@12: i.1.e164.arpa.                     IN TXT   "4"
michael@12: 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5
michael@12: 678 999"
michael@12: 
michael@12:    If set to "ebl", i_enum_query() will look for an EBL (ENUM
michael@12:    Branch Label) record at
michael@12:    [branchlabel].[reverse-country-code].[i_enum_suffix]. See
michael@12:    http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-loc
michael@12:    ation-record-00.txt for a description of that record and the
michael@12:    meaning of the fields. The RR type for the EBL has not been
michael@12:    allocated yet. This version of the code uses 65300. See
michael@12:    resolve.h.
michael@12: 
michael@13:    Example 1.7. Zone file example
michael@12: i.1.e164.arpa.     TYPE65300  \# 14 (
michael@12:                               04    ; position
michael@12:                               01 69 ; separator
michael@12:                               04 65 31 36 34 04 61 72 70 61 00 ; e164.ar
michael@12: pa
michael@12: ;                               )
michael@12: 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5
michael@12: 678 999"
michael@12: 
michael@12:    Default value is "cc"
michael@12: 
michael@13:    Example 1.8. Setting the bl_algorithm module parameter
michael@12: modparam("enum", "bl_algorithm", "txt")
michael@12: 
michael@12: 1.4. Exported Functions
michael@12: 
michael@12: 1.4.1.  enum_query(["suffix"[,"service"]])
michael@12: 
michael@12:    The function performs an enum query and rewrites the
michael@12:    Request-URI with the result of the query. See Section 1.1,
michael@12:    "Overview" for more information.
michael@12: 
michael@12:    Meaning of the parameters is as follows:
michael@12:      * suffix - Suffix to be appended to the domain name.
michael@12:      * service - Service string to be used in the service field.
michael@12: 
michael@12:    This function can be used from REQUEST_ROUTE.
michael@12: 
michael@13:    Example 1.9. enum_query usage
michael@12: ...
michael@12: # search for "e2u+sip" in freenum.org
michael@12: enum_query("freenum.org.");
michael@12: ...
michael@12: # search for "e2u+sip" in default tree (configured as parameter)
michael@12: enum_query();
michael@12: ...
michael@12: # search for "e2u+voice:sip" in e164.arpa
michael@12: enum_query("e164.arpa.","voice");
michael@12: ...
michael@12: # search for service type "sip" or "voice:sip" or "video:sip"
michael@12: # note the '+' sign in front of the second parameter
michael@12: enum_query("e164.arpa.","+sip+voice:sip+video:sip");
michael@12: ...
michael@12: # quering for service sip and voice:sip
michael@12: enum_query("e164.arpa.");
michael@12: enum_query("e164.arpa.","voice");
michael@12: # or use instead
michael@12: enum_query("e164.arpa.","+sip+voice:sip");
michael@12: ...
michael@12: 
michael@12: 1.4.2.  enum_pv_query("pvar"[,"suffix"[,"service"]])
michael@12: 
michael@12:    The function performs an enum query on E.164 number stored in
michael@12:    its pseudo variable argument and rewrites the Request-URI with
michael@12:    the result of the query. See Section 1.1, "Overview" for more
michael@12:    information.
michael@12: 
michael@12:    Meaning of the parameters is as follows:
michael@12:      * pvar - Pseudo variable that holds an E.164 number on which
michael@12:        enum query is performed.
michael@12:      * suffix - Suffix to be appended to the domain name.
michael@12:      * service - Service string to be used in the service field.
michael@12: 
michael@12:    This function can be used from REQUEST_ROUTE.
michael@12: 
michael@13:    Example 1.10. enum_pv_query usage
michael@12: ...
michael@12: # search for "e2u+sip" in freenum.org
michael@12: enum_pv_query("$avp(i:100)", "freenum.org.");
michael@12: ...
michael@12: # search for "e2u+sip" in default tree (configured as parameter)
michael@12: enum_pv_query("$fU");
michael@12: ...
michael@12: # search for "e2u+voice:sip" in e164.arpa
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12: ...
michael@12: # search for service type "sip" or "voice:sip" or "video:sip"
michael@12: # note the '+' sign in front of the second parameter
michael@12: enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");
michael@12: ...
michael@12: # quering for service sip and voice:sip
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.");
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12: # or use instead
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
michael@12: ...
michael@12: 
michael@12: 1.4.3.  i_enum_query(["suffix"[,"service"]])
michael@12: 
michael@12:    The function performs an enum query and rewrites the
michael@12:    Request-URI with the result of the query. This the
michael@12:    Infrastructure-ENUM version of enum_query(). The only
michael@12:    difference to enum_query() is in the calculation of the FQDN
michael@12:    where NAPTR records are looked for.
michael@12: 
michael@12:    See
michael@12:    ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberle
michael@12:    r-carrier-enum-01.txt for the rationale behind this function.
michael@12: 
michael@13: 1.4.4.  isn_query(["suffix"[,"service"]])
michael@13: 
michael@13:    The function performs a ISN query and rewrites the
michael@13:    Request-URI with the result of the query. See Section 1.1,
michael@13:    "Overview" for more information.
michael@13: 
michael@13:    Meaning of the parameters is as follows:
michael@13:      * suffix - Suffix to be appended to the domain name.
michael@13:      * service - Service string to be used in the service field.
michael@13: 
michael@13:    This function can be used from REQUEST_ROUTE.
michael@13: 
michael@15:    See ftp://ftp.ietf.org/rfc/rfc3872.txt and
michael@15:    ftp://ftp.ietf.org/rfc/rfc2871.txt for information
michael@13:    regarding the ITAD part of the ISN string.
michael@13: 
michael@13:    Example 1.11. isn_query usage
michael@13: ...
michael@13: # search for "e2u+sip" in freenum.org
michael@13: isn_query("freenum.org.");
michael@13: ...
michael@13: # search for "e2u+sip" in default tree (configured as parameter)
michael@13: enum_query();
michael@13: ...
michael@13: # search for "e2u+voice:sip" in freenum.org
michael@13: enum_query("freenum.org.","voice");
michael@13: ...
michael@13: 
michael@13: 1.4.5. is_from_user_enum()
michael@12: 
michael@12:    Checks if the user part of from URI is found in an enum lookup.
michael@12:    Returns 1 if yes and -1 if not.
michael@12: 
michael@12:    This function can be used from REQUEST_ROUTE.
michael@12: 
michael@13:    Example 1.12. is_from_user_enum usage
michael@12: ...
michael@12: if (is_from_user_enum()) {
michael@12:         ....
michael@12: };
michael@12: ...