XEP-0235: Direct Invitations

This specification defines an XMPP extension for generating, requesting, and providing invitations, which can be used in the context of Multi-User Chat rooms and other services.

WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.

Document Information

Series: XEP
Number: 0235
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.1
Last Updated: 2008-03-05
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Direct Invitations (XEP-0235)>

Author Information

Legal Notices

Discussion Venue

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

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

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

Multi-User Chat [1] includes a protocol for inviting a contact to a chatroom. That protocol results in the sending of an invitation from the chatroom to the contact (a "mediated invitation"), not from the inviting user to the contact (a "direct invitation"). Because use of Server-Based Privacy Rules [2] may result in blocking of XML stanzas from entities that are not in the contact's roster, mediated invitations may never be delivered to the contact. Therefore, this specification defines an XMPP extension that enables a user to directly send an invitation to a contact, thus routing around the blocking of mediated invitations. While the main use case for this protocol is multi-user chat, nothing in the protocol prevents it from being used to invite contacts to other types of services, such as Publish-Subscribe [3] services or future collaboration services.

2. Obtaining an Invitation

In order to obtain an invitation that can be directly sent to a contact, a user requests an invitation token from the relevant service. For example, let us imagine that the user <crone1@shakespeare.lit> wishes to invite the contact <hecate@shakespeare.lit> to the chatroom <darkcave@macbeth.shakespeare.lit>. The user would send the following request to the room (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

Example 1. Token request

<iq from='crone1@shakespeare.lit/desktop'
    id='request1'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'>
  <invitation 
      for='hecate@shakespeare.lit'
      xmlns='urn:xmpp:tmp:invite'/>
</iq>
  

If the room supports the direct invitation protocol and the user is allowed to invite contacts to the room, the room returns an invitation token to the user.

Example 2. Token response

<iq from='darkcave@macbeth.shakespeare.lit'
    id='request1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <invitation 
      expires='2007-02-21T23:59:59Z'
      for='hecate@shakespeare.lit'
      jid='darkcave@macbeth.shakespeare.lit'
      xmlns='urn:xmpp:tmp:invite'>
    37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
  </invitation>
</iq>
  

The syntax of the invitation is as follows.

• The 'expires' attribute defines a date and time when the invitation expires. Inclusion of this attribute is OPTIONAL. If included, it MUST be a DateTime as specified in XMPP Date and Time Profiles [4].
• The 'for' attribute defines the JabberID of the invitee. Inclusion of this attribute is REQUIRED.
• The 'jid' attribute defines the JabberID of the service to which the invitee is being invited. Inclusion of this attribute is REQUIRED.
• The XML character data of the <invitation/> element is the invitation token itself. The token MAY be generated according to any method deemed appropriate by the service implementation. It is RECOMMENED that the token be the hexadecimal representation of a Keyed-Hash Message Authentication Code (see HMAC [5]) generated using the SHA256 hashing algorithm (see SHA [6]), as described elsewhere in this document.

3. Sharing an Invitation

The user can then send the invitation to the contact in an XMPP message stanza:

Example 3. Sharing the invitation

<message from='crone1@shakespeare.lit/desktop' to='hecate@shakespeare.lit'>
  <invitation 
      expires='2007-02-21T23:59:59Z'
      for='hecate@shakespeare.lit'
      jid='darkcave@macbeth.shakespeare.lit'
      xmlns='urn:xmpp:tmp:invite'>
    37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
  </invitation>
</message>
  

4. Using an Invitation

The contact then MUST then determine the identity of the service (via Service Discovery [7]) so that it can determine how to use the invitation.

In this example, the service is a multi-user chat service. Therefore if the contact wishes to join the designated chatroom, it will include the invitation in its join request.

Example 4. Chatroom join with invitation

<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'
  <invitation xmlns='urn:xmpp:tmp:invite'>
    37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
  </invitation>
</iq>
  

If the invitation is acceptable, the service will then allow the contact to enter the room.

Note: Detailed error flows will be added to a future version of this specification.

5. Security Considerations

To follow.

6. IANA Considerations

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

7. XMPP Registrar Considerations

8. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

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

  <xs:element name='invitation'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='expires' type='xs:string' use='optional'/>
          <xs:attribute name='for' type='xs:string' use='optional'/>
          <xs:attribute name='jid' type='xs:string' use='optional'/>
          <xs:attribute name='node' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
  

9. Acknowledgements

Thanks to Dave Cridland for his suggestions. Aspects of this specification were inspired by RFC 4467 [11].

Notes

Revision History

END