moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-25 02:32:18 -05:00
Code Issues Releases Wiki Activity

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

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2518 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-11-19 05:21:25 +00:00
parent 39c3101bda
commit 9585d2fdda
1 changed files with 50 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
xep-0174.xml
View File

@ -27,8 +27,8 @@
<registry/> <registry/>
&stpeter; &stpeter;
<revision> <revision>
<version>1.3rc3</version> <version>1.3rc4</version>
<date>in progress, last updated 2008-11-14</date> <date>in progress, last updated 2008-11-18</date>
<initials>psa</initials> <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> <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> </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 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> <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> </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[ <code><![CDATA[
juliet@pronto._presence._tcp.local. IN TXT " txtvers=1
0x09txtvers=1 1st=Juliet
0x0A1st=Juliet email=juliet@capulet.lit
0x18email=juliet@capulet.lit hash=sha-1
0x0Ahash=sha-1 jid=juliet@capulet.lit
0x16jid=juliet@capulet.lit last=Capulet
0x0Clast=Capulet msg=Hanging out downtown
0x18msg=Hanging out downtown nick=JuliC
0x0Anick=JuliC node=http://www.adiumx.com
0x1Anode=http://www.adiumx.com phsh=a3839614e1a382bcfebbcf20464f519e81770813
0x2Dphsh=a3839614e1a382bcfebbcf20464f519e81770813 port.p2pj=5562
0x0Eport.p2pj=5562 status=avail
0x0Cstatus=avail vc=CA!
0x06vc=CA! ver=QgayPKawpkPSDYmwT/WM94uAlu0=
0x20ver=QgayPKawpkPSDYmwT/WM94uAlu0=
"
]]></code> ]]></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>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> <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> ]]></code>
</li> </li>
<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[ <code><![CDATA[
user@machine._presence._tcp.local. IN TXT " txtvers=1
0x##txtvers=1 1st=user-first-name
0x##1st=user-first-name" email=user-email-address
0x##email=user-email-address" hash=entity-capabilities-algorithm
0x##hash=entity-capabilities-algorithm" jid=user-jabber-id
0x##jid=user-jabber-id" last=user-last-name
0x##last=user-last-name" msg=freeform-availability-status
0x##msg=freeform-availability-status" n=entity-capabilities-application-name
0x##n=entity-capabilities-application-name" nick=user-nickname
0x##nick=user-nickname" node=application-identifier
0x##node=application-identifier" n=entity-capabilities-operating-system
0x##n=entity-capabilities-operating-system" phsh=sha1-hash-of-avatar
0x##phsh=sha1-hash-of-avatar" port.p2pj=5562
0x##port.p2pj=5562" status=avail-away-or-dnd
0x##status=avail-away-or-dnd" vc=capabilities-string
0x##vc=capabilities-string" ver=entity-capabilities-identity
0x##ver=entity-capabilities-identity"
"
]]></code> ]]></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> <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> </li>
@ -319,35 +315,27 @@ juliet@pronto._presence._tcp.local. SRV 5562 pronto.local.
pronto.local. A 10.2.1.187 pronto.local. A 10.2.1.187
juliet@pronto._presence._tcp.local. IN TXT " juliet@pronto._presence._tcp.local. IN TXT
0x09txtvers=1 "txtvers=1"
0x0A1st=Juliet "1st=Juliet"
0x18email=juliet@capulet.lit "email=juliet@capulet.lit "
0x0Ahash=sha-1 "hash=sha-1"
0x16jid=juliet@capulet.lit "jid=juliet@capulet.lit"
0x0Clast=Capulet "last=Capulet"
0x18msg=Hanging out downtown "msg=Hanging out downtown"
0x0Anick=JuliC "nick=JuliC"
0x1Anode=http://www.adiumx.com "node=http://www.adiumx.com"
0x2Dphsh=a3839614e1a382bcfebbcf20464f519e81770813 "phsh=a3839614e1a382bcfebbcf20464f519e81770813"
0x0Eport.p2pj=5562 "port.p2pj=5562"
0x0Cstatus=avail "status=avail"
0x06vc=CA! "vc=CA!"
0x20ver=QgayPKawpkPSDYmwT/WM94uAlu0= "ver=QgayPKawpkPSDYmwT/WM94uAlu0=""
"
]]></code> ]]></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>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 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> <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'> <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>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 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>In the context of serverless messaging, the following rules apply:</p> <p>In the context of serverless messaging, the following rules apply:</p>
<ol> <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> <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>