XEP-0174: Link-Local Messaging

This document describes how to establish XMPP-like communications over local networks using zero-configuration networking.

NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the XSF standards process.

Document Information

Series: XEP
Number: 0174
Publisher: XMPP Standards Foundation
Status: Proposed
Type: Standards Track
Version: 0.15
Last Updated: 2007-05-14
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, RFC 3927, draft-cheshire-dnsext-dns-sd, draft-cheshire-dnsext-multicastdns
Supersedes: None
Superseded By: None
Short Name: N/A
Wiki Page: <http://wiki.jabber.org/index.php/Link-Local Messaging (XEP-0174)>

Author Information

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the XSF-IETF list may also be appropriate (see <http://mail.jabber.org/mailman/listinfo/jsf-ietf> for details).

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Table of Contents

1. Introduction

XMPP as defined in RFC 3920 [1] does not support direct client-to-client interactions, since it requires authentication with a server: an XMPP client is allowed access to the network only once it has authenticated with a server, and the server must not grant access if authentication fails for any reason. If an unauthenticated client attempts to communicate directly with another client, such communication will fail because all XMPP communications are sent through one or more servers and a client cannot inject messages onto the network without first authenticating with a server.

However, it is possible to establish an XMPP-like communications system on a local network using zero-configuration networking. In this situation, the clients obviate the XMPP requirement for authentication with a server by relying on zero-configuration networking to establish link-local communication using the _presence._tcp DNS SRV service type. Once discovery has been completed, the clients are then able to exchange messages and other structured data using the XMPP <message/> and <iq/> stanzas. Note well that such communications are restricted to the local network because of how zero-configuration networking works. It is impossible for clients that communicate via link-local addresses to insert messages into an XMPP network, which is why this kind of local "mesh" is most accurately referred to as an XMPP-like system that exists outside the context of existing XMPP networks (though see the Security Considerations regarding the ability to "forward" messages from a local mesh to an XMPP network or vice-versa).

Such a local "mesh" can be quite valuable in certain circumstances. For instance, participants in a trade show or conference, users of the same WiFi hotspot, or employees on the same local area network can communicate without the need for a pre-configured server. For this reason, support for link-local messaging has been a feature of Apple's iChat client when operating in Bonjour (formerly Rendezvous) mode. Because it is desirable for other Jabber clients to support such functionality, this document describes how to use zero-configuration networking as the basis for link-local communication.

2. Glossary

Table 1: Terminology

3. DNS Records

In order to advertise its availability for link-local messaging, a client MUST publish four different kinds of DNS records:

1. An address ("A" or "AAAA") record of the following form: [5]

   machine-name.local. A ip-address
         

2. An "SRV" record (see RFC 2782 [6]) of the following form:

   _presence._tcp <ttl> IN SRV <priority> <weight> port-number username@machine-name.local. 
         

3. A "PTR" record (see RFC 2317 [7] and RFC 1886 [8]) of the following form:

   _presence._tcp.local. port-number IN PTR username@machine-name._presence._tcp.local.
         

4. Optionally, various "TXT" records (see RFC 1464 [9]) of the following form, as further described in to the TXT Records section of this document:

   <owner> IN <ttl> TXT "1st=user-first-name"
   <owner> IN <ttl> TXT "email=user-email-address"
   <owner> IN <ttl> TXT "ext=optional-list-of-extensions"
   <owner> IN <ttl> TXT "jid=user-jabber-id"
   <owner> IN <ttl> TXT "last=user-last-name"
   <owner> IN <ttl> TXT "msg=freeform-availability-status"
   <owner> IN <ttl> TXT "nick=user-nickname"
   <owner> IN <ttl> TXT "node=application-identifier"
   <owner> IN <ttl> TXT "phsh=sha1-hash-of-avatar"
   <owner> IN <ttl> TXT "port.p2pj=5298"
   <owner> IN <ttl> TXT "status=avail-away-or-dnd"
   <owner> IN <ttl> TXT "txtvers=1"
   <owner> IN <ttl> TXT "vc=capabilities-string"
   <owner> IN <ttl> TXT "ver=application-version"
         

The "machine-name" is the name of the computer, the "username" is the system username of the principal currently logged into the computer, the "port" may be any unassigned port number, and the "ip-address" is the physical address of the computer on the local network.

So, for example, if the machine name is "roundabout", the username is "stpeter", the chosen port is "5526", the IP address is "10.2.1.187", and the personal information is that associated with the author of this document, the DNS records would be as follows:

roundabout.local. A 10.2.1.187

_presence._tcp IN SRV 5526 stpeter@roundabout.local. 

_presence._tcp.local. 5526 IN PTR stpeter@roundabout._presence._tcp.local.

psa IN TXT "1st=Peter"
psa IN TXT "email=stpeter@jabber.org"
psa IN TXT "ext=rcd sgc auxvideo sgs mvideo avavail avcap maudio"
psa IN TXT "jid=stpeter@jabber.org"
psa IN TXT "last=Saint-Andre"
psa IN TXT "msg=IETF 66 Montreal"
psa IN TXT "nick=stpeter"
psa IN TXT "node=http://www.apple.com/ichat/caps"
psa IN TXT "phsh=a3839614e1a382bcfebbcf20464f519e81770813"
psa IN TXT "port.p2pj=5298"
psa IN TXT "status=avail"
psa IN TXT "txtvers=1"
psa IN TXT "vc=CA!"
psa IN TXT "ver=524"

  

The IPv4 and IPv6 addresses associated with a machine may vary depending on the local network to which the machine is connected. For example, on an Ethernet connection the physical address might be "10.2.1.187" but when the machine is connected to a wireless network, its physical address might change to "10.10.1.179".

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., "roundabout-1"), adding the character "-" and digit "2" if the resulting machine name is already taken (e.g., "roundabout-2"), and similarly incrementing the digit until a unique machine name is constructed.

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., "stpeter-1"), adding the character "-" and digit "2" if the resulting username is already taken (e.g., "stpeter-2"), and similarly incrementing the digit until a unique username is constructed.

4. Discovering Other Users

In order to discover other users, a client sends an mDNS request for PTR records that match "_presence_tcp.local.". The client then receives replies from all machines that advertise support for link-local messaging. [11] The client MAY then find out detailed information about each machine by sending SRV and TXT queries to "username@machine-name._presence._tcp.local." for each machine (however, to preserve bandwidth, the client SHOULD NOT send these queries unless it is about to initiate communications with the other user, and it MUST cancel the queries after it has received a response). Note: The presence name to be used for display in a link-local "roster" SHOULD be obtained from the <Instance> portion of the received PTR record for each user; however, the client MAY instead display a name or nickname derived from the TXT records if available.

5. Exchanging Presence

When the _presence._tcp service is used, presence is exchanged via the format described in the TXT Records section of this document. In particular, presence information is not pushed as in XMPP (see RFC 3921 [12]). Instead, clients listen for presence announcements from other local entities. Recommended rates for sending updates can be found in Multicast DNS.

6. Discovering Capabilities

Because link-local communication does not involve the exchange of XMPP presence, it is not possible to use Entity Capabilities [13] for capabilities discovery. Therefore, it is RECOMMENDED to instead include the node and ver TXT records (and OPTIONAL to include the ext TXT record). The values of these records MUST be the same as the values for the 'node', 'ver', and 'ext' attributes that are advertised for the application in XMPP presence (if any) via the Entity Capabilities protocol as described in XEP-0115.

7. Initiating a Messaging Session

In order to exchange link-local messages, the initiator and recipient MUST first establish XML streams between themselves, as is familiar from RFC 3920.

First, the initiator opens a TCP connection at the IP address and port discovered via the DNS lookup for a local entity and opens an XML stream to the recipient, which SHOULD include 'to' and 'from' address:

Example 1. Opening a Stream

<stream:stream 
        xmlns='jabber:client' 
        xmlns:stream='http://etherx.jabber.org/streams'
        from='stpeter@roundabout'
        to='hildjj@wolfram'
        version='1.0'>
  

Note: If the initiator supports stream features and the other stream-related aspects of XMPP 1.0 as specified in RFC 3920, then it SHOULD include the version='1.0' flag as shown in the previous example.

The recipient then responds with a stream header as well:

Example 2. Stream Header Response

<stream:stream 
        xmlns='jabber:client' 
        xmlns:stream='http://etherx.jabber.org/streams'>
        from='hildjj@wolfram'
        to='stpeter@roundabout'
        version='1.0'>
  

If both the initiator and recipient included the version='1.0' flag, the recipient SHOULD also send stream features as specified in RFC 3920:

Example 3. Recipient Sends Stream Features

<stream:features>
  <starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
</stream:features>
  

The exchange of stream headers results in an unencrypted and unauthenticated channel between the two entities. See the Security Considerations section of this document regarding methods for authenticating and encrypting the stream.

8. Exchanging Messages

Once the streams are established, either entity then can send XMPP message or IQ stanzas by specifying 'to' and 'from' addresses using the logical local addresses: [14]

Example 4. Sending a Message

<message to='hildjj@wolfram' from='stpeter@roundabout'>
  <body>Hey, I'm testing out link-local messaging!</body>
</message>
  

9. Ending a Messaging Session

To end the chat, either party closes the XML stream:

Example 5. Ending the Chat

</stream:stream>
  

The other party then closes the stream in the other direction as well:

Example 6. Closing the Stream

</stream:stream>
  

Both parties then MUST close the TCP connection between them.

10. Going Offline

In order to go offline, a client MUST send a Multicast DNS "Goodbye" packet for the user's PTR record. As a result, all other entities on the local network will receive a Multicast DNS "Remove" event, at which point they MUST cancel any outstanding TXT, SRV, or NULL record queries for the offline user.

11. Implementation Notes

_presence._tcp.local. IN NULL raw-binary-data-here
    

12. Internationalization Considerations

RFC 1035 does not allow characters outside the US-ASCII [16] character range in DNS A records. Therefore the "machine-name" portion of an A record as used for link-local messaging MUST NOT contain characters outside the US-ASCII character range.

Although RFC 2317 and RFC 2782 do not allow characters outside the US-ASCII character range in PTR and SRV records respectively, Section 4.1 of DNS-Based Service Discovery recommends support for UTF-8-encoded Unicode characters in the <Instance> portion of Service Instance Names, which in link-local messaging is the "username@machine-name" portion of the PTR or SRV record. This document adheres to the recommendation in DNS-Based Service Discovery. However, as mentioned above, the "machine-name" portion of the <Instance> portion MUST NOT contain characters outside the US-ASCII range.

Although RFC 1464 does not allow characters outside the US-ASCII character range in TXT records, Section 6.5 of DNS-Based Service Discovery mentions support for UTF-8-encoded Unicode characters in text record values (e.g., values of the TXT "msg" name). This document adheres to the recommendation in DNS-Based Service Discovery.

13. Security Considerations

14. IANA Considerations

DNS-SD service type names are not yet managed by the Internet Assigned Numbers Authority (IANA) [21]. Section 19 of DNS-Based Service Discovery proposes an IANA allocation policy for unique application protocol or service type names. Until the proposal is adopted and in force, Section 19 points to <http://www.dns-sd.org/ServiceTypes.html> regarding registration of service type names for DNS-SD. The current registration is as follows:

The XMPP Registrar has proposed to the maintainer of <http://www.dns-sd.org/ServiceTypes.html> that the registration be changed as follows:

15. XMPP Registrar Considerations

<record>
  <name>The attribute name of the TXT record.</name>
  <desc>A natural-language description of the record.</desc>
  <status>
    The requirements status of the record. Should be one of: 
      - required
      - recommended 
      - optional
      - deprecated
      - obsolete
 </status>
</record>
      

<record>
  <name>1st</name>
  <desc>The given or first name of the user.</desc>
  <status>optional</status>
</record>

<record>
  <name>email</name>
  <desc>
    The email address of the user; may contain a space-separated list 
    of more than one email address.
  </desc>
  <status>optional</status>
</record>

<record>
  <name>ext</name>
  <desc>
    A space-separated list of extensions; the value of this record MUST 
    be the same as that provided via normal XMPP presence (if applicable) 
    in the 'ext' attribute specified in XEP-0115; for details, refer to 
    the Discovering Capabilities section of XEP-0174.
  </desc>
  <status>recommended</status>
</record>

<record>
  <name>jid</name>
  <desc>
    The Jabber ID of the user; may contain a space-separated list of 
    more than one JID.
  </desc>
  <status>recommended</status>
</record>

<record>
  <name>last</name>
  <desc>The family or last name of the user.</desc>
  <status>optional</status>
</record>

<record>
  <name>msg</name>
  <desc>
    Natural-language text describing the user's state. This is 
    equivalent to the XMPP &lt;status/&gt;; element.
  </desc>
  <status>optional</status>
</record>

<record>
  <name>nick</name>
  <desc>A friendly or informal name for the user.</desc>
  <status>recommended</status>
</record>

<record>
  <name>node</name>
  <desc>
    A unique identifier for the application; the value of this record MUST 
    be the same as that provided via normal XMPP presence (if applicable) 
    in the 'node' attribute specified in XEP-0115; for details, refer to 
    the Discovering Capabilities section of XEP-0174.
  </desc>
  <status>recommended</status>
</record>

<record>
  <name>phsh</name>
  <desc>
    The SHA-1 hash of the user's avatar icon or photo. This SHOULD be 
    requested using mDNS in unicast mode by sending a DNS query to the 
    mDNS multicast address (224.0.0.251 or its IPv6 equivalent FF02::FB).
    The client should keep a local cache of icons keyed by hash. If the 
    phsh value is not in the cache, the client should fetch the unknown 
    icon and then cache it. Implementations should also include logic for 
    expiring avatar icons.
  </desc>
  <status>optional</status>
</record>

<record>
  <name>port.p2pj</name>
  <desc>
    The (hardcoded) port for link-local communications. Clients MUST use the 
    port discovered via SRV lookups and MUST ignore the value of this TXT 
    record, which is included only for backwards-compatibility with some 
    older, existing implementations.
  </desc>
  <status>deprecated</status>
</record>

<record>
  <name>status</name>
  <desc>
    The presence availability of the user. Allowable values are "avail", "away", 
    and "dnd", which map to mere XMPP presence (the user is available) and the 
    XMPP &lt;show/&gt; values of "away" and "dnd", respectively; if the status
    record is not included, the status should be assumed to be "avail".
  </desc>
  <status>recommended</status>
</record>

<record>
  <name>txtvers</name>
  <desc>
    The version of the TXT records supported by the client. For backwards 
    compatibility this is hardcoded at "1".
  </desc>
  <status>deprecated</status>
</record>

<record>
  <name>vc</name>
  <desc>
    A flag advertising the user's ability to engage in audio or video 
    conferencing. If the user is able to engage in audio conferencing, 
    the string MUST include the "A" character. If the user is able to 
    engage in video conferencing, the string MUST include the "V" 
    character. If the user is able to engage in conferencing with more 
    than one participant, the string MUST include the "C" character. If 
    the user is not currently engaged in an audio or video conference, 
    the string MUST include the "!" character. The order of characters 
    in the string is immaterial. NOTE: This flag is included only for
    backwards-compatibility; implementations SHOULD use the node, ver, 
    and ext records for more robust capabilities discovery as described 
    in the Discovering Capabilities section of XEP-0174.
  </desc>
  <status>optional</status>
</record>

<record>
  <name>ver</name>
  <desc>
    The application version; the value of this record MUST be the same as that 
    provided via normal XMPP presence (if applicable) in the 'ver' attribute 
    specified in XEP-0115; for details, refer to the Discovering Capabilities 
    section of XEP-0174.
  </desc>
  <status>recommended</status>
</record>

      

16. Acknowledgements

Thanks to Jens Alfke, Justin Karneges, Marc Krochmal, Eric St. Onge, and Sjoerd Simons for their input.

Notes

Revision History

END