XEP-xxxx: Presence Decloaking

This specification defines an XMPP protocol extension that enables a user to send directed presence with a request for the target to reciprocate.
  • Simon McVittie
  • Peter Saint-Andre
  • Robert McQueen
© 1999 – 2020 XMPP Standards Foundation. SEE LEGAL NOTICES.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.
Standards track
0.0.2 (2010-01-17)
Document Lifecycle
  1. ProtoXEP

1. Introduction

Various XMPP extensions, such as Jingle (XEP-0166) [1], require additional support from clients, advertised in presence via Entity Capabilities (XEP-0115) [2], 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 Entity Capabilities (XEP-0115) [2] 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; RFC 3261 [3]) 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.

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".

Note: This protocol has already been implemented using an XML namespace of "http://telepathy.freedesktop.org/xmpp/protocol/decloak" but the XMPP Registrar [4] is requested to issue the XMPP URN "urn:xmpp:decloak:0" upon publication of this proposal in the XMPP Extension Protocols (XEP-0001) [5] series.

2. Requirements

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.

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.

3. Scenario

Suppose that Juliet wishes to make a media call to Tybalt, but the two parties do not share presence information in accordance with XMPP IM [6]. Suppose also that Juliet and Tybalt have the following presence, although neither can initially see the other's presence:

Example 1. Initial state
<presence from='juliet@shakespeare.lit/balcony'>
  <status>on the phone</status>
  <c ver="[Juliet's client's caps hash]" .../>

<presence from='tybalt@shakespeare.lit/library'>
  <c ver="[Tybalt's client's caps hash]" .../>

<presence from='tybalt@shakespeare.lit/garden'>
  <status>gone to the library</status>
  <c ver="[Tybalt's client's caps hash]" .../>

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

Example 2. Requesting that a peer decloaks
<presence from='juliet@shakespeare.lit/balcony'
  <c ver="[Juliet's client's caps hash]" .../>
  <decloak xmlns='urn:xmpp:decloak:0' reason='media'/>

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

Example 3. Decloaking in response to a request
<presence from='tybalt@shakespeare.lit/library'
  <c ver="[Tybalt's client's caps hash]" .../>

<presence from='tybalt@shakespeare.lit/garden'
  <c ver="[Tybalt's client's caps hash]" .../>

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.

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

4. Decloaking with a Gateway

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.

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 <decloak/> element.

Example 4. Requesting that a gateway contact shall decloak
<presence from='juliet@shakespeare.lit/balcony'
  <c ver="[Juliet's client's caps hash]" .../>
  <decloak xmlns='urn:xmpp:decloak:0' reason='media'/>

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

Example 5. Decloaking in response to a request
<presence from='romeo%shakespeare.lit@sip.shakespeare.lit'
  <c ver="[SIP gateway's caps hash]" .../>

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

5. The reason Attibute

To signal the type of communication that is desired, the entity that first decloaks MAY include a 'reason' attribute on the <decloak/> element. The following values for the 'reason' attribute are defined:

Presence is requested for a voice and/or video call, e.g. via Jingle RTP Sessions (XEP-0167) [7].
Presence is requested for a plaintext or XHTML-IM (XEP-0071) [8] conversation, e.g. with end-to-end encryption (which requires capabilities to be disclosed).
Presence is requested for one or more file transfers, e.g. via Jingle File Transfer (XEP-0234) [9] or Stream Initiation (XEP-0095) [10].

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.

6. Business Rules

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:

  1. 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.

  2. 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.

7. Security Considerations

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.)

8. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [11].

9. XMPP Registrar Considerations

The XMPP Registrar is requested to issue an initial namespace of "urn:xmpp:decloak:0".

10. XML Schema


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

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>

11. Acknowledgements

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.


Appendix A: Document Information

XMPP Standards Foundation
Standards track
Last Updated
Approving Body
XMPP Council
Superseded By
Short Name

This document in other formats: XML  PDF

Appendix B: Author Information

Simon McVittie
Peter Saint-Andre
Robert McQueen


This XMPP Extension Protocol is copyright © 1999 – 2020 by the XMPP Standards Foundation (XSF).


Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) 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.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements 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".

Appendix G: Notes

1. XEP-0166: Jingle <https://xmpp.org/extensions/xep-0166.html>.

2. XEP-0115: Entity Capabilities <https://xmpp.org/extensions/xep-0115.html>.

3. RFC 3261: Session Initiation Protocol (SIP) <http://tools.ietf.org/html/rfc3261>.

4. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.

5. XEP-0001: XMPP Extension Protocols <https://xmpp.org/extensions/xep-0001.html>.

6. RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc6121>.

7. XEP-0167: Jingle RTP Sessions <https://xmpp.org/extensions/xep-0167.html>.

8. XEP-0071: XHTML-IM <https://xmpp.org/extensions/xep-0071.html>.

9. XEP-0234: Jingle File Transfer <https://xmpp.org/extensions/xep-0234.html>.

10. XEP-0095: Stream Initiation <https://xmpp.org/extensions/xep-0095.html>.

11. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

  1. Version 0.0.2 (2010-01-17)

    Rewrote the introduction, clarified the security considerations, requested issuance of an appropriate URN from the XMPP Registrar.

  2. Version 0.0.1 (2010-01-05)

    First draft.