Permalink
Browse files

1.3rc4: incorporated list consensus about workding on TXT record format

git-svn-id: svn://svn.xmpp.org:7938/xmpp/trunk@2518 4b5297f7-1745-476d-ba37-a9c6900126ab
  • Loading branch information...
1 parent 78540c5 commit 839bc528524362c6d51f3584c5c5e1db2b75dd00 @stpeter stpeter committed Nov 19, 2008
Showing with 50 additions and 62 deletions.
  1. +50 −62 extensions/xep-0174.xml
View
@@ -27,8 +27,8 @@
<registry/>
&stpeter;
<revision>
- <version>1.3rc3</version>
- <date>in progress, last updated 2008-11-14</date>
+ <version>1.3rc4</version>
+ <date>in progress, last updated 2008-11-18</date>
<initials>psa</initials>
<remark><p>Corrected TXT record format in conformance with draft-cheshire-dnsext-dns-sd; clarified a number of issues related to DNS-SD and Multicast DNS; as an optimization, recommended sending of disco#info data in stream features; removed reference to Encrypted Sessions specification from the security considerations.</p></remark>
</revision>
@@ -177,24 +177,22 @@ _presence._tcp.local. PTR juliet@pronto._presence._tcp.local.
<li>The SRV record (see &rfc2782;) maps the presence service instance "juliet@pronto" to the machine "pronto.local." on port 5562.</li>
<li>The PTR ("pointer") record (see &rfc2317; and &rfc1886;) says that there is a service of type "presence" on the local subnet (".local.") called "juliet@pronto" and that the service communicates over TCP.</li>
</ul>
- <p>Your chat client also wants to advertise some information about you (subject to your control so that you don't divulge private information). Therefore it invokes the mDNS daemon to also publish a single DNS TXT record (see &rfc1464;) that encapsulates some strings of information, where the record name is the same as the SRV record and the record value follows the format defined in the DNS-SD specification, as further described in the <link url='#txt'>TXT Record</link> section of this document.</p>
+ <p>Your chat client also wants to advertise some information about you (subject to your control so that you don't divulge private information). Therefore it invokes the mDNS daemon to also publish a single DNS TXT record (see &rfc1464;) that encapsulates some strings of information, where the record name is the same as the SRV record and the record value follows the format described in the <link url='#txt'>TXT Record</link> section of this document. The strings are typically key-value pairs such as the following:</p>
<code><![CDATA[
-juliet@pronto._presence._tcp.local. IN TXT "
- 0x09txtvers=1
- 0x0A1st=Juliet
- 0x18email=juliet@capulet.lit
- 0x0Ahash=sha-1
- 0x16jid=juliet@capulet.lit
- 0x0Clast=Capulet
- 0x18msg=Hanging out downtown
- 0x0Anick=JuliC
- 0x1Anode=http://www.adiumx.com
- 0x2Dphsh=a3839614e1a382bcfebbcf20464f519e81770813
- 0x0Eport.p2pj=5562
- 0x0Cstatus=avail
- 0x06vc=CA!
- 0x20ver=QgayPKawpkPSDYmwT/WM94uAlu0=
- "
+txtvers=1
+1st=Juliet
+email=juliet@capulet.lit
+hash=sha-1
+jid=juliet@capulet.lit
+last=Capulet
+msg=Hanging out downtown
+nick=JuliC
+node=http://www.adiumx.com
+phsh=a3839614e1a382bcfebbcf20464f519e81770813
+port.p2pj=5562
+status=avail
+vc=CA!
+ver=QgayPKawpkPSDYmwT/WM94uAlu0=
]]></code>
<p>Other people at the hotspot can also advertise similar DNS records for use on the local link. Essentially, the mDNS daemons running on all of the machines at the hotspot collectively manage the ".local." domain, which has meaning only at the hotspot (not across the broader Internet). Queries and responses for services on the local link occur via multicast DNS over UDP port 5353 instead of via normal DNS unicast over UDP port 53. When a new machine joins the local link, it can send out queries for any number of service types, to which the other machines will reply. For the purpose of serverless messaging we are interested only in the "presence" service, but many other services could exist on the local link (see <link url='http://www.dns-sd.org/'>dns-sd.org</link> for a complete list).</p>
<p>Now let us imagine that a fine young gentleman named Romeo joins the hotspot and that his chat client (actually his mDNS daemon) sends out multicast DNS queries for services of type "presence". To do this, his client essentially reverses the order of DNS record publication (explained above) by asking for pointers to presence services (i.e., PTR records that match "_presence._tcp.local."), querying each service for its service instance and port (i.e., SRV record), mapping each service instance to an IP address (i.e., A record), and finding out additional information about the entity using the service (i.e., TXT record parameters). <note>As explained in the DNS-SD specification, these queries might all be returned in the same answer.</note> As a result, Romeo's client will discover any number of local presence services, among them a service named "juliet@pronto" (with some intriguing TXT record parameters) at IP address 10.2.1.187 and port 5562. Being a romantic fellow, he then initiates a chat with you by opening an XML stream to the advertised IP address and port.</p>
@@ -286,26 +284,24 @@ user@machine._presence._tcp.local <ttl> SRV <priority> <weight> port-number mach
]]></code>
</li>
<li>
- <p>A TXT record whose name is the same as the SRV record and whose value follows the format defined in the DNS-SD specification, as further described in the <link url='#txt'>TXT Record</link> section of this document (note: the line breaks are provided only for the sake of readability):</p>
+ <p>A TXT record whose name is the same as the SRV record and whose value follows the format described in the <link url='#txt'>TXT Record</link> section of this document, consisting of a set of strings that typically represent a series of key-value pairs such as the following:</p>
<code><![CDATA[
-user@machine._presence._tcp.local. IN TXT "
- 0x##txtvers=1
- 0x##1st=user-first-name"
- 0x##email=user-email-address"
- 0x##hash=entity-capabilities-algorithm"
- 0x##jid=user-jabber-id"
- 0x##last=user-last-name"
- 0x##msg=freeform-availability-status"
- 0x##n=entity-capabilities-application-name"
- 0x##nick=user-nickname"
- 0x##node=application-identifier"
- 0x##n=entity-capabilities-operating-system"
- 0x##phsh=sha1-hash-of-avatar"
- 0x##port.p2pj=5562"
- 0x##status=avail-away-or-dnd"
- 0x##vc=capabilities-string"
- 0x##ver=entity-capabilities-identity"
- "
+txtvers=1
+1st=user-first-name
+email=user-email-address
+hash=entity-capabilities-algorithm
+jid=user-jabber-id
+last=user-last-name
+msg=freeform-availability-status
+n=entity-capabilities-application-name
+nick=user-nickname
+node=application-identifier
+n=entity-capabilities-operating-system
+phsh=sha1-hash-of-avatar
+port.p2pj=5562
+status=avail-away-or-dnd
+vc=capabilities-string
+ver=entity-capabilities-identity
]]></code>
<p>Note: The DNS-SD specification stipulates that the TXT record MUST be published, but that it MAY contain no more than a single zero byte (e.g., if the user does not wish to publish any personal information).</p>
</li>
@@ -319,35 +315,27 @@ juliet@pronto._presence._tcp.local. SRV 5562 pronto.local.
pronto.local. A 10.2.1.187
-juliet@pronto._presence._tcp.local. IN TXT "
- 0x09txtvers=1
- 0x0A1st=Juliet
- 0x18email=juliet@capulet.lit
- 0x0Ahash=sha-1
- 0x16jid=juliet@capulet.lit
- 0x0Clast=Capulet
- 0x18msg=Hanging out downtown
- 0x0Anick=JuliC
- 0x1Anode=http://www.adiumx.com
- 0x2Dphsh=a3839614e1a382bcfebbcf20464f519e81770813
- 0x0Eport.p2pj=5562
- 0x0Cstatus=avail
- 0x06vc=CA!
- 0x20ver=QgayPKawpkPSDYmwT/WM94uAlu0=
- "
+juliet@pronto._presence._tcp.local. IN TXT
+ "txtvers=1"
+ "1st=Juliet"
+ "email=juliet@capulet.lit "
+ "hash=sha-1"
+ "jid=juliet@capulet.lit"
+ "last=Capulet"
+ "msg=Hanging out downtown"
+ "nick=JuliC"
+ "node=http://www.adiumx.com"
+ "phsh=a3839614e1a382bcfebbcf20464f519e81770813"
+ "port.p2pj=5562"
+ "status=avail"
+ "vc=CA!"
+ "ver=QgayPKawpkPSDYmwT/WM94uAlu0=""
]]></code>
<p>The IPv4 and IPv6 addresses associated with a machine might vary depending on the local network to which the machine is connected. For example, on an Ethernet connection the physical address might be "192.168.0.100" but when the machine is connected to a wireless network the physical address might change to "10.10.1.187". See <cite>RFC 3927</cite> for details.</p>
<p>If the machine name asserted by a client is already taken by another machine on the network, the client MUST assert a different machine name, which SHOULD be formed by adding the character "-" and digit "1" to the end of the machine name string (e.g., "pronto-1"), adding the character "-" and digit "2" if the resulting machine name is already taken (e.g., "pronto-2"), and similarly incrementing the digit until a unique machine name is constructed.</p>
<p>If the username asserted by a client is already taken by another application on the machine, the client MUST assert a different username, which SHOULD be formed by adding the character "-" and digit "1" to the end of the username string (e.g., "juliet-1"), adding the character "-" and digit "2" if the resulting username is already taken (e.g., "juliet-2"), and similarly incrementing the digit until a unique username is constructed.</p>
<section2 topic='TXT Record' anchor='txt'>
- <p>DNS-SD enables service definitions to include a TXT record that specifies parameters to be used in the context of the relevant service type. The name of the TXT record is the same as that of the SRV record (i.e., "user@machine._presence._tcp.local."). When the TXT record is sent over the wire, its value is a binary object that contains one or more strings, where (1) each string is a parameter that usually takes the form of a key-value pair and (2) the parameters are separated by a single-length byte ("0x##") that specifies the length of the parameter itself. For detailed information about the format of the TXT record value, refer to the DNS-SD specification.</p>
- <p class='box'>Note: The format used for <em>publishing</em> the TXT record value to the mDNS daemon depends on the mDNS daemon in use, and might not follow the binary format described here (e.g., it might consist of a series of quoted strings, one for each parameter).</p>
- <p>The following truncated example illustrates the wire format.</p>
- <code><![CDATA[
---------------------------------------------------------------------------
-| 0x09 | txtvers=1 | 0x0A | 1st=Juliet | 0x18 | email=juliet@capulet.lit |
---------------------------------------------------------------------------
- ]]></code>
+ <p>DNS-SD enables service definitions to include a TXT record that specifies parameters to be used in the context of the relevant service type. The name of the TXT record is the same as that of the SRV record (i.e., "user@machine._presence._tcp.local."). The value of the TXT record is one or more strings, where each string is a parameter that usually takes the form of a key-value pair.</p>
<p>In the context of serverless messaging, the following rules apply:</p>
<ol>
<li>The entire TXT record needs to comply with the suggested maximum TXT record size (see Section 6.3 of the DNS-SD specification).</li>

0 comments on commit 839bc52

Please sign in to comment.