moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity
xeps/xep-0155.xml

561 lines
26 KiB
XML
Raw Blame History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Chat Session Negotiation</title>
<abstract>This document specifies a feature negotiation profile for initiating a one-to-one chat session.</abstract>
&LEGALNOTICE;
<number>0155</number>
<status>Experimental</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0020</spec>
<spec>JEP-0068</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>chatneg</shortname>
&stpeter;
&ianpaterson;
<revision>
<version>0.8</version>
<date>2006-10-02</date>
<initials>ip</initials>
<remark><p>Added continue field and optional terminate acknowledgement; specified renegotiation failure proceedure; added context to Introduction; changed unavailable presence handling; renamed logging field to otr.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-07-14</date>
<initials>psa</initials>
<remark><p>Added secure field from JEP-0116.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2006-07-13</date>
<initials>psa</initials>
<remark><p>Specified that a client must re-initiate if it receives presence unavailable; changed JEP type to Standards Track.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2006-01-24</date>
<initials>psa</initials>
<remark><p>Added renegotiate use case.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2006-01-03</date>
<initials>psa</initials>
<remark><p>Added terminate use case; further specified mapping to SIP.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2005-12-30</date>
<initials>psa</initials>
<remark><p>Further specified use of id attribute and thread element.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2005-07-15</date>
<initials>psa</initials>
<remark><p>Further described contexts in which chat session negotiation could be useful; added more examples; added reference to SIP RFC and explained basic mapping to SIP INVITE method; added Jabber Registrar considerations.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2005-07-14</date>
<initials>psa</initials>
<remark><p>Initial JEP version.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2005-07-12</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The traditional model for one-to-one chat "sessions" in Jabber/XMPP is for a user to simply send a message to a contact without any formal negotiation of chat session parameters (e.g., see &xmppim;). This informal approach to initiation of a chat session is perfectly acceptable in many contexts, environments, and cultures. However, it may be desirable to formally request the chat and negotiate its parameters before beginning the chat session in some circumstances, such as:</p>
<ul>
<li>Whenever parameters specific to a chat session must be agreed. e.g., security and privacy parameters (see &jep0116; and &jep0136;).</li>
<li>The parties are unknown to each other, have not exchanged presence, or have not discovered their respective capabilities via &jep0030; or &jep0115;.</li>
<li>When an XMPP-based system interfaces with a SIP-based system built on top of &rfc3261;. <note>In essence, a chat state negotiation request as specified herein is functionally equivalent to a SIP INVITE request, and acceptance of such a request is functionally equivalent to sending a SIP 200 OK response; see Section 17 of <cite>RFC 3261</cite>.</note></li>
<li>Within an organization or culture in which one would not simply begin chatting with another person (e.g., a superior) without first receiving permission to do so.</li>
</ul>
<p>This proposal defines best practices for such a negotiation, re-using the protocol defined in &jep0020;.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Initiating a Chat' anchor='initiate'>
<p>In order to initiate a negotiated chat session, the initiating party ("user") sends a &MESSAGE; stanza to the receiving party ("contact") containing a &lt;feature/&gt; child qualified by the 'http://jabber.org/protocol/feature-neg' namespace. The &MESSAGE; stanza MUST NOT contain a &BODY; child element (as specified in &rfc3921;). The &MESSAGE; stanza is used because the user does not necessarily know which of the contact's resources is most available (or indeed if the contact is online). The &MESSAGE; stanza type SHOULD be "normal" (either explicitly or by non-inclusion of the 'type' attribute). The stanza SHOULD include an 'id' attribute and MUST contain a &THREAD; element for tracking purposes (where the newly-generated ThreadID is unique to the proposed session). The data form MUST contain a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/chatneg" and MUST contain a boolean field named "accept". &BOOLEANNOTE;</p>
<p>The following is an example of a negotiation request:</p>
<example caption="User requests chat session"><![CDATA[
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>true</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Disable All Message Logging?'
type='boolean'
var='otr'>
<value>1</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>In the foregoing example, Romeo requests a chat with Juliet and also queries her regarding whether she wants to disable all message logging (see &jep0136;) <note>A client MUST NOT set the 'otr' field to 'true' unless it has confirmed that its server will allow it to switch off Automated Archiving (see <cite>Message Archiving</cite>).</note> and support &jep0071; and &jep0085; extensions during this chat session. (Note: These fields are examples only; a full set of chat session negotiation parameters will be registered as described in the <link url='#registrar'>Jabber Registrar Considerations</link> section of this document.)</p>
<p>Juliet's server delivers Romeo's request to her most available resource (which happens to be "balcony").</p>
<p>In any response to the request, the contact's client MUST mirror the 'id' attribute and &THREAD;value so that the user's client can correctly track the response.</p>
<p>We assume that Juliet accepts the chat and specifies that she does not want to log messages or use XHTML formatting but that she does want to use Chat State Notifications:</p>
<example caption="Contact accepts offer and specifies parameters"><![CDATA[
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='accept'>
<value>true</value>
</field>
<field var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field var='http://jabber.org/protocol/chatstates'>
<value>1</value>
</field>
<field var='otr'>
<value>1</value>
</field>
<field var='secure'>
<value>1</value>
</field>
<field var='reason'>
<value>Sure, let's talk!</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>However, it could be that Juliet is busy so she declines the invitation.</p>
<example caption="Contact declines offer and specifies reason"><![CDATA[
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='accept'>
<value>0</value>
</field>
<field var='reason'>
<value>Sorry, can't chat now! How about tonight?</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>If Juliet's client does not support feature negotiation or does not support the "http://jabber.org/protocol/chatneg" FORM_TYPE, it SHOULD return a &unavailable; error. However, if Juliet does not want to reveal her presence to Romeo for whatever reason, or she is using a legacy client that does not support returning a &unavailable; error, then her client MAY return no error. In this case Romeo MAY, proceed to send stanzas to Juliet outside the context of a negotiated chat session.</p>
<example caption="Contact returns service unavailable error"><![CDATA[
<message type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>1</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Disable All Message Logging?'
type='boolean'
var='otr'>
<value>1</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
<error code='503' type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
]]></example>
<p>If Juliet's client does not support one of the required features, it SHOULD return a &feature; error (but MAY return no error if, for example, Juliet does not want to reveal her presence to Romeo for whatever reason):</p>
<example caption="Contact returns feature not implemented error"><![CDATA[
<message type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>1</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Disable All Message Logging?'
type='boolean'
var='otr'>
<value>1</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
]]></example>
<p>If Juliet's client does not support one of the optional features (e.g., Chat State Notifications) but it accepts the request, it MUST set the value of that boolean variable to "0" or "false".</p>
</section2>
<section2 topic='Renegotiating a Chat' anchor='renegotiate'>
<p>At any time during an existing chat session, either party MAY attempt to renegotiate the parameters of the session. The requesting party does this by sending a new &MESSAGE; stanza containing a feature negotiation form and a &THREAD; element with the same value as that of the existing chat session.</p>
<p>Note: The "accept" field SHOULD NOT be included in a renegotiation form. The set of other fields in the form MAY be different from the set included in the initial session negotitation.</p>
<example caption="One party requests renegotiation"><![CDATA[
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>1</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>1</value>
</field>
<field label='Disable All Message Logging?'
type='boolean'
var='otr'>
<value>1</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Gotta have formatting!</value>
</field>
</x>
</feature>
</message>
]]></example>
<example caption="Other party accepts offer and specifies parameters"><![CDATA[
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='http://jabber.org/protocol/xhtml-im'>
<value>true</value>
</field>
<field var='http://jabber.org/protocol/chatstates'>
<value>1</value>
</field>
<field var='otr'>
<value>1</value>
</field>
<field var='secure'>
<value>1</value>
</field>
<field var='reason'>
<value>Agreed, XHTML is fun.</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>If the other party's client does not support one of the required features, it SHOULD return a &feature; error instead. In that case the existing negotiated chat session parameters are maintained. Either party MAY then terminate the chat session as specified in the section <link url='#terminate'>Terminating a Chat</link>.</p>
</section2>
<section2 topic='Switching Resources' anchor='switch'>
<p>Either party MAY use chat renegotiation to attempt to continue the session using another of its resources. The requesting party does this by sending a feature renegotiation form with a "continue" field containing the value of the new resource:</p>
<example caption="One party asks to switch session to another of its resources"><![CDATA[
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='New client name'
type='text-single'
var='continue'>
<value>PDA</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>I am leaving the orchard.</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>The requesting party SHOULD NOT send stanzas within the session from either resource until the other party has accepted or rejected (with a &feature; error) the switch to the new resource.</p>
<p>The other party SHOULD accept the switch since the requesting party might otherwise be unable to continue the session:</p>
<example caption="Other party accepts switch"><![CDATA[
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='continue'>
<value>PDA</value>
</field>
<field var='reason'>
<value>OK, hurry to me.</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>Once the other party has accepted the switch then all stanzas sent within the chat session MUST be to or from the new resource. Note: Both parties MUST ensure that they comply with all the other chat session negotiation parameters that were previously agreed for this session.</p>
</section2>
<section2 topic='Terminating a Chat' anchor='terminate'>
<p>In order to explicitly terminate a negotiated chat, the party that wishes to end the chat MUST do so by sending a &MESSAGE; containing a data form of type "submit". The &MESSAGE; stanza SHOULD possess an 'id' attribute and MUST contain a &THREAD; element with the same XML character data as the original initiation request. The data form containing a boolean field named "terminate" set to a value of "1" or "true" and MAY also contain a "reason" field.</p>
<example caption="One party terminates chat and specifies reason"><![CDATA[
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='term1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='terminate'>
<value>1</value>
</field>
<field var='reason'>
<value>Gotta go!</value>
</field>
</x>
</feature>
</message>
]]></example>
<p>Both parties MUST then consider the chat session to be ended.</p>
<p>The other party's client MAY explicitly acknowledge the termination of the chat by sending a &MESSAGE; containing a data form of type "result", with no "reason" field and the value of the "terminate" field set to "1" or "true". The client MUST mirror the 'id' attribute and &THREAD; value it received.</p>
<example caption="Other party acknowledges chat termination"><![CDATA[
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='term1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='terminate'>
<value>1</value>
</field>
</x>
</feature>
</message>
]]></example>
</section2>
</section1>
<section1 topic='Mapping to SIP' anchor='sip'>
<p>When mapping instant messaging flows to SIP, implementations SHOULD adhere to &xmppsimple;.</p>
<p>In addition, the following mappings apply to chat session negotiation:</p>
<ul>
<li>Initiation of a negotiated chat session maps to the semantics of the SIP INVITE method.</li>
<li>Renegotiation of a negotiated chat session also maps to the semantics of the SIP INVITE method.</li>
<li>Termination of a negotiated chat session maps to the semantics of the SIP BYE method.</li>
<li>The XMPP &THREAD; value maps to the semantics of the SIP Call-ID attribute.</li>
</ul>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>A client MAY require a human user to approve each chat session negotiation request or MAY auto-accept and auto-reject requests based on some user-configurable policy.</p>
<p>If a party receives XMPP presence of type "unavailable" from the full JID (&FULLJID;) of the other party (i.e., the resource with which it has had an active session) during a chat session, the receiving party MAY assume that the other client will still be unable to continue the session (perhaps it simply became "invisible", or it is persisting the state of the negotiated chat until it reconnects and receives "offline" messages).
However, if the receiving party assumes that the other client will <em>not</em> be able to continue the session, then it MUST explicitly terminate the session (see <link url='#terminate'>Terminating a Chat</link>) - since its assumption could be incorrect. If the receiving party later receives presence of type "available" from that same resource or another resource associated with the other party and the receiving party desires to restart the chat session, it MUST initiate a new chat session (including a newly-generated ThreadID) with the other party rather than renegotiate parameters for the terminated session. (Note: This is consistent with the handling of chat states as specified in <cite>JEP-0085</cite>.)</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>If a contact accepts a user's request or returns an error to the user, the user will effectively discover the contact's presence (at least the presence of one of the contact's resources). Due care must therefore be exercised in determining whether to accept the request or return an error. For examples, the contact's client SHOULD NOT <em>automatically</em> (i.e. without first asking the contact) either accept the user's request or return an error to the user unless the user is subscribing to the contact's presence (and the contact's presence is not currently "invisible" to the user). Furthermore, the contact's client MUST NOT take either action if the user is in the contact's block list.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Service Discovery Features' anchor='registrar-features'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/chatneg' in its registry of Service Discovery features.</p>
<code caption='Registry Submission'><![CDATA[
<var>
<name>http://jabber.org/protocol/chatneg</name>
<desc>Support for Chat Session Negotiation and its FORM_TYPE</desc>
<doc>JEP-0155</doc>
</var>
]]></code>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&jep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Chat Session Negotiation:</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>http://jabber.org/protocol/chatneg</name>
<doc>JEP-0155</doc>
<desc>
Forms enabling negotation of a one-to-one
chat session between two entities.
</desc>
<field
var='accept'
type='boolean'
label='Whether to accept the invitation'/>
<field
var='http://jabber.org/protocol/chatstates'
type='boolean'
label='Whether to enable Chat State Notifications per JEP-0085'/>
<field
var='http://jabber.org/protocol/xhtml-im'
type='boolean'
label='Whether to enable XHTML-IM formatting per JEP-0071'/>
<field
var='otr'
type='boolean'
label='Off-The-Record: whether to disable absolutely all message logging including automatic archiving - see JEP-0136'/>
<field
var='reason'
type='text-single'
label='A reason for chatting (or not)'/>
<field
var='continue'
type='text-single'
label='Another resource with which to continue the session'/>
<field
var='secure'
type='boolean'
label='Whether both parties must be securely connected to their servers'/>
<field
var='terminate'
type='boolean'
label='Whether to terminate the session'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>This proposal re-uses the format defined in JEP-0020 and therefore does not require a separate schema.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Thomas Charron and Jean-Louis Seguineau for their feedback.</p>
</section1>
</jep>
Reference in New Issue View Git Blame Copy Permalink