RFC 3017
XML DTD for Roaming Access Phone Book
RFC 3017: XML DTD for Roaming Access Phone Book 💖
Okay bestie, this one is a Standards Track spec, so it's an official Internet protocol that people are meant to actually implement 🫶 It was written in December 2000 by M. Riegel from Siemens AG and G. Zorn from Cisco Systems. It doesn't obsolete or update any other RFC, since the title block doesn't list any. 🎀
Status of This Memo 🌸
This doc is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements. If you want to know where this protocol sits in standardization, check the current edition of the "Internet Official Protocol Standards" (STD 1). And yeah, you're free to distribute this memo as much as you want. Unlimited, baby! 🦋
Copyright Notice ⭐
Copyright (C) The Internet Society (2000). All Rights Reserved. 💜
Abstract ✨
So this doc is basically the rulebook for a phone book for roaming apps 📖 It defines both the syntax and the semantics of the info that goes in there. That info is what you need to pick the best ISP and set up your device so it can get onto that provider's network. 🌈
There's a small set of info that's required, plus a bunch of optional extras. Everything is written in XML [5] (Extensible Markup Language) syntax, which leads to a tidy little XML DTD (Document Type Declaration) for the phone book. It's giving clean and organized 💅
Table of Contents 🧚
1. Introduction ............................................. 3
2. Rationale for XML Usage .................................. 4
3. Specification of Requirements ............................ 5
4. Value type notations for 'stronger' typing ............... 5
5. Container Element Definitions ............................ 5
5.1. PhoneBook ............................................ 5
5.1.1. phoneBook Attribute "name" ........................ 6
5.1.2. phoneBook Attribute "version" ..................... 6
5.2. POP .................................................. 7
5.2.1. pop Attribute "entryVersion" ...................... 8
5.3. Setup ................................................ 8
5.4. Support .............................................. 9
5.5. Provider ............................................. 9
6. Information Element Definitions .......................... 10
6.1. Information elements defined for the POP element ..... 10
6.1.1. Address ........................................... 10
6.1.1.1. address Attribute "family" ..................... 10
6.1.1.2. address Attribute "countryCode" ................ 11
6.1.1.3. address Attribute "areaCode" ................... 11
6.1.2. Media ............................................. 11
6.1.2.1. Modem Protocols ................................ 12
6.1.2.2. ISDN Protocols ................................. 12
6.1.2.3. ATM Protocols .................................. 13
6.1.2.4. Frame Relay Protocols .......................... 13
6.1.2.5. X.25 Protocols ................................. 13
6.1.3. Minimum Data Rate ................................. 14
6.1.4. Maximum Data Rate ................................. 14
6.1.5. POP Properties .................................... 14
6.1.6. Tunneling Protocols ............................... 15
6.1.7. Dialing Script .................................... 15
6.1.8. Pricing Information ............................... 16
6.1.9. City .............................................. 16
6.1.10. Region ........................................... 16
6.1.11. Country .......................................... 16
6.1.12. POP Setup ........................................ 17
6.1.13. POP Support ...................................... 17
6.1.14. POP Provider ..................................... 17
6.2. Information elements defined for the Setup element ... 17
6.2.1. DNS Server Address ................................ 17
6.2.2. NNTP Server Name .................................. 18
6.2.3. SMTP Server Name .................................. 18
6.2.4. POP3 Server Name .................................. 18
6.2.5. IMAP Server Name .................................. 18
6.2.6. WWW Proxy ......................................... 19
6.2.7. FTP Proxy ......................................... 19
6.2.8. Winsock Proxy ..................................... 19
6.2.9. Default Gateway Address ........................... 19
6.2.10. User Name Suffix ................................. 20
6.2.11. User Name Prefix ................................. 20
6.3. Information elements defined for the support element.. 20
6.3.1. Support Telephone Number .......................... 20
6.3.2. Support Email Address ............................. 21
6.4. Information elements defined for the provider element. 21
6.4.1. Provider Name ..................................... 21
6.4.2. Provider Icon ..................................... 21
6.4.3. Provider's World Wide Web URL ..................... 21
6.4.4. Provider's Main Email Address ..................... 22
6.4.5. Billing Inquiry Email Address ..................... 22
6.4.6. Further elements .................................. 22
7. Complete XML DTD for the roaming phone book .............. 22
8. Security Considerations .................................. 28
9. IANA Considerations ...................................... 28
9.1. Registration of new attribute values ................. 29
9.2. Registration of new information elements ............. 29
10. References .............................................. 30
11. Appendix: Examples ...................................... 31
11.1. The most simple example ............................. 31
11.2. A more comprehensive example ........................ 31
12. Acknowledgments ......................................... 31
13. Authors' Addresses ...................................... 32
14. Full Copyright Statement ................................ 331. Introduction ✨
Okay so picture this: roaming apps rely on getting info about the services that are offered, plus instructions for how to connect to the network. That info flows from the roaming consortium to the individual users. It also flows from the operators of the network access servers (usually members of the roaming consortium themselves) and from the consortium too. It's a whole web of info, bestie 🕸️
"phone book"
+------+ +--+
| | | ++
| ISP1 | -- | | --+
| | +---+ \ "phone book"
+------+ \ +------+
+------+ +--+ \_ | | +--+ +------+
| | | ++ | | | ++ | |
| ISP2 | -- | | -->>--- | | --- | | ->> | USER |
| | +---+ _ | | +---+ | |
+------+ / | | +------+
+------+ +--+ / +------+
| | | ++ / Roaming
| ISP# | -- | | --+ Consortium
| | +---+
+------+So here's the deal: every provider in the consortium contributes their own piece, and the consortium puts them together into one unified phone book that customers can use 📚 Different groups of users probably end up with different versions of the book that fit what they need. Even the users themselves might pull out subsets for specific apps from what the consortium sends over. Like, grabbing only the entries for one country, or pulling out every access point that does wireless. Iconic behavior 🙈
That's why the doc wants a highly portable and well formed structure, so the phone book is easy to generate and post-process. 🧚 The goals are:
- Creating a flexible, extensible and robust framework upon which to build a standard phone book 🏗️
- Promoting a standard phone book format, so ISPs and roaming consortia interoperate better, and so a wide variety of devices can automatically pull out configuration data 🔌
- Defining a compact structure with the essential info for the roaming user, so it's easy to store and update, even on small devices 📱
Not gonna lie, the doc is pretty clear that it's not trying to be a plethoric solution with phone book elements for every condition on earth 🙅♀️ And it isn't defining any kind of phone book update or transfer protocol either. Just the structure. Simple and sweet 🍓
2. Rationale for XML Usage 💅
Ngl, XML is basically the standard format for swapping data between different apps, including data moving over the web 🌐 It's used here to express the structure and content of a roaming phone book, so the book can be published on lots of media (paper, CDROM, the WWW) and read by a bunch of different access devices. Super accessible, no cap ✨
XML brings three big things to the table:
- Extensibility 🌱
- Flexibility 🦋
- Integration with directories 📂
Extensibility matters because phone books are living documents 📖 Honestly it's unlikely that a fixed scheme would cover every semantic need of every ISP, no matter how well thought out it is. So phone book designers need to be able to add new attributes in a well-understood way, to keep up with changing business needs. Main character energy for the designers 👑
Flexibility is needed in the attribute definition syntax for many of the same reasons. If designers might need to define elements of arbitrary type, the syntax has to represent those data objects cleanly. XML can unambiguously describe pretty much any data type, so it fits this bill perfectly 💖
Integration with directories is the last one. It's unlikely that phone books will live in a directory because of performance concerns. BUT the XML DTD describing the phone book content keeps that option open, and implementing it takes relatively little extra effort. Iykyk 🙃
3. Specification of Requirements 🎀
Here's the key-word situation: in this document, the key words MAY, MUST, MUST NOT, optional, recommended, SHOULD, and SHOULD NOT are to be interpreted as described in [1]. The lowercase "optional" and "recommended" are just regular words, and the capitalized ones carry their formal meaning from [1]. Be careful out there 🫶
4. Value type notations for 'stronger' typing 🔥
Okay so XML DTDs can't do "strong typing" of element content right now 😭 The only type the base spec has is "#PCDATA" (parsable character data). That's honestly enough for a lot of stuff, and this doc uses it all over the place for elements that are mostly meant for humans to read.
But sometimes you want a more detailed description of what goes inside an element, so the doc introduces a few value type notations. That lets you describe the content more precisely wherever it's worth it. Lowkey genius 🧠✨
<?xml version="1.0" encoding="UTF-8"?>
<!-- Phone book value type notation declarations -->
<!NOTATION FQDN PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Fully_qualified_domain_name">
<!NOTATION IPADR PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type IP_address">
<!NOTATION B64JPG PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Base64_encoded_jpeg_image">
<!NOTATION B64GIF PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Base64_encoded_gif_image">5. Container Element Definitions ✨
5.1. PhoneBook
okay so the phoneBook element is the main container 💖 for all your phone book entries. It has two attributes: a phone book name and a phone book version number. The version number covers the whole phone book 🎀. It always holds one or more pop elements 💅. It can also hold multiple Setup, Support and Provider elements, but only if more than one pop element is pointing at them 🦋.
Syntax:
<!ELEMENT phoneBook (
pop+,
setup*,
support*,
provider*)>
<!ATTLIST phoneBook
name CDATA #REQUIRED
version CDATA #REQUIRED >
phoneBook
+-----------------------------------+
| phoneBookName (req)|
| phoneBookVersion (req)|
| +-----------------------+ |
| | pop |+ (req)|
| +-----------------------+| |
| + - - - - - - - - - - - + |
| |
| + - - - - - - - - - - - + |
| | setup |+ (opt)|
| + - - - - - - - - - - - +| |
| + - - - - - - - - - - - + |
| |
| + - - - - - - - - - - - + |
| | support |+ (opt)|
| + - - - - - - - - - - - +| |
| + - - - - - - - - - - - + |
| |
| + - - - - - - - - - - - + |
| | provider |+ (opt)|
| + - - - - - - - - - - - +| |
| + - - - - - - - - - - - + |
+-----------------------------------+5.1.1. phoneBook Attribute "name"
the name attribute is basically any string you want 🧚. It works as the identifier for the phone book.
5.1.2. phoneBook Attribute "version"
the phoneBookVersion attribute is an integer that tracks the version of the phone book. It's a monotonically increasing counter, and it should be incremented every time the phone book gets modified 🌸. This is what a server can use to figure out what (if anything) it needs to do to bring a client's phone book up to date ✨. For example, at connect time the client can send an update request to the server that includes the version number of its current phone book. If the client's version isn't the same as the server's current version, the server can easily take appropriate action, e.g., reply with a URL pointing to a file that has the differences between the client and server phone books 🙌.
5.2. POP
the pop element holds the info elements for each individual network point of presence (POP) 🌈. The required info elements are addrFamily, address, media and entryVersion. The media element lists the media types the POP supports. The entryVersion element is a monotonically-increasing integer that should be incremented whenever the object is modified 💜.
These are the info elements currently defined for the pop element. IANA may define more info elements in the future 🦋.
POP
+-----------------------------------+
| entryVersion (req)|
| +-------------------------+ |
| | address | (req)|
| +-------------------------+ |
| media (req)|
| minBitsPerSecond (opt)|
| maxBitsPerSecond (opt)|
| "popProperties" (opt)|
| "tunnelingProtocols" (opt)|
| dialScript (opt)|
| pricingInformation (opt)|
| + - - - - - - - - - - - - + |
| | "location" | (opt)|
| + - - - - - - - - - - - - + |
| + - - - - - - - - - - - - + |
| | "popSetup" | (opt)|
| + - - - - - - - - - - - - + |
| + - - - - - - - - - - - - + |
| | "popSupport" | (opt)|
| + - - - - - - - - - - - - + |
| + - - - - - - - - - - - - + |
| | "popProvider" | (opt)|
| + - - - - - - - - - - - - + |
+-----------------------------------+Syntax:
<!ENTITY % popInformation
"address,
media+,
minBitsPerSecond?,
maxBitsPerSecond?,
popProperty*,
tunnelProto*,
dialScript?,
pricingInformation?,
city?,
region?,
country?,
(setup | setupPtr)?,
(support | supportPtr)?,
(provider |providerPtr)?">
<!ELEMENT pop ( %popInformation; )>
<!ATTLIST pop
entryVersion CDATA #REQUIRED>5.2.1. pop Attribute "entryVersion"
the entryVersion attribute is an integer for the version of the POP object 💖. It's a monotonically increasing counter, and it should go up each time the object is modified. This attribute may come in handy when you're merging and updating phone books 🎀.
5.3. Setup
the Setup element packs in info elements describing services that can change from provider to provider, or even from POP to POP 🌸. Some of these values might be available by other means (e.g., DHCP), but others might not be ngl 🙈.
These are the info elements currently defined for the Setup element. IANA may define more in the future ✨.
Syntax:
<!ENTITY % setupInformation
"dnsServerAddress*,
nntpServerName*,
smtpServerName*,
popServerName*,
imapServerName*,
wwwProxyServerName*,
ftpProxyServerName*,
winsockProxyServerName*,
defaultGatewayAddress?,
userNamePrefix?,
userNameSuffix?">
<!ELEMENT setup ( %setupInformation; )>
<!ATTLIST setup
id ID #REQUIRED>5.4. Support
the Support element is for all the info about customer support for a POP or a provider 🫶. The languages the support staff speak can be listed with multiple entries for the language attribute value 🌈.
IANA may define more info elements for the Support element in the future 💅.
Syntax:
<!ENTITY % supportInformation
"(supportTelephoneNumber | supportMailtoURL)+">
<!ELEMENT support %supportInformation; >
<!ATTLIST support
id ID #REQUIRED
language NMTOKENS #IMPLIED >5.5. Provider
the Provider element is all about the general business side of a network service provider 💼✨. That includes stuff like telephone number and mailing address, plus URLs for e-mail and a World Wide Web site 🌐. A Provider element can also hold a reference to support info 🎀.
These are the info elements currently defined for the Provider element. IANA may define more in the future 🦋.
Syntax:
<!ENTITY % providerInformation
"providerName?,
providerIcon?,
wwwURL?,
generalMailtoURL?,
billingMailtoURL?,
businessCategory?,
x121Address?,
registeredAddress?,
destinationIndicator?,
preferredDeliveryMethod?,
telexNumber?,
teletexTerminalIdentifier?,
telephoneNumber?,
internationalISDNNumber?,
facsimileTelephoneNumber?,
street?,
postOfficeBox?,
postalCode?,
postalAddress?,
physicalDeliveryOfficeName?,
description?,
supportPtr*">
<!ELEMENT provider ( %providerInformation; )>
<!ATTLIST provider
id ID #REQUIRED>6. Information Element Definitions ✨
6.1. Information elements defined for the POP element
6.1.1. Address
the address element holds the info that represents the POP's address 📞. For POPs offering dial-up network access, the address element will at least contain an IA5 string for a telephone number, formatted in standard fashion [4] (e.g., "+ 1 234 5678") 💖. More detailed info might be available through optional attribute values 🌸.
Syntax:
<!-- A network address for this POP -->
<!ELEMENT address (#PCDATA)>6.1.1.1. address Attribute "family"
the family attribute of the address element tells you which address family the element value belongs to 🧚. For POPs offering dial-up network access, the addrFamily attribute will generally hold a value for a telephone network based address family 📱. These are the attribute values currently defined. IANA may register more values in the future 🦋.
Value Description
------ ------------------------------------------
E164 ITU-T E.164 (PSTN, SMDS, Frame Relay, ATM)
X121 ITU-T X.121 (X.25, Frame Relay)Syntax:
<!-- Attribute values for address family -->
<!ENTITY % addressFamily "(E164|X121)" >
<!ATTLIST address
family %addressFamily; #REQUIRED >6.1.1.2. address Attribute "countryCode"
the countryCode attribute shows the international dialing prefix for the country where the POP is located 🌍.
Syntax:
<!-- ITU dialing code for the country in which this POP is located -->
<!ATTLIST address
countryCode CDATA #IMPLIED >6.1.1.3. address Attribute "areaCode"
the areaCode attribute holds the area or city code part of the telephone number in the 'address' element (if there is one) linked to this POP 🏙️.
<!-- Area or city code component of the telephone number in the
accessTelephoneNumber element associated with this POP -->
<!ATTLIST address
areaCode CDATA #IMPLIED >6.1.2. Media
the media element is a container that describes the media types and related protocols this POP supports 📡. These are the media types currently defined. IANA may register more types in the future ✨.
Value Media Type
-------- -----------
viaMODEM Modem
viaISDN ISDN
viaATM ATM
viaFR Frame Relay
viaX25 X.25Syntax:
<!-- The types of media supported by this POP -->
<!ENTITY % mediaTypes "(viaMODEM|viaISDN|viaATM|viaFR|viaX25)+" >
<!ELEMENT media %mediaTypes; >6.1.2.1. Modem Protocols
the viaMODEM element is an empty element 🌙. Its optional type attribute says which modem protocol is supported by the access devices you can reach at the address. You can include this element more than once to define multiple available protocols 💜. The initially defined modem protocol types are in the table below. IANA may register more values in the 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.90Syntax
<!-- A modem media type element -->
<!ENTITY % modemProtocols "(V21|V22|V29|V32|V32B|V34|V34B|V90)" >
<!ELEMENT viaMODEM EMPTY>
<!ATTLIST viaMODEM
type %modemProtocols; #IMPLIED >6.1.2.2. ISDN Protocols ✨
okay so the viaISDN element is an empty element 💖 its optional type attribute says which ISDN protocol the access devices reachable at address support. you can include it more than once if there are several protocols to list 🎀 the first ISDN protocol types are in the table below, and IANA may register more later 🦋
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
HDLC 64k RFC 1618Syntax:
<!-- An ISDN media type element -->
<!ENTITY % isdnProtocols "(V110L|V110H|V120L|V120H|X75|HDLC)">
<!ELEMENT viaISDN EMPTY>
<!ATTLIST viaISDN
type %isdnProtocols; #IMPLIED >6.1.2.3. ATM Protocols 🌸
the viaATM element is also empty, and its optional type attribute names one protocol the access devices at address support 💅 you can repeat it to list several. right now there's only one protocol defined, and IANA may add more values later on 🧚
Syntax:
<!-- An ATM media type element -->
<!ENTITY % atmProtocols "(RFC2364)">
<!ELEMENT viaATM EMPTY>
<!ATTLIST viaATM
type %atmProtocols; #IMPLIED >6.1.2.4. Frame Relay Protocols 🍓
the viaFR element is an empty one as well, and its optional type attribute gives the particular protocol the access devices at address support 🫶 same deal as before: repeat it for more protocols. only one is defined so far, and IANA can register new values in future ✨
Syntax:
<!-- A Frame Relay media type element -->
<!ENTITY % frProtocols "(RFC1973)">
<!ELEMENT viaFR EMPTY>
<!ATTLIST viaFR
type %frProtocols; #IMPLIED >6.1.2.5. X.25 Protocols 🦋
the viaX25 element is empty too 💜 its optional type attribute is the particular protocol supported by the access devices reachable at address. include it repeatedly for multiple protocols. currently just one is defined, and IANA may register more down the line 👑
Syntax:
<!-- A X.25 media type element -->
<!ENTITY % x25Protocols "(RFC1598)">
<!ELEMENT viaX25 EMPTY>
<!ATTLIST viaX25
type %x25Protocols; #IMPLIED >6.1.3. Minimum Data Rate 🌈
the minBitsPerSecond element tells you the lowest data rate (in bits/second) the access devices at the POP support 📉 it's the floor, bestie 😭
Syntax:
<!-- Minimum data rate supported by this POP in bits/second -->
<!ELEMENT minBitsPerSecond (#PCDATA)>6.1.4. Maximum Data Rate 🔥
the maxBitsPerSecond element is the opposite: it gives the highest data rate (in bits/second) the access devices at the POP support 🚀 the ceiling, iykyk 💅
Syntax:
<!-- Maximum data rate supported by this POP in bits/second -->
<!ELEMENT maxBitsPerSecond (#PCDATA)>6.1.5. POP Properties 💖
the popProperty element is empty, and its attribute type names a particular property of this POP ✨ you can include it several times, and the first properties defined are in the table below. IANA may register more values later 🎀
Value Property
------ ----------------------
MPPP Multilink PPP (RFC 1990)
MOBIP Mobile IP (RFC 2002)
MCRX Multicast Reception
MCTX Multicast TransmissionSyntax:
<!-- A property characterizing this POP -->
<!ENTITY % popProperties "(MPPP|MOBIP|MCRX|MCTX)" >
<!ELEMENT popProperty EMPTY>
<!ATTLIST popProperty
type %popProperties; #REQUIRED>6.1.6. Tunneling Protocols 🧚
the tunnelProto element is empty and uses its type attribute to name a tunneling protocol this POP supports 🦋 repeat it for more than one. the initial values are in the table below, and IANA may add more later 💜
Value Protocol
------ ------------------
L2TP RFC 2661 L2TP
PPTP RFC 2637 PPTP
L2F RFC 2341 L2F
ATMP RFC 2107 ATMP
AHT RFC 2402 IP AH Tunnel Mode
ESPT RFC 2406 IP ESP Tunnel Mode
IPIP RFC 1853 IP-IP
MIP RFC 2004 Minimal IP-IP
GRE RFC 1701 GRESyntax:
<!-- A tunneling protocol supported by this POP -->
<!ENTITY % tunnelingProtocols
"(L2TP|PPTP|L2F|ATMP|AHT|ESPT|IPIP|MIP|GRE)" >
<!ELEMENT tunnelProto EMPTY>
<!ATTLIST tunnelProto
type %tunnelingProtocols; #REQUIRED>6.1.7. Dialing Script 📞
the dialScript element holds the dialing script you use when connecting to this POP 🎀 its type attribute says what kind of script it is 💅
Syntax:
<!-- The dial script to be used -->
<!ELEMENT dialScript (#PCDATA)>
<!ATTLIST dialScript
type CDATA #IMPLIED >6.1.8. Pricing Information 💸
the pricingInformation element is a free-form string about what this POP costs 🤑 it can be as simple as a vibe check like "$$$$" for a very expensive POP, or as long as a paragraph explaining time-of-day and other differential pricing stuff 🙈
Syntax:
<!-- Pricing information for this POP -->
<!ELEMENT pricing (#PCDATA)>6.1.9. City 🏙️
the city element has the name of the city where the POP is located 🌆 it is not the city (or cities) you can reach with a local call, so don't mix those up, bestie 💅
Syntax:
<!-- The name of the city in which this POP is located -->
<!ELEMENT city (#PCDATA)>6.1.10. Region 🗺️
the region element names the region where the POP is located 🌏 in the United States that's a state, or a district for Washington, D.C. in other countries it could be a province, parish or county 🍓
Syntax:
<!-- The name of the region in which this POP is located -->
<!ELEMENT region (#PCDATA)>6.1.11. Country 🌍
the country element has the name of the country where the POP is located 🫶 you can abbreviate it, like "USA" for the United States of America or "UK" for the United Kingdom, but if you do, you have to be consistent throughout a given phone book 📖
Syntax:
<!-- The name of the country in which this POP is located -->
<!ELEMENT country (#PCDATA)>6.1.12. POP Setup ⚙️
the popSetup element is either a setup element (if setup is specific to this POP) or a reference to any of the setup elements in the outer scope of the phonebook element 🧩
Syntax:
<!-- Reference for setup information for this POP -->
<!ELEMENT setupPtr EMPTY>
<!ATTLIST setupPtr
setupID IDREFS #IMPLIED>6.1.13. POP Support 🛟
the popSupport element is either a support element (if support is specific to this POP) or a reference to a support element from the outer scope of the phonebook element 🤝
Syntax:
<!-- Reference for support information for this POP -->
<!ELEMENT supportPtr EMPTY>
<!ATTLIST supportPtr
supportID IDREFS #IMPLIED>6.1.14. POP Provider 🏢
the popProvider element is either a provider element (if provider info is specific to this POP) or a reference to any provider element in the outer scope of the phonebook element 💼
Syntax:
<!-- Reference for provider information for this POP -->
<!ELEMENT providerPtr EMPTY>
<!ATTLIST providerPtr
providerID IDREFS #IMPLIED>6.2. Information elements defined for the Setup element 🌷
6.2.1. DNS Server Address 🌐
the dnsServerAddress element is the IP address of the Domain Name Service (DNS) server to use when connected to this POP 💖 the address is a string in dotted-decimal notation, like 192.168.101.1 ✨
Syntax:
<!-- Domain Name Server IP address -->
<!ELEMENT dnsServerAddress (#PCDATA)>
<!ATTLIST dnsServerAddress
value NOTATION (IPADR) #IMPLIED>6.2.2. NNTP Server Name 📰
the nntpServerName element has the fully qualified domain name (FQDN) of the Network News Transfer Protocol (NNTP) server to use when connected to this POP 🗞️
Syntax:
<!-- Name of an NNTP server -->
<!ELEMENT nntpServerName (#PCDATA)>
<!ATTLIST nntpServerName
value NOTATION (FQDN) #IMPLIED>6.2.3. SMTP Server Name 📨
the smtpServerName element is the FQDN of the Simple Mail Transfer Protocol (SMTP) server to use when connected to this POP 💌
Syntax:
<!-- Name of an SMTP mail server -->
<!ELEMENT smtpServerName (#PCDATA)>
<!ATTLIST smtpServerName
value NOTATION (FQDN) #IMPLIED>6.2.4. POP3 Server Name 📬
the popServerName element is the FQDN of the Post Office Protocol (POP) server to use when connected to this POP 💜
Syntax:
<!-- Name of an POP3 mail server -->
<!ELEMENT popServerName (#PCDATA)>
<!ATTLIST popServerName
value NOTATION (FQDN) #IMPLIED>6.2.5. IMAP Server Name 🪽
the imapServerName element has the FQDN of the Internet Mail Access Protocol (IMAP) server to use when connected to this POP 🦋
Syntax:
<!-- Name of an IMAP4 server -->
<!ELEMENT imapServerName (#PCDATA)>
<!ATTLIST imapServerName
value NOTATION (FQDN) #IMPLIED>6.2.6. WWW Proxy 🕸️
the wwwProxyServerName element is the FQDN of the World Wide Web (WWW) proxy server to use when connected to this POP 🌐
Syntax:
<!-- Name of an WWW Proxy -->
<!ELEMENT wwwProxyServerName (#PCDATA)>
<!ATTLIST wwwProxyServerName
value NOTATION (FQDN) #IMPLIED>6.2.7. FTP Proxy 📁
the ftpProxyServerName element has the FQDN of the File Transfer Protocol (FTP) proxy server to use when connected to this POP 🗂️
Syntax:
<!-- Name of an FTP Proxy -->
<!ELEMENT ftpProxyServerName (#PCDATA)>
<!ATTLIST ftpProxyServerName
value NOTATION (FQDN) #IMPLIED>6.2.8. Winsock Proxy 🪟
the winsockProxyServerName element is the FQDN of the Windows Socket (Winsock) proxy server to use when connected to this POP 💻
Syntax:
<!-- Name of an Winsock Proxy -->
<!ELEMENT winsockProxyServerName (#PCDATA)>
<!ATTLIST winsockProxyServerName
value NOTATION (FQDN) #IMPLIED>6.2.9. Default Gateway Address 🚪
the defaulttGatewayAddress element is the address of the default gateway to use when connected to this POP 🌸 it's a string in dotted-decimal notation, like 192.168.101.1 🫶
Syntax:
<!-- Default Gateway IP address (in dotted decimal notation) -->
<!ELEMENT defaultGatewayAddress (#PCDATA)>
<!ATTLIST defaultGatewayAddress
value NOTATION (IPADR) #IMPLIED>6.2.10. User Name Suffix 💖
okay so the userNameSuffix element is a string that gets stuck onto the END of the base username 🎀 for example, if the base username is "userA" and this element is "@bigco.com", the augmented username becomes "userA@bigco.com" ✨ an intelligent dialer can add it automatically for you 🧚 and btw the suffix AND the prefix (below) can both be applied to the same base username 💅
Syntax:
<!-- User Name suffix -->
<!ELEMENT userNameSuffix (#PCDATA)>6.2.11. User Name Prefix 🌸
the userNamePrefix element is the opposite vibe 🦋 it's a string that goes in FRONT of the base username 💜 so if the base username is "userB" and this element is "BIGCO/", the augmented username is "BIGCO/userB" 🍓 an intelligent dialer may do the concatenation automatically 🫶 and yep, the userNameSuffix (above) and the userNamePrefix can both be used on the same base username ✨
Syntax:
<!-- User Name prefix -->
<!ELEMENT userNamePrefix (#PCDATA)>6.3. Information elements defined for the support element 🎧
6.3.1. Support Telephone Number 📞
the supportTelephoneNumber element holds a number you can call to reach the support center for a provider or POP 💖 it's basically just a string, and it should hold the whole number in international form, like "+1 425 838 8080" 🌈
Syntax:
<!-- The number to be dialed to contact customer support
for this POP or provider -->
<!ELEMENT supportTelephoneNumber (#PCDATA)>6.3.2. Support Email Address 💌
the supportMailtoURL element holds a URL for the provider's customer support email address, like mailto:support@uu.net 🦋 this is the one you'd use to reach customer support about stuff that isn't urgent 🫶
Syntax:
<!-- A Uniform Resource Locator for the provider's customer
support email address -->
<!ELEMENT supportMailtoURL (#PCDATA)>6.4. Information elements defined for the provider element 🏢
6.4.1. Provider Name 🏷️
the providerName element is a string with the name of the provider, like "BIGNET Corporation" 👑
Syntax:
<!-- The name of the provider -->
<!ELEMENT providerName (#PCDATA)>6.4.2. Provider Icon 🖼️
the providerIcon attribute holds a BASE64 encoded JPEG or GIF image 🌸 it can be used for branding phone book entries, or shown when dialing 📱 it's giving main character energy 💅
Syntax:
<!-- An icon in BASE64 encoded JPEG or GIF format -->
<!ELEMENT providerIcon (#PCDATA)>
<!ATTLIST providerIcon
value NOTATION (B64JPG | B64GIF) #IMPLIED>6.4.3. Provider's World Wide Web URL 🌐
the wwwURL element holds a Uniform Resource Locator (URL) for the provider's website, like http://www.uu.net ✨
Syntax:
<!-- A Uniform Resource Locator for the provider's home page -->
<!ELEMENT wwwURL (#PCDATA)>6.4.4. Provider's Main Email Address 📧
the generalMailtoURL element holds a URL for the provider's main email address, like mailto:contact@uu.net 💜 it's for general correspondence, complaints, that kind of thing 🙈
Syntax:
<!-- A Uniform Resource Locator for the provider's
email address -->
<!ELEMENT generalMailtoURL (#PCDATA)>6.4.5. Billing Inquiry Email Address 💳
the billingMailtoURL element holds a URL for the provider's billing support email address, like mailto:billing@uu.net 🍓 it's for correspondence about billing and payment issues 💸
Syntax:
<!-- A Uniform Resource Locator for the email
address to be used for billing inquiries -->
<!ELEMENT billingMailtoURL (#PCDATA)>6.4.6. Further elements 🧚
the rest of the information elements of the provider element are described in principle in [3] 📚
7. Complete XML DTD for the roaming phone book 🎀
<?xml version="1.0" encoding="UTF-8"?>
<!-- Parameter entity declaration -->
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<!-- This section will be maintained by IANA and can be direct
referenced by the DTD specification by means of an external
parameter entity. -->
<!ENTITY % addressFamily "(E164|X121)" >
<!ENTITY % mediaTypes "(viaMODEM|viaISDN|viaATM|viaFR|viaX25)+" >
<!ENTITY % modemProtocols "(V21|V22|V29|V32|V32B|V34|V34B|V90)" >
<!ENTITY % isdnProtocols "(V110L|V110H|V120L|V120H|X75|HDLC)">
<!ENTITY % atmProtocols "(RFC2364)">
<!ENTITY % frProtocols "(RFC1973)">
<!ENTITY % x25Protocols "(RFC1598)">
<!ENTITY % popProperties "(MPPP|MOBIP|MCRX|MCTX)" >
<!ENTITY % tunnelingProtocols
"(L2TP|PPTP|L2F|ATMP|AHT|ESPT|IPIP|MIP|GRE)" >
<!ENTITY % popInformation
"address,
media+,
minBitsPerSecond?,
maxBitsPerSecond?,
popProperty*,
tunnelProto*,
dialScript?,
pricingInformation?,
city?,
region?,
country?,
(setup|setupPtr)?,
(support|supportPtr)?,
(provider|providerPtr)?">
<!ENTITY % setupInformation
"dnsServerAddress*,
nntpServerName*,
smtpServerName*,
popServerName*,
imapServerName*,
wwwProxyServerName*,
ftpProxyServerName*,
winsockProxyServerName*,
defaultGatewayAddress?,
userNamePrefix?,
userNameSuffix?">
<!ENTITY % supportInformation
"(supportTelephoneNumber|supportMailtoURL)+">
<!ENTITY % providerInformation
"providerName?,
providerIcon?,
wwwURL?,
generalMailtoURL?,
billingMailtoURL?,
businessCategory?,
x121Address?,
registeredAddress?,
destinationIndicator?,
preferredDeliveryMethod?,
telexNumber?,
teletexTerminalIdentifier?,
telephoneNumber?,
internationalISDNNumber?,
facsimileTelephoneNumber?,
street?,
postOfficeBox?,
postalCode?,
postalAddress?,
physicalDeliveryOfficeName?,
description?,
supportPtr*">
<!-- ++++++++++++++ End of IANA maintained section ++++++++++ -->
<!-- Phone book value type notation declarations -->
<!NOTATION FQDN PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Fully_qualified_domain_name">
<!NOTATION IPADR PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type IP_address">
<!NOTATION B64JPG PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Base64_encoded_jpeg_image">
<!NOTATION B64GIF PUBLIC "-//IETF/roamPhoneBook/NOTATION
value Type Base64_encoded_gif_image">
<!-- Phone book element declarations -->
<!ELEMENT phoneBook (
pop+,
setup*,
support*,
provider*) >
<!ATTLIST phoneBook
name CDATA #REQUIRED
version CDATA #REQUIRED >
<!ELEMENT pop ( %popInformation; )>
<!ATTLIST pop
entryVersion CDATA #REQUIRED>
<!ELEMENT setup ( %setupInformation; )>
<!ATTLIST setup
id ID #REQUIRED>
<!ELEMENT support ( %supportInformation; )>
<!ATTLIST support
id ID #REQUIRED
language NMTOKENS #IMPLIED >
<!ELEMENT provider ( %providerInformation; )>
<!ATTLIST provider
id ID #REQUIRED>
<!-- Information elements for pop -->
<!ELEMENT address (#PCDATA)>
<!ATTLIST address
family %addressFamily; #REQUIRED
countryCode CDATA #IMPLIED
areaCode CDATA #IMPLIED >
<!ELEMENT media %mediaTypes; >
<!ELEMENT viaMODEM EMPTY>
<!ATTLIST viaMODEM
type %modemProtocols; #IMPLIED >
<!ELEMENT viaISDN EMPTY>
<!ATTLIST viaISDN
type %isdnProtocols; #IMPLIED >
<!ELEMENT viaATM EMPTY>
<!ATTLIST viaATM
type %atmProtocols; #IMPLIED >
<!ELEMENT viaFR EMPTY>
<!ATTLIST viaFR
type %frProtocols; #IMPLIED >
<!ELEMENT viaX25 EMPTY>
<!ATTLIST viaX25
type %x25Protocols; #IMPLIED >
<!ELEMENT minBitsPerSecond (#PCDATA)>
<!ELEMENT maxBitsPerSecond (#PCDATA)>
<!ELEMENT popProperty EMPTY>
<!ATTLIST popProperty
type %popProperties; #REQUIRED >
<!ELEMENT tunnelProto EMPTY>
<!ATTLIST tunnelProto
type %tunnelingProtocols; #REQUIRED >
<!ELEMENT dialScript (#PCDATA)>
<!ATTLIST dialScript
type CDATA #IMPLIED >
<!ELEMENT pricing (#PCDATA)>
<!ELEMENT city (#PCDATA)>
<!ELEMENT region (#PCDATA)>
<!ELEMENT country (#PCDATA)>
<!ELEMENT setupPtr EMPTY>
<!ATTLIST setupPtr
setupID IDREFS #IMPLIED>
<!ELEMENT supportPtr EMPTY>
<!ATTLIST supportPtr
supportID IDREFS #IMPLIED>
<!ELEMENT providerPtr EMPTY>
<!ATTLIST providerPtr
providerID IDREFS #IMPLIED>
<!-- Information elements for setup -->
<!ELEMENT dnsServerAddress (#PCDATA)>
<!ATTLIST dnsServerAddress
value NOTATION (IPADR) #IMPLIED>
<!ELEMENT nntpServerName (#PCDATA)>
<!ATTLIST nntpServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT smtpServerName (#PCDATA)>
<!ATTLIST smtpServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT popServerName (#PCDATA)>
<!ATTLIST popServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT imapServerName (#PCDATA)>
<!ATTLIST imapServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT wwwProxyServerName (#PCDATA)>
<!ATTLIST wwwProxyServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT ftpProxyServerName (#PCDATA)>
<!ATTLIST ftpProxyServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT winsockProxyServerName (#PCDATA)>
<!ATTLIST winsockProxyServerName
value NOTATION (FQDN) #IMPLIED>
<!ELEMENT defaultGatewayAddress (#PCDATA)>
<!ATTLIST defaultGatewayAddress
value NOTATION (IPADR) #IMPLIED>
<!ELEMENT userNameSuffix (#PCDATA)>
<!ELEMENT userNamePrefix (#PCDATA)>
<!-- Information elements for support -->
<!ELEMENT supportTelephoneNumber (#PCDATA)>
<!ELEMENT supportMailtoURL (#PCDATA)>
<!-- Information elements for provider -->
<!ELEMENT providerName (#PCDATA)>
<!ELEMENT providerIcon (#PCDATA)>
<!ATTLIST providerIcon
value NOTATION (B64JPG|B64GIF) #IMPLIED>
<!ELEMENT wwwURL (#PCDATA)>
<!ELEMENT generalMailtoURL (#PCDATA)>
<!ELEMENT billingMailtoURL (#PCDATA)>
<!-- Further provider elements according to RFC1274 -->
<!ELEMENT businessCategory (#PCDATA)>
<!ELEMENT x121Address (#PCDATA)>
<!ELEMENT registeredAddress (#PCDATA)>
<!ELEMENT destinationIndicator (#PCDATA)>
<!ELEMENT preferredDeliveryMethod (#PCDATA)>
<!ELEMENT telexNumber (#PCDATA)>
<!ELEMENT teletexTerminalIdentifier (#PCDATA)>
<!ELEMENT telephoneNumber (#PCDATA)>
<!ELEMENT internationalISDNNumber (#PCDATA)>
<!ELEMENT facsimileTelephoneNumber (#PCDATA)>
<!ELEMENT street (#PCDATA)>
<!ELEMENT postOfficeBox (#PCDATA)>
<!ELEMENT postalCode (#PCDATA)>
<!ELEMENT postalAddress (#PCDATA)>
<!ELEMENT physicalDeliveryOfficeName (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!-- end of dtd -->8. Security Considerations 🔐
okay this part is SERIOUS bestie 😭 the secure distribution and transport of a phone book's information for roaming applications needs a reliable authentication of the issuer of the info, plus ways to preserve the integrity of what gets provided 🛡️ the phone book XML DTD doesn't provide any specific elements for security requirements by itself 💀 so it's assumed that security of the roaming phone book is handled by means outside the scope of this specification, such as signing the phone book using pgp 🔑 don't skip this one, it's the difference between a phone book you can trust and one that's cooked 🙈
9. IANA Considerations 🎀
okay so this section is about how the phone book can keep growing without breaking anyone 💅 the spec lets you define more attribute values for every enumerated attribute list, and it lets you add more information elements to the main structures pop, setup, support and provider. so the roaming phone book can keep up with future needs without this document ever needing a rewrite 🦋 new stuff gets added by registering it with IANA ✨
extending the spec with new attributes or elements must not change whether documents based on an older version of the XML DTD are valid. that's why every added information element has to be optional, so nobody can be forced to include something brand new 🫶 adding new values to enumerated attribute lists has no backward compatibility constraints, because it doesn't hurt the validity of attributes that already exist 🌸
to make registering new stuff easier, the DTD for the phone book is split into two parts 🧚 the extensible part only has parameter entity declarations, so adding new values is simple, and the fixed part has the detailed content and structure of the phone book. by referencing those parameter entity declarations from the fixed part, the whole phone book becomes extensible 🌈 IANA maintains the part with the parameter entity declarations, and there are two different classes of declarations in it that need different policies for registering new values 💜
9.1. Registration of new attribute values
the entities 'addressFamily', 'modemProtocols', 'isdnProtocols', 'atmProtocols', 'frProtocols', 'x25Protocols', 'popProperties' and 'tunnelingProtocols' describe enumerated attribute value lists ✨ there's no limit on the name space for these values, and newly defined attribute values can't harm the validity of existing ones, so new attribute values can be assigned by Specification Required [6] 💖
9.2. Registration of new information elements
the entities 'mediaTypes', 'popInformation', 'setupInformation', 'supportInformation' and 'providerInformation' define the information elements that are probably included in the media, pop, setup, support and provider elements 👑 adding new values to these lists extends the phone book with new information elements, but misusing the XML content model can destroy the backward compatibility of the DTD, so 🙈 the assignment of new information elements needs approval from a Designated Expert [6] 💀 on top of inserting the new value into the list, the detailed definition of the information element has to be appended to the specification part that IANA maintains 🍓
10. References 📚
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[2] Reynolds, J. and J. Postel, "ASSIGNED NUMBERS", STD 2, RFC 1700, October 1994.
[3] Barker, P. and S. Kille, "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.w3.org/TR/1998/REC-xml-19980210
[6] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
11. Appendix: Examples 🧁
11.1. The most simple example
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE phoneBook SYSTEM "roamPhoneBook.dtd">
<phoneBook name="minimalExample" version="1">
<pop entryVersion="1">
<address family="E164">+1 234 5678901</address>
<media><viaMODEM/></media>
</pop>
</phoneBook>11.2. A more comprehensive example
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE phoneBook SYSTEM "roamPhoneBook.dtd">
<phoneBook name="KNF_simple" version="1">
<pop entryVersion="1">
<address family="E164" countryCode="49">+49913130540</address>
<media>
<viaMODEM type="V90"/>
<viaMODEM type="V34B"/>
<viaISDN type="HDLC"/>
</media>
<setup>
<dnsServerAddress>192.168.147.5</dnsServerAddress>
<dnsServerAddress>193.175.24.33</dnsServerAddress>
</setup>
</pop>
<support id="KNF_main" language="EN DE">
<supportMailtoURL>mailto:support@franken.de</supportMailtoURL>
<supportTelephoneNumber>+499123968066</supportTelephoneNumber>
</support>
</phoneBook>12. Acknowledgments 🫶
thanks to Pat Calhoun, Bernard Aboba, Jay Farhat, Butch Anton, Quentin Miller, and Ken Crocker for the salient input and review 💖
13. Authors' Addresses 💌
questions about this memo can be directed to:
Max Riegel
Siemens AG
Hofmannstr. 51
Munich, 81359
Germany
Phone: +49 89 722 49557
EMail: maximilian.riegel@icn.siemens.deGlen Zorn
Cisco Systems, Inc.
500 108th Avenue N.E., Suite 500
Bellevue, WA 98004
USA
Phone: +1 425 438 8218
EMail: gwz@cisco.com14. Full Copyright Statement ⚖️
Copyright (C) The Internet Society (2000). All Rights Reserved. 🌸
this document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, as long as the above copyright notice and this paragraph are included on all such copies and derivative works 🦋 but this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations. the exceptions are when it's needed for developing Internet standards, in which case the copyright procedures defined in the Internet Standards process must be followed, or when it's needed to translate it into languages other than English 🌈
the limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns ✨
this document and the information in it are provided on an "AS IS" basis, and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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 💜
Acknowledgement
funding for the RFC Editor function is currently provided by the Internet Society 🎀
📦 where this page comes from
- ietf: rfc3017 2000-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms