xeps/xep-0152.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Reachability Addresses</title>
  <abstract>This document defines an XMPP protocol extension for communicating information about how an entity can be reached temporarily using methods other than the entity's normal JID.</abstract>
  &LEGALNOTICE;
  <number>0152</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>reach</shortname>
  <schemaloc>
    <ns>reach</ns>
    <url>http://www.xmpp.org/schemas/reach.xsd</url>
  </schemaloc>
  &stpeter;
  &hildjj;
  <revision>
    <version>1.0</version>
    <date>2014-02-25</date>
    <initials>XEP Editor (mm)</initials>
    <remark><p>Per a vote of the XMPP Council, advanced specification from Experimental to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2013-12-02</date>
    <initials>psa</initials>
    <remark><p>Further clarified the intent of the protocol.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2013-09-25</date>
    <initials>psa</initials>
    <remark><p>Modified the text and examples to better illustrate the primary use case.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2013-02-05</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect new XMPP RFCs; strengthened security considerations.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2008-10-06</date>
    <initials>psa</initials>
    <remark>
      <ul>
        <li>Modified namespaces to incorporate namespace versioning.</li>
        <li>Removed IQ request-response method.</li>
        <li>Corrected PEP examples.</li>
        <li>Corrected XML schema.</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2006-09-17</date>
    <initials>psa</initials>
    <remark><p>Defined PEP transport.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2005-06-16</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2005-06-07</date>
    <initials>psa/jjh</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>Sometimes it is desirable to augment instant messaging (IM) with another real-time communications medium, such as a voice conversation conducted over the traditional public switched telephone network (PSTN) or Voice over Internet Protocol (VoIP) applications. In order to facilitate this functionality, a user needs to advertise the address(es) at which they can be reached. There are several possible ways to do this:</p>
  <ul>
    <li><p>Publish the address(es) in the user's vCard (see &xep0054; and &xep0292;); this is convenient, but is not very dynamic (e.g., reachability addresses might change when the user moves to a new conference room in an office building).</p></li>
    <li><p>Send the address(es) within a &PRESENCE; stanza; this option is described in the <link url='#transport-presence'>Presence Transport</link> section of this document and is consistent with &rfc6121; since reachability is one aspect of a user's availability for communication.</p></li>
    <li><p>Send address(es) to the appropriate &xep0060; node; this option is described in the <link url='#transport-pep'>PEP Transport</link> section of this document but might not be available at all service providers.</p></li>
  </ul>
  <p>This document defines methods for publishing addresses at which a user can be reached temporarily, as opposed to semi-permanent addresses of the kind that are more appropriately communicated in a user's vCard. We illustrate this usage through the scenario of a user sending a reachability address upon entering a physical conference room and then sending an updated notification (without a reachability address) upon leaving the conference room. Similar scenarios might apply when an XMPP implementation is used with technologies such as WebRTC and in deployments of the combined use of SIP and XMPP ("CUSAX"; &rfc7081;).</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <p>This document addresses the following requirements:</p>
  <ul>
    <li>Enable clients to dynamically publish reachability addresses.</li>
    <li>Minimize network traffic.</li>
  </ul>
</section1>

<section1 topic='Data Format' anchor='format'>
  <p>The following is an example of the data format for reachability addresses:</p>
  <example caption="Data Format for Reachability Addresses"><![CDATA[
<reach xmlns='urn:xmpp:reach:0'>
  <addr uri='tel:+1-303-555-1212'/>
  <addr uri='sip:room123@example.com'/>
</reach>
]]></example>
  <p>When publishing reachability addresses, the &lt;reach/&gt; element MUST contain at least one &lt;addr/&gt; element. Each &lt;addr/&gt; element MUST possess a 'uri' attribute, whose value MUST be the Uniform Resource Identifier (&rfc3986;) or Internationalized Resource Identifier (&rfc3987;) of an alternate communications method for reaching the user.</p>
  <p>The &lt;addr/&gt; element MAY contain one or more &lt;desc/&gt; children whose XML character data is a natural-language description of the address; this element SHOULD possess an 'xml:lang' attribute whose value is a language tag that conforms to &rfc4646; (although the default language MAY be specified at the stanza level; see &rfc6120;). In order to preserve bandwidth, the &lt;desc/&gt; element SHOULD NOT be included when sending reachability data via presence broadcast, but MAY be included when using directed presence or the personal eventing protocol.</p>
  <example caption="Reachability Addresses With Descriptions"><![CDATA[
<reach xmlns='urn:xmpp:reach:0'>
  <addr uri='tel:+1-303-555-1212'>
    <desc xml:lang='en'>Conference room phone</desc>
  </addr>
  <addr uri='sip:room123@example.com'>
    <desc xml:lang='en'>In-room video system</desc>
  </addr>
</reach>
]]></example>
</section1>

<section1 topic='Data Transport' anchor='transport'>
  <p>This document specifies two methods of advertising reachability addresses:</p>
  <ul>
    <li>Presence</li>
    <li>&xep0163; (PEP)</li>
  </ul>
  <p>This document does not recommend one transport method over the other.</p>
  <p>In addition, a contact MAY request a user's reachability addresses in an XMPP &IQ; stanza of type "get" and a user MAY send reachability addresses in an XMPP &MESSAGE; stanza. However, the presence and PEP transport methods are preferred.</p>

  <section2 topic='Presence Transport' anchor='transport-presence'>
    <p>To broadcast reachability addresses in presence information, a user's client includes the &lt;reach/&gt; element in the &PRESENCE; stanza it sends to its server.</p>
    <p>For example, consider someone who walks into a conference room at the office. Via nearfield communication, the user's XMPP client might auto-discover a 'tel:' URI for the room audio system and a 'sip:' URI for the room video system.</p>
    <example caption="User&apos;s Client Includes Reachability Addresses in Presence"><![CDATA[
<presence from='romeo@example.com/mobile'>
  <reach xmlns='urn:xmpp:reach:0'>
    <addr uri='tel:+1-303-555-1212'/>
    <addr uri='sip:room123@example.com'/>
  </reach>
</presence>
]]></example>
    <p>The user's server then broadcasts that presence stanza to all entities who are subscribed to the user's presence:</p>
    <example caption="User&apos;s Server Broadcasts Presence Information"><![CDATA[
<presence from='romeo@montague.net/mobile' to='juliet@capulet.com'>
  <reach xmlns='urn:xmpp:reach:0'>
    <addr uri='tel:+1-303-555-1212'/>
    <addr uri='sip:room123@example.com'/>
  </reach>
</presence>
]]></example>
    <p>(Naturally, a reachability address MAY alternatively be included in directed presence.)</p>
    <p>Upon leaving the conference room, the user's client would send updated presence without the reachability extension.</p>
    <example caption="User&apos;s Client Sends Updated Presence Without Reachability Addresses"><![CDATA[
<presence from='romeo@example.com/mobile'/>
]]></example>
  </section2>

  <section2 topic='Personal Eventing Protocol' anchor='transport-pep'>
    <p>To publish reachability addresses via the personal eventing protocol (<cite>XEP-0163</cite>), the entity publishes data to the "urn:xmpp:reach:0" node.</p>
    <example caption='Entity Publishes Reachability Addresses via PEP'><![CDATA[
<iq type='set'
    from='romeo@example.com'
    to='pubsub.shakespeare.example'
    id='publish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'>
          <addr uri='tel:+1-303-555-1212'>
            <desc xml:lang='en'>Conference room phone</desc>
          </addr>
          <addr uri='sip:room123@example.com'>
            <desc xml:lang='en'>In-room video system</desc>
          </addr>
        </reach>
      </item>
    </publish>
  </pubsub>
</iq>
]]></example>
    <example caption='Subscriber Receives PEP Event with Payload'><![CDATA[
<message from='pubsub.shakespeare.lit'
         to='juliet@capulet.com'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'>
          <addr uri='tel:+1-303-555-1212'>
            <desc xml:lang='en'>Conference room phone</desc>
          </addr>
          <addr uri='sip:room123@example.com'>
            <desc xml:lang='en'>In-room video system</desc>
          </addr>
        </reach>
      </item>
    </items>
  </event>
</message>
]]></example>
    <p>As above, when leaving the conference room the user's client would publish an updated payload indicating that it no longer has any temporary reachability addresses.</p>
    <example caption='Entity Publishes Payload with Empty Reachability Addresses'><![CDATA[
<iq type='set'
    from='romeo@example.com'
    to='pubsub.shakespeare.example'
    id='publish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'/>
      </item>
    </publish>
  </pubsub>
</iq>
]]></example>
  </section2>
</section1>

<section1 topic='Determining Support' anchor='support'>
  <p>If an entity supports reachability addresses, it MUST advertise that fact by returning a feature of "urn:xmpp:reach:0" &VNOTE; in response to a &xep0030; information request.</p>
  <example caption="Service Discovery Information Request"><![CDATA[
<iq from='juliet@capulet.com/balcony'
    id='disco1'
    to='romeo@montague.net/orchard'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption="Service Discovery Information Response"><![CDATA[
<iq from='romeo@montague.net/orchard'
    id='disco1'
    to='juliet@capulet.com/balcony'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:reach:0'/>
  </query>
</iq>
]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>

<section1 topic='Implementation Notes' anchor='impl'>
  <p>To preserve network bandwidth, the sender ought not include the &lt;desc/&gt; element unless that information is deemed necessary to enable communication.</p>
  <p>A recipient ought to attempt communications with reachability addresses in the order that the &lt;addr/&gt; elements appear within the &lt;reach/&gt; element.</p>
</section1>

<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>If included, the &lt;desc/&gt; element SHOULD possess an 'xml:lang' attribute specifying the language of the human-readable descriptive text for a particular address.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>Security considerations for XMPP presence and PEP publication are described in RFC 6120, RFC 6121, XEP-0060, and XEP-0163.</p>
  <p>Advertising a telephone number, SIP URI, or other real-time communication address to multiple contacts in an unencrypted way (e.g., via XMPP presence or PEP in cases where not all hops are TLS-protected) introduces the possibility of information leakage and subsequent attacks such as unsolicited phone calls. Clients are advised to appropriately warn users about the dangers of such attacks. Alternatively, if the address is especially sensitive (say, a hashname &rfc6920; for use in a system that enables direct private communication outside of XMPP), then a client could send it in a message that itself is end-to-end encrypted.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:reach:0</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Namespace Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:reach:0'
    xmlns='urn:xmpp:reach:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0152: http://www.xmpp.org/extensions/xep-0152.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='reach'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='addr'
                    minOccurs='0'
                    maxOccurs='unbounded'
                    type='addrElementType'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='addrElementType'>
    <xs:sequence>
      <xs:element name='desc'
                  minOccurs='0'
                  maxOccurs='unbounded'
                  type='xs:string'/>
    </xs:sequence>
    <xs:attribute name='uri' use='required' type='xs:anyURI'/>
  </xs:complexType>

</xs:schema>
]]></code>
</section1>
</xep>