Network Working Group M. Riegel Internet-Draft Siemens AG Category: Standards Track G. Zorn Microsoft Corporation October 1999 XML DTD for Phone Books 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. The distribution of this memo is unlimited. It is filed as , and expires April 23, 2000. Please send comments to the Roaming Operations Working Group mailing list (roamops@tdmx.rutgers.edu) or to the editor of this draft (maximilian.riegel@icn.siemens.de). 2. Abstract This document defines the syntax as well as the semantics of the information to be included in the phone book for roaming applications. It comprises the information necessary to select the most appropriate ISP and to configure the host to get access to the network of the provider. The specification consists of a small set of required information elements and a variety of possible extensions. All data is specified in XML [5] (Extensible Markup Language) syntax leading to a concise XML DTD (Document Type Declaration) for the phone book. Riegel, Zorn Expires April 2000 [Page 1] Internet-Draft Phone Book XML DTD October 1999 3. Introduction Roaming applications depend on the delivery of information about provided services and the procedures to get connected to the network from the roaming consortium to the individual users as well as from the operators of the network access servers, normally the members of the roaming consortium, and the roaming consortium. "phone book" +------+ +--+ | | | ++ | ISP1 | -- | | --+ | | +---+ \ "phone book" +------+ \ +------+ +------+ +--+ \_ | | +--+ +------+ | | | ++ | | | ++ | | | ISP2 | -- | | -->>--- | | --- | | ->> | USER | | | +---+ _ | | +---+ | | +------+ / | | +------+ +------+ +--+ / +------+ | | | ++ / Roaming | ISP# | -- | | --+ Consortium | | +---+ +------+ The roaming consortium assembles from the individual contributions of the providers belonging to the consortium a unified version of the phone book for usage by the customers. Probably different groups of users get different versions of a phone book adapted to their particular needs. Even users might generate different subsets especially suited to particular applications from the information received from the roaming consortium, e.g. retrieving only entries for a particular country or extracting all access points providing wireless connectivity. Therefore it is desirable to define a highly portable and well formed structure of the phone book to enable easy generation and postprocessing. Goals of this document include: - Creating a flexible, extensible and robust framework upon which to build a standard phone book; - Promoting a standard phone book format, to enhance interoperability between ISPs and roaming consortia as well as to enable automatic extraction of configuration data by a wide variety of devices; - Defining a compact structure containing the essential information for the roaming user, to allow for storage and easy update even on small devices. Riegel, Zorn Expires April 2000 [Page 2] Internet-Draft Phone Book XML DTD October 1999 It is not intended by this document to create a plethoric solution, with phone book elements to fit every condition on earth, neither to define any kind of phone book update or transfer protocol. 4. Rationale for XML Usage XML is rapidly becoming a standard format for data exchange between different applications also taking into account the transfer and access of data over the web. XML is used as syntax for expressing the structure and content of a roaming phone book to enable widespread usage and access to many different kind of media (e.g. paper, CDROM, www) using a widespread selection of access devices. Furthermore XML enables: - Extensibility - Flexibility - Integration with directories Extensibility is important because phone books are living documents; as such, it is unlikely that all the semantic requirements of arbitrary Internet service providers (ISPs) would be met by a fixed scheme, no matter how well thought out. Phone book designers must be free to create new attributes in a well-understood fashion to meet changing business needs. Flexibility is required of the attribute definition syntax for many of the same reasons that semantic extensibility is necessary. If we assume that phone book designers may need to define elements of arbitrary type, the syntax chosen must be able to represent these data objects cleanly. Using XML for describing the data content of the phone book fits this bill nicely, since it can be used to unambiguously describe virtually any data type. Integration with directories: although it is unlikely that phone books will be stored in the directory due to performance considerations, the creation of a XML DTD describing phone book content leaves that option open, with relatively little incremental effort required to implement it. 5. Specification of Requirements In this document, the key words "MAY", "MUST, "MUST NOT", "optional", "recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as described in [1]. Riegel, Zorn Expires April 2000 [Page 3] Internet-Draft Phone Book XML DTD October 1999 6. Value type notations for 'stronger' typing XML currently does not have capabilities for 'strong typing' of the content of elements. The only type definition foreseen in the base specification is "#PCDATA", 'parsable character data'. This might be sufficient and is used throughout this document to define elements containing information mainly aimed for interpretation by human beings. To enable a more concise description of the content of particular elements several value type notations are introduced. This allows for a more detailed type description of the content of elements in cases where it seems to be desirable. 7. Container Element Definitions 7.1. PhoneBook The phoneBook element is the basic container for phone book entries. It has two attributes, a phone book name and a phone book version number (applying to the phone book as a whole), and always contains one or more pop elements. A phoneBook element may also contain multiple Setup, Support and Provider elements, if they are referenced to by more than one pop element. Riegel, Zorn Expires April 2000 [Page 4] Internet-Draft Phone Book XML DTD October 1999 phoneBook +-----------------------------------+ | phoneBookName (req)| | phoneBookVersion (req)| | +-----------------------+ | | | pop |+ (req)| | +-----------------------+| | | + - - - - - - - - - - - + | | | | + - - - - - - - - - - - + | | | setup |+ (opt)| | + - - - - - - - - - - - +| | | + - - - - - - - - - - - + | | | | + - - - - - - - - - - - + | | | support |+ (opt)| | + - - - - - - - - - - - +| | | + - - - - - - - - - - - + | | | | + - - - - - - - - - - - + | | | provider |+ (opt)| | + - - - - - - - - - - - +| | | + - - - - - - - - - - - + | +-----------------------------------+ Syntax: 7.1.1. phoneBook Attribute "name" The phoneBook attribute "name" is an arbitrary string assigned as an identifier for a phone book. 7.1.2. phoneBook Attribute "version" The phoneBookVersion attribute is an integer representing the version of the phone book; it is a monotonically increasing counter which should be incremented each time the phone book is modified. This element can be used by a server to help decide what (if any) actions are required to bring a client's phone book up to date. For Riegel, Zorn Expires April 2000 [Page 5] Internet-Draft Phone Book XML DTD October 1999 example, the client can, at connect time, send an update request to the server including in the request the version number of its current phone book. If the client's phone book version is not the same as the server's current phone book version, the server can easily take appropriate action, e.g., reply with a URL pointing to a file containing the differences between the client and server phone books. 7.2. POP The pop element contains information elements relevant to individual network points of presence (POPs). The required information elements are addrFamily, address, media and entryVersion. The media element represents the media types supported by the POP, while the entryVersion element is a monotonically-increasing integer which should be incremented whenever the object is modified. POP +-----------------------------------+ | entryVersion (req)| | +-------------------------+ | | | address | (req)| | +-------------------------+ | | media (req)| | minBitsPerSecond (opt)| | maxBitsPerSecond (opt)| | "popProperties" (opt)| | "tunnelingProtocols" (opt)| | "unicastRoutingProtocols" (opt)| | "multicastRoutingProtocols" (opt)| | dialScript (opt)| | pricingInformation (opt)| | + - - - - - - - - - - - - + | | | "location" | (opt)| | + - - - - - - - - - - - - + | | + - - - - - - - - - - - - + | | | "popSetup" | (opt)| | + - - - - - - - - - - - - + | | + - - - - - - - - - - - - + | | | "popSupport" | (opt)| | + - - - - - - - - - - - - + | | + - - - - - - - - - - - - + | | | "popProvider" | (opt)| | + - - - - - - - - - - - - + | +-----------------------------------+ Riegel, Zorn Expires April 2000 [Page 6] Internet-Draft Phone Book XML DTD October 1999 Syntax: 7.3. Setup The Setup element includes information elements which describe services which may change from provider to provider or even from POP to POP. Some of the values contained in these information elements may be available by other means (e.g., DHCP), but others may not. Syntax: Riegel, Zorn Expires April 2000 [Page 7] Internet-Draft Phone Book XML DTD October 1999 7.4. Support The Support element includes those information elements that are pertinent to the provision of customer support for a POP or provider. Languages spoken by the staff at the support center might be specified by multiple entries for the attribute value language. Syntax: 7.5. Provider The Provider element contains information elements pertaining to the general business operations of a given network service provider. The information elements include such things as telephone number, mailing address, etc., as well as URLs for e-mail and a World Wide Web site. A Provider element may also contain a reference to support information. Syntax: Riegel, Zorn Expires April 2000 [Page 8] Internet-Draft Phone Book XML DTD October 1999 8. Information Element Definitions 8.1. Information elements defined for the POP element 8.1.1. pop Attribute "entryVersion" The entryVersion attribute is an integer representing the version of the POP object; it is a monotonically increasing counter which should be incremented each time the object is modified. This attribute may be useful in merging and updating phone books. 8.1.2. Address The address element provides the information representing the address of the POP. For POPs offering dial-up network access, the address element will at least contain an IA5 string representing a telephone number, formatted in standard fashion [4] (e.g. "+ 1 234 5678"). More detailed information may be available by optional attribute values. Syntax: 8.1.2.1. address Attribute "family" The attribute family of the element address defines the address family to which the element value belongs. For POPs offering dial-up network access, the addrFamily attribute will generally contain a value for a telephone network based address family. Currently the following attribute values are defined. Additional values may be registered by IANA in future. Value Description ------ -------------------------------------- E164 E.164 (PSTN, SMDS, Frame Relay, ATM) X121 X.121 (X.25, Frame Relay) Syntax: Riegel, Zorn Expires April 2000 [Page 9] Internet-Draft Phone Book XML DTD October 1999 8.1.2.2. address Attribute "encodingType" The encodingType attribute is a value representing the type of encoding used within a specific address family. The value "0" is reserved and represents the native encoding. Syntax: 8.1.2.3. address Attribute "countryCode" The countryCode attribute indicates the international dialing prefix for the country in which the POP is located. Syntax: 8.1.2.4. address Attribute "areaCode" The areaCode attribute contains the area or city code component of the telephone number in the 'address' element (if any) associated with this POP. 8.1.3. Media The media element is a container describing the types of media and related protocols supported by this POP. Protocols are specified for modem and ISDN. The following attribute values are currently defined. Additional values may be registered by IANA in future. Value Type Riegel, Zorn Expires April 2000 [Page 10] Internet-Draft Phone Book XML DTD October 1999 ----- ----------- MODEM Modem ISDN ISDN ATM ATM FR Frame Relay X25 X.25 SMDS SMDS Syntax: 8.1.3.1. Modem Protocols The mProto element is an empty container only representing by its type attribute a modem protocol supported by the access devices that can be reached at address. To define multiple available protocols this element might be included repeatedly. The initially defined modem protocol types are listed in the table below. Additional values may be registered by IANA in future. Value Duplex Speed Protocol ----- ------ ----- ------------- V21 Full 300 ITU-T V.21 V22 Full 1200 ITU-T V.22 V29 Half 9600 ITU-T V.29 V32 Full 9600 ITU-T V.32 V32B Full 14.4k ITU-T V.32bis V34 Full 28.8k ITU-T V.34 V34B Full 33.6k ITU-T V.34bis V90 Full 56k ITU-T V.90 Syntax 8.1.3.2. ISDN Protocols The iProto element is an empty container only representing by its type attribute a ISDN protocol supported by the access devices that Riegel, Zorn Expires April 2000 [Page 11] Internet-Draft Phone Book XML DTD October 1999 can be reached at address. To define multiple available protocols this element might be included repeatedly. The initially defined ISDN protocol types are listed in the table below. Additional values may be registered by IANA in future. Value Speed Meaning ----- ----- ----------- V110L 19.2k ITU-T V.110 V110H 38.4k ITU-T V.110 V120L 56k ITU-T V.120 V120H 64k ITU-T V.120 X75 64k ITU-T X.75 PPP 64k RFC 1618 Syntax: 8.1.4. Minimum Data Rate The minBitsPerSecond element indicates the minimum data rate (in bits/second) supported by the access devices at the POP. Syntax: 8.1.5. Maximum Data Rate The maxBitsPerSecond element indicates the maximum data rate (in bits/second) supported by the access devices at the POP. Syntax: 8.1.6. POP Properties The popProperty element is an empty element representing by its attribute value a particular property of this POP. To define multiple available protocols this element might be included several times. The initially defined properties are listed in the table below. Riegel, Zorn Expires April 2000 [Page 12] Internet-Draft Phone Book XML DTD October 1999 Additional values may be registered by IANA in future. Value Property ------ ---------------------- MPPP Multilink MOBIP Mobile IP MCRX Multicast Reception MCTX Multicast Transmission Syntax: 8.1.7. Tunneling Protocols The tunnelProto element is an empty element representing by its attribute a tunneling protocol supported by this POP. To define multiple available protocols this element might be included several times. The initially defined values are listed in the table below. Additional values may be registered by IANA in future. Value Protocol ------ ------------------ PPTP PPTP L2F L2F L2TP L2TP ATMP ATMP VTP VTP AHT IP AH Tunnel Mode IPIP IP-IP MIP Minimal IP-IP ESPT IP ESP Tunnel Mode GRE GRE BDVS Bay DVS Syntax: Riegel, Zorn Expires April 2000 [Page 13] Internet-Draft Phone Book XML DTD October 1999 8.1.8. Unicast Routing Protocols The unicastRtg element is an empty element representing by its attribute value a unicast routing protocol supported by this POP. To define multiple available protocols this element might be included several times. The initially defined values are listed in the table below. Additional values may be registered by IANA in future. Value Protocol ------ -------- STAT Static RIP1 RIP v1 RIP2 RIP v2 OSPF OSPF ISIS IS-IS IGRP IGRP EIGRP EIGRP BGP BGP Syntax: 8.1.9. Multicast Routing Protocols The multicastRtg element is an empty element representing by its attribute value a multicast routing protocol supported by this POP. To define multiple available protocols this element might be included several times. The initially defined values are listed in the table below. Additional values may be registered by IANA in future. Value Protocol ------ ---------- STAT Static DVMRP DVMRP SMPIM SM-PIM DMPIM DM-PIM CTB1 CBT v1 CTB2 CBT v2 BGMP BGMP PIGMP Proxy IGMP Riegel, Zorn Expires April 2000 [Page 14] Internet-Draft Phone Book XML DTD October 1999 Syntax: 8.1.10. Dialing Script The dialScript element contains the dialing script to be used when connecting to this POP. The attribute value type of dialScript defines the type of the script that should be used when connecting to this POP. Syntax: 8.1.11. Pricing Information The pricingInformation element is a free-form string representing pricing information for this POP. It may be anything from a simple string indicating relative expense (e.g., "$$$$" for a very expensive POP) to a paragraph describing time-of-day and other differential pricing variables. Syntax: 8.1.12. City The city element contains the name of the city in which the POP is located (not the city(s) from which it is accessible by a local call). Syntax: Riegel, Zorn Expires April 2000 [Page 15] Internet-Draft Phone Book XML DTD October 1999 8.1.13. Region The region element contains the name of the region in which the POP is located. In the United States, this would be the name of a state or (for Washington, D.C.) administrative district. In other countries, it might be the name of a province, parish or county. Syntax: 8.1.14. Country The country element contains the name of the country in which the POP is located. The country name may be abbreviated (e.g., "USA" for the United States of America or "UK" for the United Kingdom) but if abbreviations are used the usage must be consistent within a given phone book. Syntax: 8.1.15. POP Setup The popSetup element is either a setup element, if setup is specific to this particular POP, or a reference to any of the setup elements given in the outer scope of the phonebook element. Syntax: 8.1.16. POP Support The popSupport element is either a support element, if support is specific to this particular POP, or a reference to any of the support elements given in the outer scope of the phonebook element. Syntax: 8.1.17. POP Provider The popProvider element is either a provider element, if provider information is specific to this particular POP, or a reference to any of the provider elements given in the outer scope of the phonebook element. Syntax: 8.2. Information elements defined for the Setup element 8.2.1. DNS Server Address The dnsServerAddress element represents the IP address of the Domain Name Service (DNS) server which should be used when connected to this POP. The address is represented in the form of a string in dotted-decimal notation (e.g., 192.168.101.1). Syntax: 8.2.2. NNTP Server Name The nntpServerName element contains the fully qualified domain name (FQDN) of the Network News Transfer Protocol (NNTP) server which should be used when connected to this POP. Syntax: Riegel, Zorn Expires April 2000 [Page 17] Internet-Draft Phone Book XML DTD October 1999 8.2.3. SMTP Server Name The smtpServerName element contains the FQDN of the Simple Mail Transfer Protocol (SMTP) server which should be used when connected to this POP. Syntax: 8.2.4. POP3 Server Name The popServerName element contains the FQDN of the Post Office Protocol (POP) server which should be used when connected to this POP. Syntax: 8.2.5. IMAP Server Name The imapServerName element contains the FQDN of the Internet Mail Access Protocol (IMAP) server which should be used when connected to this POP. Syntax: 8.2.6. WWW Proxy The wwwProxyServerName element contains the FQDN of the World Wide Web (WWW) proxy server which should be used when connected to this POP. Syntax: Riegel, Zorn Expires April 2000 [Page 18] Internet-Draft Phone Book XML DTD October 1999 8.2.7. FTP Proxy The ftpProxyServerName element contains the FQDN of the File Transfer Protocol (FTP) proxy server which should be used when connected to this POP. Syntax: 8.2.8. Winsock Proxy The winsockProxyServerName element contains the FQDN of the Windows Socket (Winsock) proxy server which should be used when connected to this POP. Syntax: 8.2.9. Default Gateway Address The defaulttGatewayAddress element represents the address of the default gateway which should be used when connected to this POP. The address is represented in the form of a string in dotted-decimal notation (e.g., 192.168.101.1). Syntax: 8.2.10. User Name Suffix The userNameSuffix element represents a string which should be concatenated to the base username. For example, if the base username Riegel, Zorn Expires April 2000 [Page 19] Internet-Draft Phone Book XML DTD October 1999 is "userA" and the value of this element is "@bigco.com", the resulting augmented username would be "userA@bigco.com". An intelligent dialer may concatenate the string automatically. Note that both the userNameSuffix and the userNamePrefix (below) may be applied to the same base username. Syntax: 8.2.11. User Name Prefix The userNamePrefix element represents a string to which the base username should be concatenated. For example, if the base username is "userB" and the value of this element is "BIGCO/" the resulting augmented username would be "BIGCO/userB". An intelligent dialer may perform the concatenation automatically. Note that both the userNameSuffix (above) and the userNamePrefix may be applied to the same base username. Syntax: 8.3. Information elements defined for the support element 8.3.1. Support Telephone Number The supportTelephoneNumber element contains a number that may be called to reach the support center for a particular provider or POP. This element is basically a string and should contain the entire telephone number in international form, e.g., "+1 425 838 8080". Syntax: 8.3.2. Support Email Address The supportMailtoURL element contains a URL for the provider's customer support email address, e.g. mailto:support@uu.net. This URL could be used to contact customer support personnel regarding non-urgent issues. Riegel, Zorn Expires April 2000 [Page 20] Internet-Draft Phone Book XML DTD October 1999 Syntax: 8.4. Information elements defined for the provider element 8.4.1. Provider Name The providerName element is a string containing the name of the provider (e.g., "BIGNET Corporation"). Syntax: 8.4.2. Provider Icon The providerIcon attribute contains a BASE64 encoded JPEG or GIF image which may be used for 'branding' phone book entries or displayed when dialing. Syntax: 8.4.3. Provider's World Wide Web URL The wwwURL element contains a Uniform Resource Locator (URL) for the provider's Web site, for example, http://www.uu.net. Syntax: 8.4.4. Provider's Main Email Address The generalMailtoURL element contains a URL for the provider's main email address, for example, mailto:contact@uu.net. This URL could be used for general correspondence, complaints, etc. Riegel, Zorn Expires April 2000 [Page 21] Internet-Draft Phone Book XML DTD October 1999 Syntax: 8.4.5. Billing Inquiry Email Address The billingMailtoURL element contains a URL for the provider's billing support email address, for example, mailto:billing@uu.net. This URL could be used to for correspondence regarding billing and payment issues. Syntax: 8.4.6. Further elements The remainder of the information elements of the provider element are described in [3]. 9. Complete XML DTD for the roaming phone book Riegel, Zorn Expires April 2000 [Page 22] Internet-Draft Phone Book XML DTD October 1999 Riegel, Zorn Expires April 2000 [Page 26] Internet-Draft Phone Book XML DTD October 1999 Riegel, Zorn Expires April 2000 [Page 27] Internet-Draft Phone Book XML DTD October 1999 10. Security Considerations In the current revision there are no security specific elements provided within the phone book XML DTD. Security has to be provided outside of the scope of the phone book. Security specific items, like a signature for authentication the content of the phone book, may be added in a later revision, if standards are available for generating digital signatures in XML. 11. IANA Considerations The specification of the roaming phone book provides the possibility to define further attribute values for several information elements by extending the according parameter entity declaration. Separation of the entity declaration part of the phone book DTD, storing it as separate file on the Internet and referencing the URI of it by an external entity declaration in the beginning of the DTD specification allows to hand over the maintenance of the parameter declaration part of the roaming phone book to IANA. 12. References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 [2] Reynolds, J. and Postel, J., "ASSIGNED NUMBERS", STD 2, RFC 1700, October 1994 [3] Barker, P. and Kille, S., "The COSINE and Internet X.500 Schema", RFC 1274, November 1991 [4] ITU Rec. E.123, "Notation for national and international telephone numbers", 1988 [5] "Extensible Markup Language (XML) 1.0" W3C Recommendation 10-February-1998 http://www.w3org.org/TR/1998/REC-xml-19980210 Riegel, Zorn Expires April 2000 [Page 28] Internet-Draft Phone Book XML DTD October 1999 13. Appendix: Examples 13.1. The most simple example
+1 234 5678901
 13.2. A more comprehensive example
+49913130540
192.168.147.5 193.175.24.33 mailto:support@franken.de +499123968066 14. Acknowledgements Thanks to Bernard Aboba (aboba@internaut.com), Jay Farhat (jfarhat@ipass.com), Butch Anton (butch@ipass.com), Quentin Miller (quentinm@microsoft.com), and Ken Crocker (kcrocker@microsoft.com) for salient input and review. Riegel, Zorn Expires April 2000 [Page 29] Internet-Draft Phone Book XML DTD October 1999 15. Author's Addresses Questions about this memo can be directed to: Max Riegel Siemens AG Hofmannstr. 51 Munich, 81359 Germany Phone: +49 89 722 49557 E-Mail: maximilian.riegel@icn.siemens.de Glen Zorn Microsoft Corporation One Microsoft Way Redmond, Washington 98052 Phone: +1 425 703 1559 E-Mail: glennz@microsoft.com 16. Expiration Date This memo is filed as draft-ietf-roamops-phonebook-xml-02.txt and expires on April 23, 2000. Riegel, Zorn Expires April 2000 [Page 30]