Network Working Group Sajitha T. T. Internet-Draft Hewlett Packard Expires: April 19, 2006 October 20, 2005 An ENUM Library API draft-sajitha-enum-api-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on April 19, 2006. Copyright Notice Copyright (C) The Internet Society (2005). All Rights Reserved. Sajitha Expires April 19, 2006 [Page 1] Internet-Draft sajitha-enum-api October 2005 Table of Contents 1. Abstract.............................................2 2. Introduction.........................................2 3. Telephone number to URI Mapping......................2 4. Error Return Values..................................5 5. IANA Considerations..................................6 6. Security Considerations..............................6 7. References...........................................6 8. Author's Address.....................................6 9. Intellectual Property Statement......................7 1. Abstract This draft defines a library API for ENUM. The API takes telephone number as input and returns the URI associated with that telephone number. 2. Introduction ENUM (E.164 Number Mapping, RFC 3761) is a system that uses DNS (Domain Name Service, STD 13, RFC 1034) to translate telephone numbers, like '+12025332600', into URIs (Uniform Resource Identifiers, RFC 2396), like 'sip:egar@example.com'. ENUM exists primarily to facilitate the interconnection of systems that rely on telephone numbers with those that use URIs to route transactions. Currently each of the application which requires ENUM information need to explicitly perform the input validation, DNS lookup for NAPTR records and then analyze & filter the required information from the response received from DNS server. It is felt that providing a library function which performs the resolution of E.164 number into the URI will take out the overhead from the applications. 3. Telephone number to URI Mapping This document describes a library function for retrieval of ENUM information. The ENUM uses DNS as the database [RFC 3761]. Thus this library function will retrieve data from DNS database. #include int geturiinfo(const char *telephonenum, char *service_type, struct uriinfo **res); void freeuriinfo(struct uriinfo *ptr); struct ui_service_subtype { char *type; int len; struct ui_service_subtype *ui_next; } Sajitha Expires April 19, 2006 [Page 2] Internet-Draft sajitha-enum-api October 2005 struct uriinfo { int ui_order; /* A 16-bit unsigned integer */ int ui_preference; /* A 16-bit unsigned integer */ char *ui_service_type; int ui_servtypelen; struct *ui_service_subtype subtype; char *uri; int ui_urilen; struct uriinfo *ui_next; /* next structure in linked list */ }; The geturiinfo() function translates the E.164 telephone number (for example, +12025332600) to URI(for example, sip:egar@example.com). This API takes 3 arguments. The inputs for this API are E.164 number and the service type. The service type should be one which is registered & published as Enumservice with IANA (For example, the IANA Registration for Enumservice 'web' and 'ft' as given in RFC4002). The 3rd argument is the pointer to a liked list of uriinfo structure which contains the results got from DNS. The API should form the dns name to be queried from the E.164 number using the following algorithm: 1. Remove all characters with the exception of the digits. For example, for the E.164 number "+442079460148", this step would simply remove the leading "+", producing "442079460148". Implementation note: The telephone number can be considered to be in the form of . A common country code can be prefixed to the input telephone number if it is less than 12 digits. 2. Put dots (".") between each digit. Example: 4.4.2.0.7.9.4.6.0.1.4.8 3. Reverse the order of the digits. Example: 8.4.1.0.6.4.9.7.0.2.4.4 4. Append the string ".e164.arpa" to the end. Example: 8.4.1.0.6.4.9.7.0.2.4.4.e164.arpa The output from step 4 is the domain-name which is used to query DNS database. The query type for the DNS request should be NAPTR record type. DNS response will contain all NAPTR records for this particular domain name. Sajitha Expires April 19, 2006 [Page 3] Internet-Draft sajitha-enum-api October 2005 The DNS response should be parsed by the API as given below: 1. If service type is NULL, all URIs corresponding to this E.164 number should be returned along with the corresponding service type, service type length, all service subtypes & service subtype length. In case of non NULL service type, all the records in the DNS response should be parsed one by one applying the following rule: 2. If it encounters a record with an unknown flag field in the response, it MUST ignore it and move to the next one. This test takes precedence over any ordering since flags can control the interpretation placed on fields. 3. If the service field doesn't start with "E2U", ignore the particular record and move to next one. 4. If the flag field doesn't contain "U", ignore this record (As this is the only flag defined for ENUM. [Section 2.4.1 of RFC3761]) 5. Extract the service type from the service field [Section 2.4.2 of RFC3761] and compare against the requested type. If matches add this record information to the uriinfo result list otherwise ignore that record and process the next one in the response. Since the matching record will be a terminal one, the REGEXP starts with "!^.*$!". This string should be removed from the REGEXP field and the rest of it should be copied to the uri member of uriinfo structure. The length of URI should be filled in the ui_urilen member. One or more subtypes present in the record should be copied to a linked list of type ui_service_subtype and the subtype member of uriinfo structure should point to this list. Also the 'order' and 'preference' fields of NAPTR record should be copied to the ui_order & ui_preference member of uriinfo structure. 6. Finally the uriinfo list has to be sorted based on the preference value. It is assumed that the DNS response will contain the best matching order field of the NAPTR record. Sajitha Expires April 19, 2006 [Page 4] Internet-Draft sajitha-enum-api October 2005 The following function frees the dynamic memory that was allocated by geturiinfo(). #include void freeuriinfo(struct uriinfo *ptr); The ptr argument shall be a pointer that was returned by geturiinfo(). After geturiinfo() has been called, the application shall not use the array of which ptr is the address. Functions geturiinfo() and freeuriinfo() must be thread-safe. A zero return value for geturiinfo() indicates successful completion; a non-zero return value indicates failure. The possible values for the failures are listed in the Error Return Values section of this document. Upon successful return of geturiinfo(), the location to which 'res' points shall refer to a linked list of uriinfo structures, each of which shall specify a URI & URI length and associated information (service type, length, service subtypes & subtype length). The list shall include at least one uriinfo structure. The ui_next field of each structure contains a pointer to the next structure on the list, or a null pointer if it is the last structure on the list. 4. Error Return Values [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. [EAI_FAIL] A non-recoverable error occurred when attempting to resolve the name. [EAI_MEMORY] There was a memory allocation failure when trying to allocate storage for the return value. [EAI_E164NUM] The telephone number given is not a valid E.164 number. [EAI_NO_U_FLAG] The flag field doesn't contain "U" [EAI_UNKNOWNFLAG] The flag field is unknown [EAI_NO_E2U] No "E2U" in the service field [EAI_SERVICE] No match for the given service type [EAI_SYSTEM] A system error occurred; the error code can be found in errno. More than one of the error codes from among EAI_NO_U_FLAG, EAI_UNKNOWNFLAG, EAI_NO_E2U, EAI_SERVICE can be returned. In that case the return value must be the logical OR of individual values. Sajitha Expires April 19, 2006 [Page 5] Internet-Draft sajitha-enum-api October 2005 5. IANA Considerations There are no new IANA considerations other than those given in the "IANA consideration" section of RFC 3761. 6. Security Considerations This document lays out no new considerations for security other than normal DNS security considerations. 7. References [1] The E.164 to Uniform Resource Identifiers (URI), Dynamic Delegation Discovery System (DDDS) Application (ENUM RFC 3761) [2] Domain Name Service, STD 13, RFC 1034 [3] Uniform Resource Identifiers, RFC 2396 [4] Dynamic Delegation Discovery System (DDDS) Part One: The Comprehensive DDDS, RFC 3401 [5] Dynamic Delegation Discovery System (DDDS) Part Two: The Algorithm, RFC 3402 [6] Dynamic Delegation Discovery System (DDDS) Part Three: The Domain Name System (DNS) Database, RFC 3403 8. Author's Address Sajitha T. T. Hewlett-Packard STSD-I 29, Cunningham Road Bangalore - 560052 India E-Mail: sajitha@india.hp.com Sajitha Expires April 19, 2006 [Page 6] Internet-Draft sajitha-enum-api October 2005 9. Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf- ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Sajitha Expires April 19, 2006 [Page 7]