xeps/inbox/decloak.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY TYBALTCAPS "&lt;c ver=&quot;[Tybalt's client's caps hash]&quot; .../&gt;">
<!ENTITY JULIETCAPS "&lt;c ver=&quot;[Juliet's client's caps hash]&quot; .../&gt;">
<!ENTITY GWCAPS "&lt;c ver=&quot;[SIP gateway's caps hash]&quot; .../&gt;">
<!ENTITY DECLOAK "http://telepathy.freedesktop.org/xmpp/protocol/decloak">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Presence Decloaking</title>
  <abstract>This specification defines an XMPP protocol extension that enables a user to send directed presence with a request for the target to reciprocate.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards track</type>
  <sig>None</sig>
  <approver>Council</approver>
  <dependencies/>
  <supersedes/>
  <supersededby/>
  <shortname>NOT YET ASSIGNED</shortname>
  <author>
    <firstname>Simon</firstname>
    <surname>McVittie</surname>
    <email>simon.mcvittie@collabora.co.uk</email>
    <jid>simon.mcvittie@collabora.co.uk</jid>
  </author>
  &stpeter;
  &robmcqueen;
  <revision>
    <version>0.0.2</version>
    <date>2010-01-17</date>
    <initials>psa</initials>
    <remark><p>Rewrote the introduction, clarified the security considerations, requested issuance of an appropriate URN from the XMPP Registrar.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2010-01-05</date>
    <initials>smcv/psa/rm</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>

  <p>Various XMPP extensions, such as &xep0166;, require additional support from clients, advertised in presence via &xep0115;, or require that IQ stanzas are sent to a particular resource. For instance, Jingle calls can be made only by sending an IQ to a particular resource. However, two parties who wish to communicate do not always shared presence information and therefore cannot use &xep0115; to determine the correct resource (full JID) for communication. Indeed, one of the parties might not even use XMPP: e.g., a remote user on the other side of a gateway to a network based on the Session Initiation Protocol (SIP; &rfc3261;) or to the Public Switched Telephone Network (PSTN). It would be helpful if a user could make a call through such a gateway by typing the SIP URI or telephone number of an arbitrary contact, without first exchanging presence.</p>

  <p>This document defines an XML protocol extension to request that enables two parties to temporarily reveal their presence to each other through an intentional presence leak that we call "decloaking".</p>

  <p>Note: This protocol has already been implemented using an XML namespace of "&DECLOAK;" but the &REGISTRAR; is requested to issue the XMPP URN "urn:xmpp:decloak:0" upon publication of this proposal in the &xep0001; series.</p>

</section1>
<section1 topic='Requirements' anchor='reqs'>

  <p>An entity should be able to attempt to initiate a communication session that requires IQs and/or capability negotiation (Jingle, a file transfer, end-to-end encryption, or other similar communication modes) with an arbitrary entity.</p>

  <p>If the receiving entity agrees to divulge their presence in this way, minimal presence (with no 'type' attribute, &SHOW; element, avatar hash, etc.) and capabilities should be communicated to the initiating entity, so that the initiating entity can continue to initiate the communication session.</p>

</section1>

<section1 topic='Scenario' anchor='scenario'>

  <p>Suppose that Juliet wishes to make a media call to Tybalt, but the two parties do not share presence information in accordance with &xmppim;.  Suppose also that Juliet and Tybalt have the following presence, although neither can initially see the other's presence:</p>

  <example caption="Initial state">
    <![CDATA[
<presence from='juliet@shakespeare.lit/balcony'>
  <show>dnd</show>
  <status>on the phone</status>
  ]]>&JULIETCAPS;<![CDATA[
</presence>

<presence from='tybalt@shakespeare.lit/library'>
  <show>dnd</show>
  <status>researching</status>
  ]]>&TYBALTCAPS;<![CDATA[
</presence>

<presence from='tybalt@shakespeare.lit/garden'>
  <show>xa</show>
  <status>gone to the library</status>
  ]]>&TYBALTCAPS;<![CDATA[
</presence>
  ]]></example>

  <p>Juliet requests that Tybalt divulges his availability and capabilities, by sending directed presence to his bare JID &lt;tybalt@shakespeare.lit&gt;, where the presence stanza contains a &lt;decloak/&gt; element.</p>

  <example caption="Requesting that a peer decloaks"><![CDATA[
<presence from='juliet@shakespeare.lit/balcony'
          to='tybalt@shakespeare.lit'>
  ]]>&JULIETCAPS;<![CDATA[
  <decloak xmlns='urn:xmpp:decloak:0' reason='media'/>
</presence>
  ]]></example>

  <p>Tybalt MAY decloak one or more resources in response, by sending directed presence from those resource(s) to Juliet's bare JID.</p>

  <example caption="Decloaking in response to a request">
    <![CDATA[
<presence from='tybalt@shakespeare.lit/library'
          to='juliet@shakespeare.lit'>
  ]]>&TYBALTCAPS;<![CDATA[
</presence>

<presence from='tybalt@shakespeare.lit/garden'
          to='juliet@shakespeare.lit'>
  ]]>&TYBALTCAPS;<![CDATA[
</presence>
  ]]></example>

  <p>Once Juliet has received the decloaked presence from Tybalt, if necessary she can perform service discovery to find out the meaning of the entity capabilities hashes (if unknown), then proceed to make a Jingle call, initiate a file transfer, or complete some other use case.</p>

  <p>Alternatively, Tybalt MAY ignore the request (in particular, this will happen for any resource that does not implement this specification).</p>

</section1>

<section1 topic='Decloaking with a Gateway' anchor='gateway'>

  <p>Let us now suppose that Juliet wishes to make a media call to Romeo, who does not use XMPP but who has a SIP URI of sip:romeo@shakespeare.lit, which can be called via an XMPP-to-SIP gateway.</p>

  <p>Juliet requests that the SIP contact representing Romeo on the gateway shall divulge its availability and capabilities, by sending directed presence to its bare JID at the gateway containing a &lt;decloak/&gt; element.</p>

  <example caption="Requesting that a gateway contact shall decloak">
    <![CDATA[
<presence from='juliet@shakespeare.lit/balcony'
          to='romeo%shakespeare.lit@sip.shakespeare.lit'>
  ]]>&JULIETCAPS;<![CDATA[
  <decloak xmlns='urn:xmpp:decloak:0' reason='media'/>
</presence>
  ]]></example>

  <p>In response, the SIP gateway automatically decloaks on behalf of that JID, in order to tell Juliet what the gateway's capabilities are.</p>

  <example caption="Decloaking in response to a request">
    <![CDATA[
<presence from='romeo%shakespeare.lit@sip.shakespeare.lit'
          to='juliet@shakespeare.lit'>
  ]]>&GWCAPS;<![CDATA[
</presence>
  ]]></example>

  <p>As above, Juliet can now complete service discovery and any protocol-specific use cases.</p>

</section1>

<section1 topic='The reason Attibute' anchor='reason'>
  <p>To signal the type of communication that is desired, the entity that first decloaks MAY include a 'reason' attribute on the &lt;decloak/&gt; element. The following values for the 'reason' attribute are defined:</p>

  <dl>
    <dt>media</dt>
    <dd>Presence is requested for a voice and/or video call, e.g. via &xep0167;.</dd>

    <dt>text</dt>

    <dd>Presence is requested for a plaintext or &xep0071; conversation, e.g. with end-to-end encryption (which requires capabilities to be disclosed).</dd>

    <dt>file</dt>
    <dd>Presence is requested for one or more file transfers, e.g. via &xep0234; or &xep0095;.</dd>
  </dl>

  <p>Inclusion of the 'reason' attribute can be interpreted by the receiving client as a signal that communication is about to start; for instance, a call accept/reject dialog could double as a UI for accepting or rejecting a decloaking request.</p>

</section1>

<section1 topic='Business Rules' anchor='bizrules'>

  <p>To limit the extent of the presence leak, the receiving entity SHOULD send only bare presence without the XMPP &PRIORITY;, &SHOW;, or &STATUS; element. Unfortunately, this has two implications:</p>

  <ol>
    <li><p>The initiating entity cannot know which of the receiving entity's resources is more likely to engage in communication. This might imply that the initiating entity will need to send a session initiation request or other communication to more than one of the receiving entity's resources (and then retract the session initiation requests that are not answered by the receiving entity). Solutions to that problem are out of scope for this specification.</p></li>
    <li><p>Set up of a session might be delayed (e.g., because in Jingle it is desirable to start negotiating candidates as soon as possible but a user interface that prompts the receiving entity to explicitly approve of divulging presence will tend to delay call setup). As a result, it may be advantageous to have a way to configure unconditional decloaking in certain deployments, at least within the same trust domain.</p></li>
  </ol>

</section1>

<section1 topic='Security Considerations' anchor='security'>

  <p>Because decloaking is a presence leak (albeit intentional), an XMPP client that implements the receiving side of this specification MUST disable decloaking by default and MUST enable the feature only as a result of explicit user configuration. (Gateways and other non-user entities MAY divulge their own presence and capabilities unconditionally, if that is appropriate for the service policy at the gateway.)</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'>
  <p>The XMPP Registrar is requested to issue an initial namespace of "urn:xmpp:decloak:0".</p>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<xs:schema
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  targetNamespace='urn:xmpp:decloak:0'
  xmlns='urn:xmpp:decloak:0'
  elementFormDefault='qualified'>

  <xs:element name='decloak'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='reason' use='optional' type='xs:string'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>
  ]]></code>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>The need for this protocol extension, and a rough proposal for solving the problem, were originally determined at XMPP Summit 5 in the summer of 2007. Thanks to Diana Cionoiu, Justin Karneges, and Justin Uberti for their input to those discussions.</p>
</section1>

</xep>