Network Working Group M. Spencer Internet-Draft Digium, Inc. Expires: April 13, 2005 October 13, 2004 Distributed Universal Number Discovery (DUNDi) draft-mspencer-dundi-01 Status of this Memo This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft. 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 13, 2005. Abstract This memo describes the DUNDi protocol for resolving protocol and destination descriptions for locating Internet resources for contacting a phone number of any dialplan through a peer to peer, trusted system. This memo is Copyright (C) 2004, Digium, Inc. with the goal of eventually being presented to the IETF in accordance with Section 10 of RFC2026. Spencer Expires April 13, 2005 [Page 1] Internet-Draft DUNDi October 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 DUNDi Terminology . . . . . . . . . . . . . . . . . . . . 4 1.2 Applicability . . . . . . . . . . . . . . . . . . . . . . 5 1.3 Protocol Overview . . . . . . . . . . . . . . . . . . . . 5 2. Protocol Functioning . . . . . . . . . . . . . . . . . . . . 7 2.1 DUNDi Transactions . . . . . . . . . . . . . . . . . . . . 8 2.2 Retransmissions . . . . . . . . . . . . . . . . . . . . . 9 2.3 Registration . . . . . . . . . . . . . . . . . . . . . . . 9 2.4 Dialplan Discovery . . . . . . . . . . . . . . . . . . . . 9 2.5 EID Query . . . . . . . . . . . . . . . . . . . . . . . . 10 2.6 Example Transaction Flows . . . . . . . . . . . . . . . . 10 3. Packet Format and Forwarding . . . . . . . . . . . . . . . . 12 3.1 Protocol and Port Number . . . . . . . . . . . . . . . . . 12 3.2 Endpoint Identifiers . . . . . . . . . . . . . . . . . . . 12 3.3 Packet Format . . . . . . . . . . . . . . . . . . . . . . 12 4. DUNDi Commands and Responses . . . . . . . . . . . . . . . . 14 4.1 ACK Response . . . . . . . . . . . . . . . . . . . . . . . 15 4.2 DPDISCOVER Command . . . . . . . . . . . . . . . . . . . . 15 4.3 DPRESPONSE Response . . . . . . . . . . . . . . . . . . . 16 4.4 EIDQUERY Command . . . . . . . . . . . . . . . . . . . . . 17 4.5 EIDRESPONSE Response . . . . . . . . . . . . . . . . . . . 18 4.6 INVALID Response . . . . . . . . . . . . . . . . . . . . . 19 4.7 UNKNOWN Response . . . . . . . . . . . . . . . . . . . . . 20 4.8 NULL Command . . . . . . . . . . . . . . . . . . . . . . . 21 4.9 REGREQ Command . . . . . . . . . . . . . . . . . . . . . . 21 4.10 REGRESPONSE Response . . . . . . . . . . . . . . . . . . 22 4.11 CANCEL Command . . . . . . . . . . . . . . . . . . . . . 23 4.12 ENCRYPT Command . . . . . . . . . . . . . . . . . . . . 24 4.13 ENCREJ Response . . . . . . . . . . . . . . . . . . . . 25 5. DUNDi Information Elements . . . . . . . . . . . . . . . . . 26 5.1 EID Information Element . . . . . . . . . . . . . . . . . 26 5.2 CALLED CONTEXT Information Element . . . . . . . . . . . . 27 5.3 CALLED NUMBER Information Element . . . . . . . . . . . . 27 5.4 EID DIRECT Information Element . . . . . . . . . . . . . . 28 5.5 ANSWER Information Element . . . . . . . . . . . . . . . . 29 5.6 TTL Information Element . . . . . . . . . . . . . . . . . 30 5.7 VERSION Information Element . . . . . . . . . . . . . . . 31 5.8 EXPIRATION Information Element . . . . . . . . . . . . . . 31 5.9 UNKNOWN Information Element . . . . . . . . . . . . . . . 32 5.10 CAUSE Information Element . . . . . . . . . . . . . . . 32 5.11 REQEID Information Element . . . . . . . . . . . . . . . 33 5.12 ENCDATA Information Element . . . . . . . . . . . . . . 34 5.13 SHAREDKEY Information Element . . . . . . . . . . . . . 34 5.14 SIGNATURE Information Element . . . . . . . . . . . . . 35 5.15 KEYCRC32 Information Element . . . . . . . . . . . . . . 35 5.16 HINT Information Element . . . . . . . . . . . . . . . . 36 Spencer Expires April 13, 2005 [Page 2] Internet-Draft DUNDi October 2004 5.17 DEPARTMENT Information Element . . . . . . . . . . . . . 37 5.18 ORGANIZATION Information Element . . . . . . . . . . . . 37 5.19 LOCALITY Information Element . . . . . . . . . . . . . . 38 5.20 STATEPROV Information Element . . . . . . . . . . . . . 38 5.21 COUNTRY Information Element . . . . . . . . . . . . . . 39 5.22 EMAIL Information Element . . . . . . . . . . . . . . . 39 5.23 PHONE Information Element . . . . . . . . . . . . . . . 40 5.24 IPADDR Information Element . . . . . . . . . . . . . . . 40 6. DUNDi Best Practices . . . . . . . . . . . . . . . . . . . . 41 6.1 Network Architecture . . . . . . . . . . . . . . . . . . . 41 7. Security Considerations . . . . . . . . . . . . . . . . . . 43 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 Author's Address . . . . . . . . . . . . . . . . . . . . . . 43 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 44 Spencer Expires April 13, 2005 [Page 3] Internet-Draft DUNDi October 2004 1. Introduction This memo describes the Distributed Universal Number Discovery (DUNDi) protocol for resolving phone numbers into Internet resources for contacting those phone numbers, through a peer to peer, trusted system. Unlike centralized systems like ENUM, DUNDi is designed to facilitate the sharing of resources that can be used to terminate phone numbers by using a peer to peer system, requiring no centralized controlling authority, no single point of failure, and no enforced heirarchy. In this way, systems sharing a dialplan across an enterprise or across the globe can be assembled in an ad-hoc manor, while retaining confidence in the accuracy of the routes that are supplied and the security of both the queries and the answers within the trust group. 1.1 DUNDi Terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119[1]. Additionally, this document uses the following terminology: node A system which implements the DUNDi protocol. peer As a verb, to exchange information via the DUNDi protocol in a particular context. As a noun, a node with which one peers. context A logical collection of numbers, composing a virtual numbering plan. entity identifier (EID) A unique 6-byte identifier for a node, typically the Ethernet MAC address of one of its interfaces. transaction A complete dialog between two ends, uniquely identified at each end. time to live (TTL) A numerical representation of the number of hops through the DUNDi system and amount of time for which a query is valid. Spencer Expires April 13, 2005 [Page 4] Internet-Draft DUNDi October 2004 weight A value indicating the relative cost or indirection of a particular answer. A lower weight represents a route which is more direct to the intended location. The lowest weight value is 0. General Peering Agreement (GPA) A special peering agreement executed by members of the Dundi E.164 trust group to protect the integrity of the entries in that context. 1.2 Applicability DUNDi is specifically targeted at the problem of locating routes for telephone numbers over the Internet. While DUNDi has applications for finding routes for other kinds of information (e.g. e-mail addresses), implementations MAY perform certain optimizations based on the assumption that the query is, in fact, for a telephone number and relying on certain heuristics thereof. DUNDi is especially valuable in networks in which robustness to the loss of a node is valuable. DUNDi is also useful for building trust relationships between independent organizations who wish to communicate with one another, but for whom centralizing or delegating the required information would be impractical or impossible. DUNDi is valuable for networks in which more than one method exists, possibly with different priorities, for attempting to reach a phone number. For example, it may be possible to reach a phone number both directly over the Internet or via an Internet to PSTN gateway, in which the former is preferred, but the latter is an acceptable alternative. DUNDi is valuable for networks in which a phone number may move from one service provider to another (e.g. implementation of local number portability). 1.3 Protocol Overview DUNDi is a lightweight, low bandwidth, secure, binary encoded protocol for sharing and discovering routes to numbers in arbitrary dialplans. DUNDi provides messages and information elements designed to allow implementors the maximum flexibility in developing creative ways to minimize the amount of traffic and maximize the number of results that can be obtained through the system. DUNDi itself is not used for the actual call setup and voice control, only for locating Spencer Expires April 13, 2005 [Page 5] Internet-Draft DUNDi October 2004 the resource for delivering the call. Typically the call setup and voice control will be handled by another appropriate protocol (for example IAX, SIP, or H.323). Each node in DUNDi is identified by a globally unique six byte entity identifier, whose value typically is an Ethernet MAC address for one of the interfaces in the system. DUNDi supports overlaying multiple dialplans by the use of a "context", permitting, for example, an enterprise for using DUNDi for the management of local four digit dialing under a private context (e.g. "private"), while permitting them to share in the global "e164" context for true E.164 numbers. Any context name may be used, but the context "e164" is reserved for members of the DUNDi E.164 trust group who have executed the General Peering Agreement (GPA). DUNDi uses a simple, consistant binary encoded message frame with information elements to provide the necessary additional attributes for those messages. DUNDi does not enforce or require a particular topology although in pratice certain topologies will lend to better scaling of the resulting conglomberation of nodes by taking advantage of caching and hints. Generally speaking, m-ary trees can provide good architecture for large numbers of nodes, while strongly connected networks can work well in enterprise applications. To provide security and privacy, DUNDi uses RSA and AES for encryption and RSA for authenticating information. Spencer Expires April 13, 2005 [Page 6] Internet-Draft DUNDi October 2004 2. Protocol Functioning This section outlines the overall operation of the protocol. The fundamental construction of a DUNDi trust group is a collection of nodes in which each node is connected to at least one other node in the group (although in practice, often each node should be connected to two other nodes in order to provide redundancy). An example trust group might look like this: +----------+ +----------+ | | Trust | | | Node |<---------------------->| Node | | A |<------+ | D | | | | T | | +----------+ | r +----------+ | u +----------+ | s +----------+ | | | t | | | Node |<------+ Trust | Node | | B |<---------------------->| C | | | | | +----------+ +----------+ In this model, node A has a trust relationship with nodes D and B, while node B has a trust relationship with nodes A and C Suppose, for example, that A wants to call the number 1234. First, A would verify that 1234 was not in its local routing table or cache. Assuming it wasn't, A would then send queries to both B and D to request information on the number. If B or D had the number in its local table or cache, they would return the answer to A. B would also enquire from node C an answer which could then be returned to node A in response to its query. Note that more than one node MAY supply an answer for a query, even if those answers have the same weight. Each implementation MUST attempt to minimize the number of queries throughout the trust system, without sacrificing the accuracy of the answers provided. Some queries can be reduced by caching, others can be reduced by cleverly pruning trees through good architecture and the use of "hints". Spencer Expires April 13, 2005 [Page 7] Internet-Draft DUNDi October 2004 2.1 DUNDi Transactions A dundi transaction is a complete dialog within the DUNDi protocol from one node to another. A transaction is uniquely identified at each end by an arbitrary 16-bit transaction identifier from 1 to 65535 which SHOULD be selected as a random number for increased security. Each message contains both a source and destination transaction number so that a received message can be uniquely identified by the transaction number alone. The transaction identifier "0" is reserved for the destination transaction for the opening message of a dialog, since the destination transaction is not known at that time. A transaction MUST be started by the transmission of a command and MUST NOT be started by the transmission of a response. A transaction may be terminated at any time by either node participating by transmitting a message, other than ACK, with the "F" or "final" bit set, the receipt of which message MUST still be acknowledged by an ACK message. A node MUST NOT send any message after the receipt of a message with the "F" bit set to 1, except ACK. That ACK MUST have the F bit set to 1. Each message includes an 8-bit incoming and 8-bit outgoing sequence number. Each node independently holds an outgoing sequence number which is set to 0 for the first message of a transaction sent by that node. The outgoing sequence number is then incremented after the transmission of each new message, except ACK. The 8-bit incoming sequence number represents the next value for the outgoing sequence number that would be sent by the other party. DUNDi has a window size of exactly 1, meaning that a node SHOULD NOT transmit a new message until it has received a message from the other node with the incoming sequence number set to the value of the outgoing sequence number that node wishes to send in its next message. Upon receipt of a message other than ACK or INVALID with the outgoing sequence number set to the next expected incoming sequence number, the receiver MUST increment its next expected incoming sequence number and send a message with the updated next incoming sequence number. If there is no other message to be sent when the message is received, an ACK MUST be sent. Upon receipt of a message other than ACK or INVALID with the outgoing sequence number set to the next expected incoming sequence number, the receiver MUST immediately respond with an ACK command, with the next expected incoming sequence number set to the currently expected incoming sequence number (without being incremented) and the outgoing Spencer Expires April 13, 2005 [Page 8] Internet-Draft DUNDi October 2004 sequence number set to the value of the incoming sequence number in the received packet. Any message received in which the outgoing sequence number is neither the last expected incoming sequence number nor the currently expected next received sequence number MUST be ignored. 2.2 Retransmissions A DUNDi request may be retransmitted up to 10 times at time intervals to be decided by the implementor, but not greater than 1 second. If a message is not acknowledged after 10 retransmissions or 10 seconds, the transaction MUST be considered closed with no further messages being transmitted or expected. 2.3 Registration The REGREQ and REGRESPONSE are used to for one DUNDi peer, typically with a dynamic or address translated location, to register its presence to another, fixed DUNDi peer. The registering peer sends a REGREQ to the fixed peer (typically as a new transaction), which responds with REGRESPONSE regardless of whether the request was accepted or not. If the registration is successful, it must expire and be removed after time in the EXPIRATION information element of the REGRESPONSE has passed, and the registering entity MUST re-register before that timer expires if it wishes to retain its registration. 2.4 Dialplan Discovery The DPDISCOVER and DPRESPONSE commands are used to discover a number. A DPDISCOVER typically opens a new transaction to perform a query and, if authorized, is typically responded to with an ACK and then eventually with a DPRESPONSE with the F bit set to 1. Upon receipt of a DPDISCOVER, an entity MUST respond with a DPRESPONSE within T milliseconds where T is the value of the TTL information element multiplied by 200 and added to 2000. An entity which makes a DPDISCOVER SHOULD terminate its request with CANCEL if it does not receive a DPRESPONSE within T + 200 milliseconds of making its request. The peer making the DPDISCOVER request and receiving the DPRESPONSE should process and cache the response and immediately create its own DPRESPONSE to any DPDISCOVER request which had the source of its DPDISCOVER. If a DPDISCOVER is sent in conjunction with a DPDISCOVER that was received from another entity: Spencer Expires April 13, 2005 [Page 9] Internet-Draft DUNDi October 2004 1. It MUST have a TTL which is one less than the TTL in the received DPDISCOVER command. If the received TTL is 0, the request MUST NOT be forwarded to any other entities. 2. It MUST NOT be sent to any entities whose identities are listed in the originating DPDISCOVER. 3. The last EID information element in the new DPDISCOVER MUST be the same as the last EID information element in the originating DPDISCOVER. The first EID information element must be the EID of the entity sending the new DPDISCOVER. All other EID's listed in the original DPDISCOVER MUST be included in any new DPDISCOVER. Regardless of the source of a DPDISCOVER, the following MUST always hold true for the DPRESPONSE: 1. A DPRESPONSE being sent MAY include one or more answers but MUST NOT include answers with the same Technology and Destination. If the DPRESPONSE is combining answers from sources which share the same Technology and Destination, it MUST only include the answer with the lowest Weight. 2. If there were any entities which would have been queried had the TTL been greater than 1, then the response MUST have the hint flag TTLEXPIRED present. 3. The UNAFFECTED hint bit MUST be set if and only if no entities listed in the DPDISCOVER with the EID information element (as opposed to the EID_DIRECT information element) would have been queried anyway, had they not been present in the request. 4. The DONTASK hint bit SHOULD be set, and the shortest substring of the number for which no number beginning with that substring could possibly have been a match. 2.5 EID Query The EIDQUERY and EIDRESPONSE commands are used to obtain information about a speific EID in the network. An EIDQUERY typically opens a new transaction to perform a query and, if authorized, is typically responded to with an ACK and then eventually with a EIDRESPONSE with the F bit set to 1. The rules for forwarding EID queries generally follow those of the DPDISCOVER/DPRESPONSE described in Section 2.4. 2.6 Example Transaction Flows Spencer Expires April 13, 2005 [Page 10] Internet-Draft DUNDi October 2004 An example transaction sequence might look something like this (assume Si is next expected incoming sequence number and So is the next outgoing sequence number, Ts is the source transaction number, Td is the destination transaction number and F is the final bit: Example 1: Register request /response Node A Node B REGREQ (So=0,Si=0,Ts=1234,Td=0,F=0) ===============> <======= REGRESPONSE (So=0,Si=1,Ts=5678,Td=1234,F=1) ACK (So=1,Si=1,Ts=1234,Td=5678,F=1) ===============> Example 2: Dialplan discovery Node A Node B DPDISCOVER (So=0,Si=0,Ts=2345,Td=0) ===============> <=============== ACK (So=0,Si=1,Ts=6789,Td=2345,F=0) <======== DPRESPONSE (So=0,Si=1,Ts=6789,Td=2345,F=1) ACK (So=1,Si=1,Ts=2345,Td=6789,F=1) ===============> Example 3: Entity Identifier Query Node A Node B EIDQUERY (So=0,Si=0,Ts=3456,Td=0) =================> <=============== ACK (So=0,Si=1,Ts=6789,Td=3456,F=0) <======= EIDRESPONSE (So=0,Si=1,Ts=6789,Td=3456,F=1) ACK (So=1,Si=1,Ts=3456,Td=6789,F=1) ===============> (Note that these examples do not use encryption, but the flow would be essentially identical with encryption.) Spencer Expires April 13, 2005 [Page 11] Internet-Draft DUNDi October 2004 3. Packet Format and Forwarding 3.1 Protocol and Port Number Packets in DUNDi are communicated using UDP on "well known" port 4520 (not yet assigned by IANA) 3.2 Endpoint Identifiers The endpoint identifier is a 6 byte globally unique identifier. In order that global uniqueness be guaranteed, an implementation SHOULD use the MAC address of an ethernet, bluetooth, or similar interface within the system. 3.3 Packet Format The basic layout of any packet in DUNDi (omitting IP and UDP headers): 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Transaction | Destination Transaction | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ISeqno | OSeqno |F|R| CmdResp | CmdFlags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Information Elements : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Source Transaction The local unique identifier for the transaction. Destination Transaction The remote unique identifier for the transaction. ISeqno The next expected incoming sequence number. OSeqno The outgoing sequence number. F The Final bit, '1' if this is the last command of a transaction (or its acknowledging ACK). Spencer Expires April 13, 2005 [Page 12] Internet-Draft DUNDi October 2004 R The Response bit, '0' if this is a command or '1' if this is a response. Only commands may open a dialog, but commands or responses may close a dialog. CommandResp The command being requested, or the response to a command (see Section 4) CmdFlags Command specific flags. Information Elements Zero or more DUNDi information elements (see Section 5). Spencer Expires April 13, 2005 [Page 13] Internet-Draft DUNDi October 2004 4. DUNDi Commands and Responses DUNDi commands are eight bits in length including the R ("Response") and F ("Final") bits. This section documents the encodings and information elements for each frame. For each section, the encoding of the message is provided as well as a table of information elements which are applicable for the message, along with their meanings. Any information elements which are received that are NOT listed within the specification MUST be ignored unless their meaning is defined by a later version of this standard. A DUNDi peer MUST NOT append additional information elements which are not listed for a message unless they are defined by a later version of this standard. A DUNDi peer SHOULD refuse to process a command or response for which mandatory information elements are missing. The order of different kinds of information elements within a message is irrelevent except that the ENCDATA information element MUST be last if it is present at all. The folowing table describes the meaning of the "Type" field of the tables for information elements: +------+------------+-------------------------------------------------+ + Type | Name | Meaning with relation to message | +------+------------+-------------------------------------------------+ | M | Mandatory | exactly one MUST be present | +-------------------+-------------------------------------------------+ | O | Optional | exactly one MAY be present | +-------------------+-------------------------------------------------+ | M+ | Mandatory | at least one MUST be present, more permitted | +-------------------+-------------------------------------------------+ | O+ | Optional | one or more MAY be present | +---------------------------------------------------------------------+ The F bit MUST be set to a 1 when the ACK is in response to the final message of a transaction and MUST be set to 0 in all other cases. Spencer Expires April 13, 2005 [Page 14] Internet-Draft DUNDi October 2004 4.1 ACK Response The ACK CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x00 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The F bit MUST be set to a 1 when the ACK is in response to the final message of a transaction and MUST be set to 0 in all other cases. Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. The following information elements are used with ACK: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | No Information Elements are included with this message | +---------------------+------+------------------------------------+ No Information Element Notes. The purpose of the ACK command is to acknowledge receipt of a message when there is no other message immediately available to be sent. Note that the outgoing sequence number is NOT incremented after transmission of ACK, unlike all other messages. ACK MUST NOT be sent in response to another ACK or INVALID message. 4.2 DPDISCOVER Command The DPDISCOVER CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |0|0| 0x01 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MUST NOT set the F bit on a DPDISCOVER since it would preclude an answer from coming back. Handling of a DPDISCOVER with the F bit set to 1 Spencer Expires April 13, 2005 [Page 15] Internet-Draft DUNDi October 2004 MUST remain in accordance with Section 2.1. The following information elements are used with DPDISCOVER: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | VERSION | M | MUST be the value "1" for this | | | | version of the standard. | +---------------------+------+------------------------------------+ | EID / EID_DIRECT | M+ | First listed EID MUST be that of | | | | the entity making the request. | | | | Last listed EID MUST be the | | | | original source of the request. | +---------------------+------+------------------------------------+ | CALLED NUMBER | M | The number being discovered. | +---------------------+------+------------------------------------+ | CALLED CONTEXT | M | The context in which to discover. | +---------------------+------+------------------------------------+ | TTL | M | The TTL of this request. | +---------------------+------+------------------------------------+ The purpose of the DPDISCOVER command is to initiate discovery of a number within the DUNDi system. The DPDISCOVER typically begins a transaction and is typically responded to initially with an ACK and then with a DPRESPONSE once the DPDISCOVER has been processed by the remote node. Upon receiving a DPDISCOVER, a peer MUST respond within 200ms of the TTL plus 2000ms. 4.3 DPRESPONSE Response The DPRESPONSE CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x02 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MAY set the F bit on a DPRESPONSE. Spencer Expires April 13, 2005 [Page 16] Internet-Draft DUNDi October 2004 The following information elements are used with DPRESPONSE: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | CAUSE | O | May indicate cause of lack of | | | | an answer, SHOULD be included if | | | | lack of answer is authentication | | | | error. | +---------------------+------+------------------------------------+ | ANSWER | O+ | Any discovered answers from the | | | | system. | +---------------------+------+------------------------------------+ | HINT | M | Hints about answers or lack | | | | thereof. | +---------------------+------+------------------------------------+ | EXPIRATION | M | Expiration of this answer, hint or | | | | lack of information. | +---------------------+------+------------------------------------+ The purpose of the DPRESPONSE is to communicate the answer to a DPDISCOVERY back to the requesting source. 4.4 EIDQUERY Command The EIDQUERY CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |0|0| 0x03 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MUST NOT set the F bit on a EIDQUERY since it would preclude an answer from coming back. Handling of a EIDQUERY with the F bit set to 1 MUST remain in accordance with Section 2.1. Spencer Expires April 13, 2005 [Page 17] Internet-Draft DUNDi October 2004 The following information elements are used with EIDQUERY: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | VERSION | M | MUST be the value "1" for this | | | | version of the standard. | +---------------------+------+------------------------------------+ | EID / EID_DIRECT | M+ | First listed EID MUST be that of | | | | the entity making the request. | | | | Last listed EID MUST be the | | | | original source of the request. | +---------------------+------+------------------------------------+ | REQUESTED EID | M | The EID being queried. | +---------------------+------+------------------------------------+ | CALLED CONTEXT | M | The context in which to discover. | +---------------------+------+------------------------------------+ | TTL | M | The TTL of this request. | +---------------------+------+------------------------------------+ The purpose of the EIDQUERY command is to initiate a query for information about a specific EID within the DUNDi system. The EIDQUERY typically begins a transaction and is typically responded to initially with an ACK and then with an EIDRESPONSE once the EIDQUERY has been processed by the remote node. Upon receiving a EIDQUERY, a peer MUST respond within 200ms of the TTL plus 2000ms. 4.5 EIDRESPONSE Response The EIDRESPONSE CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x04 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MAY set the F bit on a EIDRESPONSE. Spencer Expires April 13, 2005 [Page 18] Internet-Draft DUNDi October 2004 The following information elements are used with EIDRESPONSE: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | DEPARTMENT | O | Contact Department for EID | +---------------------+------+------------------------------------+ | ORGANIZATION | O | Contact Organization for EID | +---------------------+------+------------------------------------+ | LOCALITY | O | Contact City or Locality for EID | +---------------------+------+------------------------------------+ | STATEPROV | O | Contact State or Province for EID | +---------------------+------+------------------------------------+ | COUNTRY | O | Contact Country for EID | +---------------------+------+------------------------------------+ | EMAIL | O | Contact E-mail Address for EID | +---------------------+------+------------------------------------+ | PHONE | O | Contact Phone Number for EID | +---------------------+------+------------------------------------+ | IPADDR | O | IP Address for EID, MUST be auto- | | | | matically assigned by entity which | | | | directly connects to the EID. | +---------------------+------+------------------------------------+ | HINT | M | Hints about answers or lack | | | | thereof. | +---------------------+------+------------------------------------+ The purpose of the EIDRESPONSE response is to relay information that is gleaned about an EID that has been required from another peer. If an answer is found, ALL fields MUST be populated with the values from the original entity whose EID is being queried, with the exception of IPADDR which is populated by the entity which is directly connected to the entity whose EID is being queried, and MAY be omitted in the response from that EID. 4.6 INVALID Response The INVALID CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1|1| 0x07 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. The F bit Spencer Expires April 13, 2005 [Page 19] Internet-Draft DUNDi October 2004 MUST for an INVALID response. The following information elements are used with INVALID: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | No Information Elements are included with this message | +---------------------+------+------------------------------------+ The purpose of the INVALID response is to indicate that a message was received outside the scope of a valid DUNDi transaction. The INVALID message MAY be sent in response to any message except an INVALID. The INVALID message MUST NOT be retransmitted unless another message is received in an INVALID state. If an INVALID message is received, it MUST NOT generate any response, including an ACK or another INVALID. 4.7 UNKNOWN Response The UNKNOWN CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x08 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node SHOULD set the F bit on an UNKNOWN response if and only if it is the first message of the transaction. The following information elements are used with UNKNOWN: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | UNKNOWN | M | Value of command which was not | | | | recognized. | +---------------------+------+------------------------------------+ The purpose of the UNKNOWN response is to indicate the receipt of an unknown or unimplemented command. If an unrecognized command is received within a transaction which was started by an understood command, an UNKNOWN response should be sent and the unrecognized command ignored. Spencer Expires April 13, 2005 [Page 20] Internet-Draft DUNDi October 2004 4.8 NULL Command The NULL CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x09 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. The F bit MAY be set for an NULL response. The following information elements are used with NULL: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | No Information Elements are included with this message | +---------------------+------+------------------------------------+ The purpose of the NULL command is to test for connectivity or to keep a socket connection alive. It does not carry any additional information. 4.9 REGREQ Command The REGREQ CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |0|0| 0x0a | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MUST NOT set the F bit on a REGREQ since it would preclude an answer from coming back. Handling of a REGREQ with the F bit set to 1 MUST remain in accordance with Section 2.1. Spencer Expires April 13, 2005 [Page 21] Internet-Draft DUNDi October 2004 The following information elements are used with REGREQ: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | VERSION | M | MUST be the value "1" for this | | | | version of the standard. | +---------------------+------+------------------------------------+ | EID | M | EID being registered | +---------------------+------+------------------------------------+ | EXPIRATION | M | Maximum requested life of | | | | registration. +---------------------+------+------------------------------------+ The purpose of the REGREQ command is to initiate registration of one, mobile node of DUNDi system with another, fixed node. The REGREQ typically begins a transaction and is typically responded to with a REGRESPONSE once the REGREQ has been processed by the fixed node. 4.10 REGRESPONSE Response The REGRESPONSE CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|1| 0x0b | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MAY set the F bit on a REGRESPONSE. Spencer Expires April 13, 2005 [Page 22] Internet-Draft DUNDi October 2004 The following information elements are used with REGRESPONSE: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | CAUSE | O | May indicate cause of lack of | | | | an answer, SHOULD be included if | | | | lack of answer is authentication | | | | error. | +---------------------+------+------------------------------------+ | EXPIRATION | M | Maximum time before registration | | | | must be renewed. | +---------------------+------+------------------------------------+ The purpose of the REGRESPONSE is to communicate the success or failure of a REGREQ. 4.11 CANCEL Command The CANCEL CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1|0| 0x0c | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. The F bit MUST be set for an CANCEL request. The following information elements are used with CANCEL: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | No Information Elements are included with this message | +---------------------+------+------------------------------------+ The purpose of the CANCEL command is to test for connectivity or to keep a socket connection alive. It does not carry any additional information. Spencer Expires April 13, 2005 [Page 23] Internet-Draft DUNDi October 2004 4.12 ENCRYPT Command The ENCRYPT CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |F|0| 0x0d | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MAY set the F bit on an ENCRYPT. The following information elements are used with DPDISCOVER: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | EID | O | EID of entity sending encrypted | | | | message. | +---------------------+------+------------------------------------+ | KEYCRC32 | O | CRC32 of RSA encrypted AES key to | | | | be used for encrypting this | | | | transaction | +---------------------+------+------------------------------------+ | SHAREDKEY | O | RSA encrypted AES key to be used | | | | for encrypting this transaction. | +---------------------+------+------------------------------------+ | SIGNATURE | O | RSA signature of the contents of | | | | SHAREDKEY information element | +---------------------+------+------------------------------------+ | ENCDATA | M | Actual encrypted data. MUST be | | | | the last information element. | +---------------------+------+------------------------------------+ Note: The EID and either KEYCRC32 or the combination of SHAREDKEY and SIGNATURE MUST be present in the first message of a transaction. The purpose of the ENCRYPT command is to encrypt another DUNDi message (other than another ENCRYPT message of course), complete with information elements in order to provide authentication and privacy for sensitive transactions. The initial encrypted message MUST contain the key, either referenced implicitly, by sending the KEYCRC32, or explicitly, senidng the full RSA encrypted shared key (encrypted by the recipients public key), Spencer Expires April 13, 2005 [Page 24] Internet-Draft DUNDi October 2004 and the RSA signature of that encrypted key (signed by the private key of the transmitter). If the receiving party has been transmitted the desired encrypted key (and signature) before, the KEYCRC32 element can be used so the recipient knows to use the old key. If the recipient does not have the old key, or its key's CRC32 does not match the received one, it MUST send ENREJ and the transmitter SHOULD re-attempt the connection using the SHAREDKEY and SIGNATURE fields instead. 4.13 ENCREJ Response The ENCREJ CmdResp and CmdFlags values shall be encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1|1| 0x0e | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Any received CmdFlags MUST be ignored unless they are defined by a later version of this standard. CmdFlags MUST be encoded as 0 unless flags are defined by a later version of this standard. A node MUST set the F bit on a ENCREJ. The following information elements are used with ENCREJ: +---------------------+------+------------------------------------+ + Information Element | Type | Notes | +---------------------+------+------------------------------------+ | CAUSE | O | May indicate cause of encryption | | | | failure. | | | | lack of answer is authentication | | | | error. | +---------------------+------+------------------------------------+ The purpose of the ENCREJ response is to inform a transmitter that their encrypted message was not properly received. Upon receiving an ENCREJ to a message which was transmitted using the, the transmitter SHOULD another ENCRYPT if and only if the message which received the ENCREJ had the KEYCRC32 information element instead of the SHAREDKEY and SIGNATURE elements. Spencer Expires April 13, 2005 [Page 25] Internet-Draft DUNDi October 2004 5. DUNDi Information Elements DUNDi Information elements are encoded as follows: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | IE | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Element Specific Data : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ IE One octet information element identifier Length The length of the element specific data, exception in the case of the ENCDATA information element, where this field is ignored and the length assumed to be the remainder of the message. Element Specific Data Any element specific data. 5.1 EID Information Element The EID information element communicates a DUNDi entity identifier and always exactly six octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x01 | 0x06 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : Entity Identifier : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The EID information element, when present in DPDISCOVER (Section 4.2) and in EIDQUERY (Section 4.4), indicates an EID which does not directly peer with the party sending the information element and which should not be queried for a DPDISCOVER or EIDQUERY. It is acceptable to send cached answers which include answers that were obtained from the listed EID, but an implementation MUST NOT send a Spencer Expires April 13, 2005 [Page 26] Internet-Draft DUNDi October 2004 new message to an EID that is listed in the DPDISCOVER or EIDQUERY message. 5.2 CALLED CONTEXT Information Element The CALLED CONTEXT information element communicates which DUNDi context in which a number or entity identifier (EID) should be interepreted as a part of. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x02 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Called Context : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Called Context may be any ASCII encoded string of any combination of letters, numbers, periods or hyphens. 5.3 CALLED NUMBER Information Element The CALLED NUMBER information element communicates the number which is being requested in a DPDISCOVER command (see Section 4.2). 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x03 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Called Number : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Called Number may be any ASCII encoded string of any combination of letters, numbers, periods or hyphens. Spencer Expires April 13, 2005 [Page 27] Internet-Draft DUNDi October 2004 5.4 EID DIRECT Information Element The EID DIRECT information element communicates a DUNDi entity identifier and always exactly six octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x04 | 0x06 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : Entity Identifier : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The EID information element, when present in DPDISCOVER (Section 4.2) and in EIDQUERY (Section 4.4), indicates an EID which does not directly peer with the party sending the information element. Its meaning is identical to that of the EID information element except the EID DIRECT refers to an entity identifier to which a given host has a direct peering relationship and which should not be queried for a DPDISCOVER or EIDQUERY. It is acceptable to send cached answers which include answers that were obtained from the listed EID, but an implementation MUST NOT send a new message to an EID that is listed in the DPDISCOVER or EIDQUERY message. Spencer Expires April 13, 2005 [Page 28] Internet-Draft DUNDi October 2004 5.5 ANSWER Information Element The ANSWER information element communicates an answer to a DUNDi number request. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x05 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Originating EID : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Protocol |0|0|0|0|0|0|0|S: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ :U|P|B|R|I|C|M|E| Weight : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : Weight (ctd) | : +-+-+-+-+-+-+-+-+ : | : : Destination Specific Data : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Originating EID is the six octet EID of the original source of the answer and MUST not be modified when an answer is propagated from one node to another. Protocol specifies which protocol the destination specific data should be interpreted with. The Weight is a measure of preference of a given answer, where the lower answer means this is a more highly preferred route. The folowing table describes encoding of protocols and protocol specific data: +----------+------------+-------------------------------------------------+ + Protocol | Name | Encoding of Destination Specific Data | +----------+------------+-------------------------------------------------+ | 0x00 | None | Reserved, do not use. | +----------+------------+-------------------------------------------------+ | 0x01 | IAX | IAX2 URI ([user[:pass]@]host[/number[@context]])| +----------+------------+-------------------------------------------------+ | 0x02 | SIP | SIP URI, without the leading "sip:" | +----------+------------+-------------------------------------------------+ | Ox03 | H.323 | IP address as a string representation (???) | +----------+------------+-------------------------------------------------+ ANSWER information elements with protocols that are not known to the Spencer Expires April 13, 2005 [Page 29] Internet-Draft DUNDi October 2004 implementation MUST be ignored. The folowing table describes encoding of flags supplied with an answer: +------+----------------+-------------------------------------------------+ + Flag | Name | Meaning of flag | +------+----------------+-------------------------------------------------+ | E | Exists | This route exists | +------+----------------+-------------------------------------------------+ | M | MatchMore | Adding an additional digit might lead to a | | | | valid number. | +------+----------------+-------------------------------------------------+ | C | CanMatch | This extension as is, or with more digits may | | | | | +------+----------------+-------------------------------------------------+ | I | IgnorePat | Reserved, do not use. | +------+----------------+-------------------------------------------------+ | R | Residential | Reserved, do not use. | +------+----------------+-------------------------------------------------+ | B | Commercial | Reserved, do not use. | +------+----------------+-------------------------------------------------+ | P | Mobile | Reserved, do not use. | +------+----------------+-------------------------------------------------+ | U | NoUnsolicited | Reserved, do not use. | +------+----------------+-------------------------------------------------+ | S | NoComUnsolctd | Reserved, do not use. | +------+----------------+-------------------------------------------------+ ANSWER information elements with protocols that are not known to the implementation MUST be ignored. 5.6 TTL Information Element The TTL information element is used to indicate time to live and always exactly two octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x06 | 0x02 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TTL | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The TTL information element communicates the maximum time to live of a DPDISCOVER (Section 4.2) or EIDQUERY (Section 4.4). At each hop, if an incoming EIDQUERY or DPDISCOVER creates an outbound request, Spencer Expires April 13, 2005 [Page 30] Internet-Draft DUNDi October 2004 that request must have a TTL at least one less than the incoming request. The TTL is also a time metric for the life of a request which can be calculated as 200 milliseconds multiplied by the TTL, plus 2000 milliseconds. 5.7 VERSION Information Element The VERSION information element is used to indicate time to live and always exactly two octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0a | 0x02 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0001 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The VERSION information element communicats what version of the protocol a node supports. 5.8 EXPIRATION Information Element The EXPIRATION information element communicates the number of seconds for the expiration of a registration or DPRESPONSE data and always exactly two octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0b | 0x02 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Expiration | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The EXPIRATION information element is used with REGREQ and REGRESPONSE commands (Section 4.9 and Section 4.10) to indicate when a registration needs to be renewed. It is also used with a DPRESPONSE (Section 4.3) to indicate how long an answer is valid for. Spencer Expires April 13, 2005 [Page 31] Internet-Draft DUNDi October 2004 5.9 UNKNOWN Information Element The UNKNOWN information element conveys which received command was unknown or unimplemented. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0c | 0x01 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Unknown Cmd | +-+-+-+-+-+-+-+-+ The UNKNOWN information element is used as part of the UNKNOWN command (see Section 4.7) to indicate which command was unknown or misunderstood. Unknown Cmd is the value of the CmdResp field of the message in question. 5.10 CAUSE Information Element The CAUSE information element communicates a reason for failure. This information element communicates both a mandatory 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0e | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Cause Code | : +-+-+-+-+-+-+-+-+ : | | : Cause Description : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Cause Code is a one byte code indicating the general cause of a failure, while the Cause Description is an optional text description, perhaps with more detail, to provide the user more helpful detail. The Cause Description MUST NOT be used for any purpose other than to provide additional diagnostics to the user. Spencer Expires April 13, 2005 [Page 32] Internet-Draft DUNDi October 2004 The folowing table describes encoding of protocols and protcol specific data: +----------+------------+-------------------------------------------------+ + Code | Name | Description | +----------+------------+-------------------------------------------------+ | 0x00 | Success | No failure at all. | +----------+------------+-------------------------------------------------+ | 0x01 | General | General failure | +----------+------------+-------------------------------------------------+ | 0x02 | Reserved | Do not use | +----------+------------+-------------------------------------------------+ | 0x03 | NoAuth | Authorization failed | +----------+------------+-------------------------------------------------+ | 0x04 | Duplicate | A matching request is alreadying in queue | +----------+------------+-------------------------------------------------+ | 0x05 | TTLExpired | Maximum TTL Expired for request | +----------+------------+-------------------------------------------------+ | 0x06 | NeedKey | Need the actual key, not just the CRC | +----------+------------+-------------------------------------------------+ | 0x07 | BadEncrypt | Data is badly encrypted | +----------+------------+-------------------------------------------------+ If the Cause Code in a cause is unrecognized, it MUST be treated as though it were "General". 5.11 REQEID Information Element The REQEID information element communicates a DUNDi entity identifier and always exactly six octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0f | 0x06 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : Entity Identifier : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The REQEID information element is used only in EIDQUERY (Section 4.4), and indicates the EID which is being queried. Spencer Expires April 13, 2005 [Page 33] Internet-Draft DUNDi October 2004 5.12 ENCDATA Information Element The ENCDATA information element communicates a block of encrypted data. It contains a 16-byte initialization vector followed by a block of AES+CBC encrypted data. This element, if present, MUST be the last element in a message and the recevier MUST ignore the length field of the information element and assume its length to be the entire remainder of the message (since the ENCDATA can often be much larger than 256 bytes!). 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x10 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Initialization Vector : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Encrypted Data : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an ENCRYPT message (see Section 4.12. Its contents are another dundi message (without the first 6 bytes of header) which has been compressed RFC1950 [2] and then encrypted with AES encryption and CBC block chaining. When receiving this information element, after decoding, 5.13 SHAREDKEY Information Element The SHAREDKEY information element communicates the RSA encrypted AES-128 key to use for decrypting the current session. This information element is always 128 bytes long. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x11 | 0x80 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Encrypted Shared Key : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is used in the first ENCRYPT message of a transaction to convey the AES-128 key that is used for the Spencer Expires April 13, 2005 [Page 34] Internet-Draft DUNDi October 2004 transaction. It is encrypted using RSA and the public key of the recipient. If this information element is present, the SIGNATURE information element must also be present. 5.14 SIGNATURE Information Element The SIGNATURE information element communicates the RSA signature of the SHAREDKEY information element. This information element is always 128 bytes long. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x12 | 0x80 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Signed Encrypted Key : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is used in the first ENCRYPT message of a transaction to convey the RSA signature (using the private key of the sender) of the SHAREDKEY. 5.15 KEYCRC32 Information Element The KEYCRC32 information element communicates a CRC32 of an encrypted shared key and contains exactly four octets of data. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x13 | 0x04 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | CRC32 : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The KEYCRC32 is used with the first ENCRYPT message (Section 4.12), of a transaction and indicates a CRC32 of the encrypted key to use, to avoid having to repeat the encrypted key. If the CRC32 does not match the CRC32 of the last received message, the recipient MUST reject the message with ENCREJ in order to request the transmitter resubmit their message with the full encrypted key and signature. Spencer Expires April 13, 2005 [Page 35] Internet-Draft DUNDi October 2004 5.16 HINT Information Element The HINT information element communicates additional information which may be valuable in interpreting an answer to a DPDISCOVER. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x14 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x00 |U|D|T| : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Hint information : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Cause Code is a one byte code indicating the general cause of a failure, while the Cause Description is an optional text description, perhaps with more detail, to provide the user more helpful detail. The Cause Description MUST NOT be used for any purpose other than to provide additional diagnostics to the user. The folowing table describes encoding of flags supplied with an answer: +------+----------------+-------------------------------------------------+ + Flag | Name | Meaning of flag | +------+----------------+-------------------------------------------------+ | T | TTLExpired | The TTL expired when performing this query. | +------+----------------+-------------------------------------------------+ | D | DontAsk | Do not ask any questions about numbers which | | | | begin with the pattern in Hint Information | +------+----------------+-------------------------------------------------+ | U | Unaffected | The supplied list of EIDs did not affect the | | | | calculation of this response. | +------+----------------+-------------------------------------------------+ HINT information elements received with flags not known to the implementation MUST behave as though those flags had not been present. Spencer Expires April 13, 2005 [Page 36] Internet-Draft DUNDi October 2004 5.17 DEPARTMENT Information Element The DEPARTMENT information element communicates the department where a node is located. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x15 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Department : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 5.18 ORGANIZATION Information Element The ORGANIZATION information element communicates the person or organization responsbile fora given node. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x16 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Organization : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 Spencer Expires April 13, 2005 [Page 37] Internet-Draft DUNDi October 2004 5.19 LOCALITY Information Element The LOCALITY information element communicates the city or locality where a node is located. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x17 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Locality : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 5.20 STATEPROV Information Element The STATEPROV information element communicates the state or privince where a node is located. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x18 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : State/Province : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 Spencer Expires April 13, 2005 [Page 38] Internet-Draft DUNDi October 2004 5.21 COUNTRY Information Element The COUNTRY information element communicates the international country appreviation where a node is located. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x19 | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Country : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 5.22 EMAIL Information Element The EMAIL information element communicates the contact e-mail address to be used for administrative communication related to DUNDi. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x1a | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : E-mail Address : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 Spencer Expires April 13, 2005 [Page 39] Internet-Draft DUNDi October 2004 5.23 PHONE Information Element The PHONE information element communicates the contact phone number to be used for administrative communication related to DUNDi. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x1b | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : Phone Number : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 5.24 IPADDR Information Element The IPADDR information element communicates the ASCII representation of the IP address where a node is located. The use of an ASCII encoding permits presentation of other kinds of addresses should DUNDi be moved to IPv4 or other addressing schemes. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x1c | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | : IP Address : | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This information element is only used with an EIDRESPONSE message (see Section 4.5 and is populated by the node next to the node being queried so that it is automatically discovered. Spencer Expires April 13, 2005 [Page 40] Internet-Draft DUNDi October 2004 6. DUNDi Best Practices The DUNDi protocol is designed to provide the greatest flexibility of implementation to the implementor themselves. As such, this section should not be considered part of the protocol specification itself, but as some hints for an implementor on how one might be able to maximize performance. 6.1 Network Architecture The Center of the tree contains nodes which are strongly connected with high speed connections. Then, a ring is formed around the core with each node of the ring This two layer core then has the remainder of the nodes in M-ary trees behind them,, where the vertex of that tree is exactly one node of the secondary ring, with an option to use another node in the secondary ring as a backup which one always accepts queries from, but only places queries to if the primary node has failed. +----+ +----+ +----+ +----+ | BA | | BB | | BC | | BD | +----+ +----+ +----+ +----+ \\ | \ / | // \\ T T T // \T | / \ | T/ \\ +----+ +----+ // \\---| AA |--T--| AB |---// T +----+ +----+ T \ / | | \ / X T T X / \ | | / \ T +----+ +----+ T //---| AC |--T--| AD |---\\ // +----+ +----+ \\ /T | \ / | T\ // T T T \\ // | / \ | \\ +----+ +----+ +----+ +----+ | BE | | BF | | BG | | BH | +----+ +----+ +----+ +----+ / | \ : T T T S / | \ : +----+ +----+ +----+ | CA | | CB | | CC | +----+ +----+ +----+ Spencer Expires April 13, 2005 [Page 41] Internet-Draft DUNDi October 2004 : / | \ S T T T : / | \ +----+ +----+ +----+ | DA | | DB | | DC | +----+ +----+ +----+ In this diagram, each node is identified by a two letter name, rather than a full 6 byte EID. The lines with "T" represent primary direct trust relationships. The dashed lines with "S" represent example secondary links which would be queried only if the primary link were missing. Spencer Expires April 13, 2005 [Page 42] Internet-Draft DUNDi October 2004 7. Security Considerations DUNDi is designed to provide builtin strong cryptographic security to be sure the messages conveyed between participating nodes are both secure and private. DUNDi also provide explicit contexts to permit the separation of dialplans, allowing certain contexts to be only available to certain peers. However, DUNDi is not able to prevent the infusion of invalid information from other trusted parties in the network. 8 References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [2] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format Specification version 3.3", RFC 1950, May 1996. [3] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. [4] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, BCP 9, October 1996. [5] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. Author's Address Mark A. Spencer Digium, Inc. 150 West Park Loop Suite 100 Huntsville, AL 35806 US Phone: +1 256 428 6000 EMail: markster@digium.com URI: http://www.digium.com/ Spencer Expires April 13, 2005 [Page 43] Internet-Draft DUNDi October 2004 Appendix A. Acknowledgements The author gratefully acknowledges the contributions of: Russell Bryant, Brian Greskamp, Ed Guy, Matthew Hardeman. John Lodden, Frank Miller, Ravi Sakaria, John Todd and Justin Troutman, Spencer Expires April 13, 2005 [Page 44]