1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-22 01:02:17 -05:00

JEP to XEP

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@45 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2006-10-04 16:57:13 +00:00
parent 8eeba9ccd3
commit 4825961d70
10 changed files with 240 additions and 240 deletions

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Waiting Lists</title> <title>Waiting Lists</title>
<abstract>This JEP defines an XMPP protocol extension that enables a user to add a non-IM user to a waiting list and be informed when the contact creates an IM account.</abstract> <abstract>This document defines an XMPP protocol extension that enables a user to add a non-IM user to a waiting list and be informed when the contact creates an IM account.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0130</number> <number>0130</number>
<status>Active</status> <status>Active</status>
@ -16,14 +16,14 @@
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>XMPP IM</spec> <spec>XMPP IM</spec>
<spec>JEP-0094</spec> <spec>XEP-0094</spec>
<spec>JEP-0030</spec> <spec>XEP-0030</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>waitinglist</shortname> <shortname>waitinglist</shortname>
<schemaloc> <schemaloc>
<url>http://jabber.org/protocol/waitinglist/waitinglist.xsd</url> <url>http://www.xmpp.org/schemas/waitinglist.xsd</url>
</schemaloc> </schemaloc>
&stpeter; &stpeter;
<author> <author>
@ -89,7 +89,7 @@
<version>0.4</version> <version>0.4</version>
<date>2005-04-01</date> <date>2005-04-01</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Changed JEP type to Informational; corrected Remote Server Error example to use &remoteserver; rather than &unavailable;; added service discovery identity to Jabber Registrar Considerations; corrected text regarding registration of service discovery features; corrected some small errors in the text, examples, and schema.</remark> <remark>Changed document type to Informational; corrected Remote Server Error example to use &remoteserver; rather than &unavailable;; added service discovery identity to XMPP Registrar Considerations; corrected text regarding registration of service discovery features; corrected some small errors in the text, examples, and schema.</remark>
</revision> </revision>
<revision> <revision>
<version>0.3</version> <version>0.3</version>
@ -107,7 +107,7 @@
<version>0.1</version> <version>0.1</version>
<date>2004-03-18</date> <date>2004-03-18</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Initial JEP version.</remark> <remark>Initial version.</remark>
</revision> </revision>
<revision> <revision>
<version>0.0.10</version> <version>0.0.10</version>
@ -161,7 +161,7 @@
<version>0.0.2</version> <version>0.0.2</version>
<date>2003-06-16</date> <date>2003-06-16</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Converted to JEP XML format; formalized use case definitions; minor editorial changes.</remark> <remark>Converted to XML format; formalized use case definitions; minor editorial changes.</remark>
</revision> </revision>
<revision> <revision>
<version>0.0.1</version> <version>0.0.1</version>
@ -397,7 +397,7 @@
<em>This section of the document is provided for the sake of domains that implement XMPP as their local protocol; domains that implement another protocol will use their service-specific protocol to complete the user-to-domain interaction.</em> <em>This section of the document is provided for the sake of domains that implement XMPP as their local protocol; domains that implement another protocol will use their service-specific protocol to complete the user-to-domain interaction.</em>
</p> </p>
<section3 topic="IM User Retrieves Current WaitingList" anchor='protocol-imuser-retrieve'> <section3 topic="IM User Retrieves Current WaitingList" anchor='protocol-imuser-retrieve'>
<p>It is RECOMMENDED for an IM User's client to retrieve the WaitingList immediately after logging in. However, first it must discover its local WaitingListService. An IM User MAY use either &jep0030; or the deprecated &jep0094; protocol.</p> <p>It is RECOMMENDED for an IM User's client to retrieve the WaitingList immediately after logging in. However, first it must discover its local WaitingListService. An IM User MAY use either &xep0030; or the deprecated &xep0094; protocol.</p>
<example caption="IM User Discovers WaitingListService by Sending Agent Information Request to its Server"><![CDATA[ <example caption="IM User Discovers WaitingListService by Sending Agent Information Request to its Server"><![CDATA[
<iq type='get' id='agent1'> <iq type='get' id='agent1'>
<query xmlns='jabber:iq:agents'/> <query xmlns='jabber:iq:agents'/>
@ -474,7 +474,7 @@
</item> </item>
<item id='23456'> <item id='23456'>
<uri scheme='mailto'>editor@jabber.org</uri> <uri scheme='mailto'>editor@jabber.org</uri>
<name>JEP Editor</name> <name>XMPP Extensions Editor</name>
</item> </item>
</query> </query>
</iq> </iq>
@ -500,14 +500,14 @@
</item> </item>
<item id='23456'> <item id='23456'>
<uri scheme='mailto'>editor@jabber.org</uri> <uri scheme='mailto'>editor@jabber.org</uri>
<name>JEP Editor</name> <name>XMPP Extensions Editor</name>
</item> </item>
</query> </query>
</iq> </iq>
]]></example> ]]></example>
</section3> </section3>
<section3 topic="IM User Adds Contact to WaitingList" anchor='protocol-imuser-add'> <section3 topic="IM User Adds Contact to WaitingList" anchor='protocol-imuser-add'>
<p>Once an IM User's client has discovered the WaitingListService and requested the user's WaitingList, the user can add Contacts to the WaitingList based on the Contact's URI. (Note: This JEP uses the example of phone numbers via the 'tel' URI scheme, but the same rules apply to WaitingList items based on email addresses or other URI schemes.)</p> <p>Once an IM User's client has discovered the WaitingListService and requested the user's WaitingList, the user can add Contacts to the WaitingList based on the Contact's URI. (Note: This document uses the example of phone numbers via the 'tel' URI scheme, but the same rules apply to WaitingList items based on email addresses or other URI schemes.)</p>
<example caption="IM User Requests Addition of Contact to WaitingList"><![CDATA[ <example caption="IM User Requests Addition of Contact to WaitingList"><![CDATA[
<iq type='set' <iq type='set'
to='waitlist.service-provider.com' to='waitlist.service-provider.com'
@ -520,7 +520,7 @@
</query> </query>
</iq> </iq>
]]></example> ]]></example>
<p>As described below, various error conditions may occur. (For information about error syntax, refer to <cite>RFC 3920</cite> and &jep0086;.)</p> <p>As described below, various error conditions may occur. (For information about error syntax, refer to <cite>RFC 3920</cite> and &xep0086;.)</p>
<p>If the IM User provided a URI whose scheme is not supported, WaitingListService MUST return a &badrequest; error to the IM User and MUST NOT add the Contact to the WaitingList.</p> <p>If the IM User provided a URI whose scheme is not supported, WaitingListService MUST return a &badrequest; error to the IM User and MUST NOT add the Contact to the WaitingList.</p>
<example caption='WaitingListService Returns &badrequest; Error to IM User'><![CDATA[ <example caption='WaitingListService Returns &badrequest; Error to IM User'><![CDATA[
<iq type='error' <iq type='error'
@ -620,7 +620,7 @@
<p>If the connection to at least one of the InteropPartners times out (a &timeout; error), WaitingListService MUST return an IQ-result as described above (indicating that the request was received) and resend the request to the InteropPartners that timed out. If connections continue to time out (over some configurable time period and for some configurable number of retries), WaitingListService SHOULD then return a &timeout; error to IM User via a "JID push" message as shown below.</p> <p>If the connection to at least one of the InteropPartners times out (a &timeout; error), WaitingListService MUST return an IQ-result as described above (indicating that the request was received) and resend the request to the InteropPartners that timed out. If connections continue to time out (over some configurable time period and for some configurable number of retries), WaitingListService SHOULD then return a &timeout; error to IM User via a "JID push" message as shown below.</p>
<p>If InterPartner's WaitingListService knows the Contact JID, it sends it to ServiceProvider's WaitingListService as shown in the <link url='#protocol-service-add'>ServiceProvider's WaitingListService Adds Contact to WaitingList</link> section of this document.</p> <p>If InterPartner's WaitingListService knows the Contact JID, it sends it to ServiceProvider's WaitingListService as shown in the <link url='#protocol-service-add'>ServiceProvider's WaitingListService Adds Contact to WaitingList</link> section of this document.</p>
<p>If WaitingListService knows Contact JID (or learns Contact JID from InteropPartner), it MUST inform IM User through a "JID push" message, which consists of a message stanza that contains a &lt;waitlist/&gt; element qualified by the 'http://jabber.org/protocol/waitinglist' namespace: <p>If WaitingListService knows Contact JID (or learns Contact JID from InteropPartner), it MUST inform IM User through a "JID push" message, which consists of a message stanza that contains a &lt;waitlist/&gt; element qualified by the 'http://jabber.org/protocol/waitinglist' namespace:
<note>When waiting list information is included in a message stanza, the root element for the 'http://jabber.org/protocol/waitinglist' namespace is &lt;waitlist/&gt; rather than &lt;query/&gt; (as used within IQ stanzas). This disparity is historical and tracks the protocol syntax that was most widely implemented, as defined in version 0.4 of this specification. In the interest of interoperability, the IQ usage was changed back to &lt;query/&gt; in version 1.1 of this specification. If this JEP were not historical, the root element usage would be harmonized to use only the &lt;waitlist/&gt; element.</note> <note>When waiting list information is included in a message stanza, the root element for the 'http://jabber.org/protocol/waitinglist' namespace is &lt;waitlist/&gt; rather than &lt;query/&gt; (as used within IQ stanzas). This disparity is historical and tracks the protocol syntax that was most widely implemented, as defined in version 0.4 of this specification. In the interest of interoperability, the IQ usage was changed back to &lt;query/&gt; in version 1.1 of this specification. If this document were not historical, the root element usage would be harmonized to use only the &lt;waitlist/&gt; element.</note>
</p> </p>
<example caption="WaitingListService Pushes Contact's JID to IM User"><![CDATA[ <example caption="WaitingListService Pushes Contact's JID to IM User"><![CDATA[
<message <message
@ -905,10 +905,10 @@
<li><p>A ServiceProvider's WaitingListService MUST record which of its IM Users have requested the JID associated with Contact's URI, and an InteropPartner's WaitingListService MUST record that Service Provider's WaitingListService (not User) has requested JID associated with Contact's URI. Therefore when Contact registers, InteropPartner's WaitingListService informs its local users as well as ServiceProvider's WaitingListService, and ServiceProvider's WaitingListService informs its local users.</p></li> <li><p>A ServiceProvider's WaitingListService MUST record which of its IM Users have requested the JID associated with Contact's URI, and an InteropPartner's WaitingListService MUST record that Service Provider's WaitingListService (not User) has requested JID associated with Contact's URI. Therefore when Contact registers, InteropPartner's WaitingListService informs its local users as well as ServiceProvider's WaitingListService, and ServiceProvider's WaitingListService informs its local users.</p></li>
<li><p>The InteropPartner's WaitingListService is not required to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.</p></li> <li><p>The InteropPartner's WaitingListService is not required to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.</p></li>
<li><p>Once an IM User learns a Contact's JID, the IM User MAY send a normal subscription request to the Contact, setting the "to" address to Contact's JID. This interaction is defined in the base XMPP specifications and is out of scope for this document.</p></li> <li><p>Once an IM User learns a Contact's JID, the IM User MAY send a normal subscription request to the Contact, setting the "to" address to Contact's JID. This interaction is defined in the base XMPP specifications and is out of scope for this document.</p></li>
<li><p>For historical reasons, implementations MUST support the older <cite>Agent Information</cite> protocol (JEP-0094) and SHOULD support <cite>Service Discovery</cite> (JEP-0030). Note well that the <cite>Agent Information</cite> protocol will eventually be deprecated in favor of <cite>Service Discovery</cite>.</p></li> <li><p>For historical reasons, implementations MUST support the older <cite>Agent Information</cite> protocol (XEP-0094) and SHOULD support <cite>Service Discovery</cite> (XEP-0030). Note well that the <cite>Agent Information</cite> protocol will eventually be deprecated in favor of <cite>Service Discovery</cite>.</p></li>
<li><p>An IM User's client receives WaitingList information either through a "JID push" message (received from WaitingListService at any time) or in the IQ result received after requesting the WaitingList (since one or more of the WaitingList items may contain a JID). (The same rule applies to a ServiceProvider's WaitingListService that receives an IQ set from an InteropPartner's WaitingListService.)</p></li> <li><p>An IM User's client receives WaitingList information either through a "JID push" message (received from WaitingListService at any time) or in the IQ result received after requesting the WaitingList (since one or more of the WaitingList items may contain a JID). (The same rule applies to a ServiceProvider's WaitingListService that receives an IQ set from an InteropPartner's WaitingListService.)</p></li>
<li><p>When an IM User logs in, the user's client SHOULD request the current WaitingList.</p></li> <li><p>When an IM User logs in, the user's client SHOULD request the current WaitingList.</p></li>
<li><p>Although the examples in this JEP show the hostname of the WaitingListService as 'waitlist.third-party.com' (etc.), this is for convenience only; the hostname MAY be any valid DNS hostname.</p></li> <li><p>Although the examples in this document show the hostname of the WaitingListService as 'waitlist.third-party.com' (etc.), this is for convenience only; the hostname MAY be any valid DNS hostname.</p></li>
<li><p>When sending JID pushes, an implementation MAY specify a message type of 'headline', which in some deployments will prevent such messages from being stored offline for later delivery.</p></li> <li><p>When sending JID pushes, an implementation MAY specify a message type of 'headline', which in some deployments will prevent such messages from being stored offline for later delivery.</p></li>
<li><p>It can happen that WaitingListService does not receive a reply from InteropPartner within a certain amount of time or the connection to InteropPartner times out. Because such behavior is often transient, WaitingListService MAY attempt to reconnect and then resend the request (although any retry logic to handle these cases is a matter of implementation). However, WaitingListService SHOULD NOT return an &notfound; error to IM User unless it knows definitively that the Contact's InteropPartner is permanently unavailable, since returning an &notfound; error in response to temporary connection timeouts is likely to be misleading.</p></li> <li><p>It can happen that WaitingListService does not receive a reply from InteropPartner within a certain amount of time or the connection to InteropPartner times out. Because such behavior is often transient, WaitingListService MAY attempt to reconnect and then resend the request (although any retry logic to handle these cases is a matter of implementation). However, WaitingListService SHOULD NOT return an &notfound; error to IM User unless it knows definitively that the Contact's InteropPartner is permanently unavailable, since returning an &notfound; error in response to temporary connection timeouts is likely to be misleading.</p></li>
</ol> </ol>
@ -919,9 +919,9 @@
<p>A service MAY require a Contact to approve the disclosure of the Contact's JID, either as a global preference or for each request; however, this is a local policy matter.</p> <p>A service MAY require a Contact to approve the disclosure of the Contact's JID, either as a global preference or for each request; however, this is a local policy matter.</p>
</section1> </section1>
<section1 topic="IANA Considerations" anchor='iana'> <section1 topic="IANA Considerations" anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic="Jabber Registrar Considerations" anchor='registrar'> <section1 topic="XMPP Registrar Considerations" anchor='registrar'>
<section2 topic="Protocol Namespaces" anchor='registrar-ns'> <section2 topic="Protocol Namespaces" anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/waitinglist' in its registry of protocol namespaces.</p> <p>The &REGISTRAR; includes 'http://jabber.org/protocol/waitinglist' in its registry of protocol namespaces.</p>
</section2> </section2>
@ -929,8 +929,8 @@
<p>The Jabber Registar includes a type of "waitinglist" in the "directory" category in its registry of service discovery identities.</p> <p>The Jabber Registar includes a type of "waitinglist" in the "directory" category in its registry of service discovery identities.</p>
</section2> </section2>
<section2 topic="Service Discovery Features" anchor='registrar-features'> <section2 topic="Service Discovery Features" anchor='registrar-features'>
<p>The Jabber Registrar includes supported URI schemes in its registry of service discovery features. These features shall be of the form 'http://jabber.org/protocol/waitlist/schemes/SCHEME-NAME'.</p> <p>The XMPP Registrar includes supported URI schemes in its registry of service discovery features. These features shall be of the form 'http://jabber.org/protocol/waitlist/schemes/SCHEME-NAME'.</p>
<p>This JEP registers the following two namespace names for URI schemes, but others MAY be registered in the future using standard registration procedures:</p> <p>This document registers the following two namespace names for URI schemes, but others MAY be registered in the future using standard registration procedures:</p>
<ul> <ul>
<li>http://jabber.org/protocol/waitlist/schemes/mailto</li> <li>http://jabber.org/protocol/waitlist/schemes/mailto</li>
<li>http://jabber.org/protocol/waitlist/schemes/tel</li> <li>http://jabber.org/protocol/waitlist/schemes/tel</li>
@ -950,7 +950,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0130: http://www.jabber.org/jeps/jep-0130.html XEP-0130: http://www.xmpp.org/extensions/xep-0130.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -962,7 +962,7 @@
'http://jabber.org/protocol/waitinglist' namespace, 'http://jabber.org/protocol/waitinglist' namespace,
query and waitlist. The query element is used within query and waitlist. The query element is used within
IQ stanzas and the waitlist element is used within IQ stanzas and the waitlist element is used within
message stanzas. See JEP-0130 for details. message stanzas. See XEP-0130 for details.
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -1040,4 +1040,4 @@
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,10 +1,10 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Stanza Headers and Internet Metadata</title> <title>Stanza Headers and Internet Metadata</title>
<abstract>This document defines an XMPP protocol extension for specifying headers about XMPP stanza content, including an XML representation of many kinds of standard Internet metadata.</abstract> <abstract>This document defines an XMPP protocol extension for specifying headers about XMPP stanza content, including an XML representation of many kinds of standard Internet metadata.</abstract>
@ -15,13 +15,13 @@
<jig>Standards JIG</jig> <jig>Standards JIG</jig>
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>JEP-0030</spec> <spec>XEP-0030</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>shim</shortname> <shortname>shim</shortname>
<schemaloc> <schemaloc>
<url>http://jabber.org/protocol/shim/shim.xsd</url> <url>http://www.xmpp.org/schemas/shim.xsd</url>
</schemaloc> </schemaloc>
<registry/> <registry/>
&stpeter; &stpeter;
@ -36,7 +36,7 @@
<version>1.1</version> <version>1.1</version>
<date>2005-08-19</date> <date>2005-08-19</date>
<initials>psa</initials> <initials>psa</initials>
<remark><p>Added Date, DateTime, and Time headers conforming to profiles from JEP-0082; renamed Date header to RFC2822Date; added note about date-related headers; added headers from RFC 2413 (Dublin Core).</p></remark> <remark><p>Added Date, DateTime, and Time headers conforming to profiles from XEP-0082; renamed Date header to RFC2822Date; added note about date-related headers; added headers from RFC 2413 (Dublin Core).</p></remark>
</revision> </revision>
<revision> <revision>
<version>1.0</version> <version>1.0</version>
@ -94,7 +94,7 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>In order to ensure proper processing by the recipient of an XML stanza, some Jabber protocols and other XMPP extensions may need to enable the sender to communicate non-addressing information about the stanza (this is especially true of protocols that translate from a foreign format to XMPP; a good example is &jep0111;). Such information was formerly included in &jep0033;, but was removed from that specification when it was changed to focus on addressing information only. Therefore, this JEP defines a mechanism for encapsulating non-addressing "header" information about stanzas, including standard Internet metadata such as that defined by &rfc2045;, &rfc2616;, &rfc2617;, &rfc2822;, and &rfc3261;. Such information is encapsulated in a protocol extension qualified by the 'http://jabber.org/protocol/shim' namespace, where "SHIM" stands for "Stanza Headers and Internet Metadata".</p> <p>In order to ensure proper processing by the recipient of an XML stanza, some Jabber protocols and other XMPP extensions may need to enable the sender to communicate non-addressing information about the stanza (this is especially true of protocols that translate from a foreign format to XMPP; a good example is &xep0111;). Such information was formerly included in &xep0033;, but was removed from that specification when it was changed to focus on addressing information only. Therefore, this document defines a mechanism for encapsulating non-addressing "header" information about stanzas, including standard Internet metadata such as that defined by &rfc2045;, &rfc2616;, &rfc2617;, &rfc2822;, and &rfc3261;. Such information is encapsulated in a protocol extension qualified by the 'http://jabber.org/protocol/shim' namespace, where "SHIM" stands for "Stanza Headers and Internet Metadata".</p>
</section1> </section1>
<section1 topic='Requirements' anchor='reqs'> <section1 topic='Requirements' anchor='reqs'>
<p>This protocol addresses the following requirements:</p> <p>This protocol addresses the following requirements:</p>
@ -106,7 +106,7 @@
</section1> </section1>
<section1 topic='Discovery' anchor='disco'> <section1 topic='Discovery' anchor='disco'>
<section2 topic='Protocol Support' anchor='disco-proto'> <section2 topic='Protocol Support' anchor='disco-proto'>
<p>In order to discover whether another entity supports this protocol, an entity MUST use &jep0030;.</p> <p>In order to discover whether another entity supports this protocol, an entity MUST use &xep0030;.</p>
<example caption='Entity queries another entity regarding protocol support'><![CDATA[ <example caption='Entity queries another entity regarding protocol support'><![CDATA[
<iq from='romeo@montague.net/orchard' <iq from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'> to='juliet@capulet.com/balcony'>
@ -177,13 +177,13 @@
]]></example> ]]></example>
</section1> </section1>
<section1 topic='Header Definitions' anchor='headers'> <section1 topic='Header Definitions' anchor='headers'>
<p>All public headers SHOULD be registered with the Jabber Registrar following the process specified in the <link url="#registrar">Jabber Registrar Considerations</link> section of this document. Many such headers are defined by other protocol specifications, such as RFCs 2045, 2616, 2617, 2822, and 3261; implementors MUST refer to those specifications for definition of the relevant headers.</p> <p>All public headers SHOULD be registered with the XMPP Registrar following the process specified in the <link url="#registrar">XMPP Registrar Considerations</link> section of this document. Many such headers are defined by other protocol specifications, such as RFCs 2045, 2616, 2617, 2822, and 3261; implementors MUST refer to those specifications for definition of the relevant headers.</p>
<p>This JEP defines several additional headers that may prove useful within Jabber protocols and other XMPP extensions, as specified in the following sections; further headers may be registered with the Jabber Registrar, either directly or via definition in Jabber Enhancement Proposals.</p> <p>This document defines several additional headers that may prove useful within Jabber protocols and other XMPP extensions, as specified in the following sections; further headers may be registered with the XMPP Registrar, either directly or via definition in Jabber Enhancement Proposals.</p>
<section2 topic='Classification' anchor='headers-classification'> <section2 topic='Classification' anchor='headers-classification'>
<p>The Classification header enables a sender or other entity to classify a stanza according to some classification scheme. The values of the XML character data contained within this header are out of scope for this document, since they are determined by the using application. Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p> <p>The Classification header enables a sender or other entity to classify a stanza according to some classification scheme. The values of the XML character data contained within this header are out of scope for this document, since they are determined by the using application. Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p>
</section2> </section2>
<section2 topic='Created' anchor='headers-created'> <section2 topic='Created' anchor='headers-created'>
<p>The Date header is defined by RFC 2822 and therefore follows the date and time format defined by RFC 2822; while this header is thus useful for translating email messages into XMPP stanzas, it is not consistent with &jep0082;. Therefore we define the "Created" header, which specifies the date and time when a stanza was created by the originating entity, where the value conforms to the DateTime profile specified in JEP-0082.</p> <p>The Date header is defined by RFC 2822 and therefore follows the date and time format defined by RFC 2822; while this header is thus useful for translating email messages into XMPP stanzas, it is not consistent with &xep0082;. Therefore we define the "Created" header, which specifies the date and time when a stanza was created by the originating entity, where the value conforms to the DateTime profile specified in XEP-0082.</p>
</section2> </section2>
<section2 topic='Distribute' anchor='headers-distribute'> <section2 topic='Distribute' anchor='headers-distribute'>
<p>The Distribute header enables a sender to specify whether the stanza may be further distributed by the recipient to other entities on the network. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT further distribute the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY further distribute the stanza or any information contained therein; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false". This header is semantically equivalent to the "Distribute" flag defined in &geoprivpol;. (The HTTP "Max-Forwards" header is not appropriate for this usage, since it defines proxy and gateway behavior rather than recipient behavior.) Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p> <p>The Distribute header enables a sender to specify whether the stanza may be further distributed by the recipient to other entities on the network. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT further distribute the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY further distribute the stanza or any information contained therein; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false". This header is semantically equivalent to the "Distribute" flag defined in &geoprivpol;. (The HTTP "Max-Forwards" header is not appropriate for this usage, since it defines proxy and gateway behavior rather than recipient behavior.) Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p>
@ -192,7 +192,7 @@
<p>The Store header enables a sender to specify whether the stanza may be stored or archived by the recipient. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT store the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY store the stanza or any information contained therein; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false". Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p> <p>The Store header enables a sender to specify whether the stanza may be stored or archived by the recipient. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT store the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY store the stanza or any information contained therein; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false". Note: This header may be security-sensitive (see the <link url='#security'>Security Considerations</link> for details).</p>
</section2> </section2>
<section2 topic='TTL' anchor='headers-ttl'> <section2 topic='TTL' anchor='headers-ttl'>
<p>It may be useful to specify that the information contained in a stanza is valid only for a limited period of time. Such is the function of the "TTL" header, the value of which is some number of seconds since the creation of the stanza. Note well that this header is purely informational and MUST NOT be used for routing or delivery of XML stanzas, since that function is already served by &jep0079;. A stanza that includes the "TTL" header SHOULD also include a "Created" header so that the recipient can properly process the stanza.</p> <p>It may be useful to specify that the information contained in a stanza is valid only for a limited period of time. Such is the function of the "TTL" header, the value of which is some number of seconds since the creation of the stanza. Note well that this header is purely informational and MUST NOT be used for routing or delivery of XML stanzas, since that function is already served by &xep0079;. A stanza that includes the "TTL" header SHOULD also include a "Created" header so that the recipient can properly process the stanza.</p>
<p>One situation in which both the "Created" and "TTL" headers might prove valuable is the broadcasting of structured presence information, such as a calendar-generated notification that a user will be in a meeting for the next hour:</p> <p>One situation in which both the "Created" and "TTL" headers might prove valuable is the broadcasting of structured presence information, such as a calendar-generated notification that a user will be in a meeting for the next hour:</p>
<example caption='Time to Live for Presence Information'><![CDATA[ <example caption='Time to Live for Presence Information'><![CDATA[
<presence> <presence>
@ -238,7 +238,7 @@
</section2> </section2>
</section1> </section1>
<section1 topic='A Note About Date-Related Headers' anchor='dates'> <section1 topic='A Note About Date-Related Headers' anchor='dates'>
<p>Date formats differ widely. &jep0082; defines the Date, DateTime, and Time profiles of &iso8601;, which correspond to the Date, DateTime, and Time headers registered herein. The SHIM Date header also corresponds to the Date metadata element used in &DUBLINCORE; as specified in &rfc2413;.</p> <p>Date formats differ widely. &xep0082; defines the Date, DateTime, and Time profiles of &iso8601;, which correspond to the Date, DateTime, and Time headers registered herein. The SHIM Date header also corresponds to the Date metadata element used in &DUBLINCORE; as specified in &rfc2413;.</p>
<p>However, many Internet standards use a different datetime format that ultimately derives from &rfc0822; as updated by &rfc1123;; specifically, that format is used by email (<cite>RFC 2822</cite>), the World Wide Web (<cite>RFC 2616</cite>), and the Session Initiation Protocol (<cite>RFC 3261</cite>). To map dates to and from these protocols, we define the SHIM RFC2822Date header.</p> <p>However, many Internet standards use a different datetime format that ultimately derives from &rfc0822; as updated by &rfc1123;; specifically, that format is used by email (<cite>RFC 2822</cite>), the World Wide Web (<cite>RFC 2616</cite>), and the Session Initiation Protocol (<cite>RFC 3261</cite>). To map dates to and from these protocols, we define the SHIM RFC2822Date header.</p>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
@ -246,17 +246,17 @@
<p>Certain SHIM headers MAY be security-sensitive (e.g., the "Classification", "Distribute", and "Store" headers specified herein). If an entity plans to use such headers, it MUST determine whether the intended recipient supports both the SHIM protocol and the particular security-sensitive headers of interst, as described under <link url='#disco'>Service Discovery</link>; furthermore, an implementation MUST warn a human user (if any) before use if the security-sensitive headers of interest are not supported.</p> <p>Certain SHIM headers MAY be security-sensitive (e.g., the "Classification", "Distribute", and "Store" headers specified herein). If an entity plans to use such headers, it MUST determine whether the intended recipient supports both the SHIM protocol and the particular security-sensitive headers of interst, as described under <link url='#disco'>Service Discovery</link>; furthermore, an implementation MUST warn a human user (if any) before use if the security-sensitive headers of interest are not supported.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The Jabber Registrar includes 'http://jabber.org/protocol/shim' in its registry of protocol namespaces (see &SHIMHEADERS;).</p> <p>The XMPP Registrar includes 'http://jabber.org/protocol/shim' in its registry of protocol namespaces (see &SHIMHEADERS;).</p>
</section2> </section2>
<section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-nodes'> <section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-nodes'>
<p>The Jabber Registrar includes 'http://jabber.org/protocol/shim' in its registry of well-known Service Discovery nodes.</p> <p>The XMPP Registrar includes 'http://jabber.org/protocol/shim' in its registry of well-known Service Discovery nodes.</p>
</section2> </section2>
<section2 topic='SHIM Headers Registry' anchor='registrar-shim'> <section2 topic='SHIM Headers Registry' anchor='registrar-shim'>
<p>The Jabber Registrar maintains a registry of SHIM headers.</p> <p>The XMPP Registrar maintains a registry of SHIM headers.</p>
<section3 topic='Process' anchor='registrar-shim-process'> <section3 topic='Process' anchor='registrar-shim-process'>
&REGPROCESS; &REGPROCESS;
<code><![CDATA[ <code><![CDATA[
@ -345,7 +345,7 @@
<header> <header>
<name>Classification</name> <name>Classification</name>
<desc>a level within a classification scheme</desc> <desc>a level within a classification scheme</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -447,7 +447,7 @@
<header> <header>
<name>Created</name> <name>Created</name>
<desc>date and time of stanza creation in ISO 8601 format</desc> <desc>date and time of stanza creation in ISO 8601 format</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -464,14 +464,14 @@
<header> <header>
<name>Date</name> <name>Date</name>
<desc>a string that conforms to the Date profile specified in JEP-0082</desc> <desc>a string that conforms to the Date profile specified in XEP-0082</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
<name>DateTime</name> <name>DateTime</name>
<desc>a string that conforms to the DateTime profile specified in JEP-0082</desc> <desc>a string that conforms to the DateTime profile specified in XEP-0082</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -483,7 +483,7 @@
<header> <header>
<name>Distribute</name> <name>Distribute</name>
<desc>whether or not the stanza may be further distributed</desc> <desc>whether or not the stanza may be further distributed</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -783,7 +783,7 @@
<header> <header>
<name>Store</name> <name>Store</name>
<desc>whether or not the stanza may be stored or archived</desc> <desc>whether or not the stanza may be stored or archived</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -806,8 +806,8 @@
<header> <header>
<name>Time</name> <name>Time</name>
<desc>a string that conforms to the Time profile specified in JEP-0082</desc> <desc>a string that conforms to the Time profile specified in XEP-0082</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -837,7 +837,7 @@
<header> <header>
<name>TTL</name> <name>TTL</name>
<desc>a time to live for the stanza, in seconds</desc> <desc>a time to live for the stanza, in seconds</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -861,7 +861,7 @@
<header> <header>
<name>Urgency</name> <name>Urgency</name>
<desc>the time sensitivity of a stanza ("high", "medium", or "low")</desc> <desc>the time sensitivity of a stanza ("high", "medium", or "low")</desc>
<doc>JEP-0131</doc> <doc>XEP-0131</doc>
</header> </header>
<header> <header>
@ -911,7 +911,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0131: http://www.jabber.org/jeps/jep-0131.html XEP-0131: http://www.xmpp.org/extensions/xep-0131.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -936,4 +936,4 @@
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Presence Obtained via Kinesthetic Excitation (POKE)</title> <title>Presence Obtained via Kinesthetic Excitation (POKE)</title>
<abstract>This JEP defines a protocol extension that enables probing for presence via physical rather than electronic means.</abstract> <abstract>This document defines an XMPP protocol extension that enables probing for presence via physical rather than electronic means.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0132</number> <number>0132</number>
<status>Active</status> <status>Active</status>
@ -30,17 +30,17 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='schema'> <section1 topic='Introduction' anchor='schema'>
<p>&xmppcore; and &xmppim; define methods for exchanging information about a person's network availability via the XML &lt;presence/&gt; stanza. In general, such presence information is generated only when a person initiates interaction with a client, although it can be generated programmatically through features such as auto-away. However, sometimes a user is present in the vicinity of a client but is not actively engaged with the client interface. In such circumstances, it would be helpful to have a mechanism that is sometimes referred to as &lt;presence type='probe-irl'/&gt;: the ability to invoke a real-life means of determining the physical presence of the user. This JEP defines just such a mechanism.</p> <p>&xmppcore; and &xmppim; define methods for exchanging information about a person's network availability via the XML &lt;presence/&gt; stanza. In general, such presence information is generated only when a person initiates interaction with a client, although it can be generated programmatically through features such as auto-away. However, sometimes a user is present in the vicinity of a client but is not actively engaged with the client interface. In such circumstances, it would be helpful to have a mechanism that is sometimes referred to as &lt;presence type='probe-irl'/&gt;: the ability to invoke a real-life means of determining the physical presence of the user. This document defines just such a mechanism.</p>
</section1> </section1>
<section1 topic='Approach' anchor='approach'> <section1 topic='Approach' anchor='approach'>
<p>Physical presence is best determined through direct interaction with an object. In this JEP, our approach is labelled "kinesthetic excitation": some form of physical contact is initiated with the object (in most cases a user), resulting in hard evidence of presence obtained by a sense modality such as sight, touch, or hearing. To ensure reliability, the physical contact MUST impinge upon the object or user to such an extent that it measurably reacts in the form of motion through space (e.g., moving in relation to a visual observation device), generation of an auditory event (e.g., vocalization), and the like. The exact means of excitation and perception are implementation-specific and therefore not specified fully in this JEP, although suggestions are provided in the <link url="#protocol-methods">Methods</link> section below.</p> <p>Physical presence is best determined through direct interaction with an object. In this document, our approach is labelled "kinesthetic excitation": some form of physical contact is initiated with the object (in most cases a user), resulting in hard evidence of presence obtained by a sense modality such as sight, touch, or hearing. To ensure reliability, the physical contact MUST impinge upon the object or user to such an extent that it measurably reacts in the form of motion through space (e.g., moving in relation to a visual observation device), generation of an auditory event (e.g., vocalization), and the like. The exact means of excitation and perception are implementation-specific and therefore not specified fully in this document, although suggestions are provided in the <link url="#protocol-methods">Methods</link> section below.</p>
</section1> </section1>
<section1 topic='Protocol' anchor='protocol'> <section1 topic='Protocol' anchor='protocol'>
<p>In the past, some members of the Jabber community have suggested the addition of a new presence type: "probe-irl". However, this has several drawbacks. First, the XMPP specifications (<cite>XMPP Core</cite> and <cite>XMPP IM</cite>) approved by the IETF do not allow any values for the 'type' attribute other than those defined in the XML schemas for the 'jabber:client' and 'jabber:server' namespaces. Second, presence probes are handled by a server on behalf of a user and therefore are not routed to clients (which presumably often have the best opportunity for discovering evidence of physical presence); an &IQ; stanza is more appropriate for client-to-client information exchange. Therefore, this JEP defines a general extension mechanism that can be used in both &PRESENCE; and &IQ; stanzas.</p> <p>In the past, some members of the Jabber community have suggested the addition of a new presence type: "probe-irl". However, this has several drawbacks. First, the XMPP specifications (<cite>XMPP Core</cite> and <cite>XMPP IM</cite>) approved by the IETF do not allow any values for the 'type' attribute other than those defined in the XML schemas for the 'jabber:client' and 'jabber:server' namespaces. Second, presence probes are handled by a server on behalf of a user and therefore are not routed to clients (which presumably often have the best opportunity for discovering evidence of physical presence); an &IQ; stanza is more appropriate for client-to-client information exchange. Therefore, this document defines a general extension mechanism that can be used in both &PRESENCE; and &IQ; stanzas.</p>
<p>The extension mechanism is encapsulated in a &lt;poke/&gt; element qualified by the 'http://jabber.org/protocol/poke' namespace; this element MAY be included as a direct child of a &PRESENCE; stanza of type "probe" or an &IQ; stanza of type "get" (for a request), "result" (for a successful response), or "error" (for an unsuccessful response).</p> <p>The extension mechanism is encapsulated in a &lt;poke/&gt; element qualified by the 'http://jabber.org/protocol/poke' namespace; this element MAY be included as a direct child of a &PRESENCE; stanza of type "probe" or an &IQ; stanza of type "get" (for a request), "result" (for a successful response), or "error" (for an unsuccessful response).</p>
<p>The requesting entity MAY specify a preferred method of excitation and observation; in general, these methods correspond to particular sense modalities such as sight, touch, and hearing (see the <link url="#protocol-methods">Methods</link> section below).</p> <p>The requesting entity MAY specify a preferred method of excitation and observation; in general, these methods correspond to particular sense modalities such as sight, touch, and hearing (see the <link url="#protocol-methods">Methods</link> section below).</p>
<section2 topic='Presence' anchor='protocol-presence'> <section2 topic='Presence' anchor='protocol-presence'>
<p>As defined in <cite>XMPP IM</cite>, presence stanzas of type "probe" are handled on behalf of the target entity by the entity's server. While normally these presence stanzas are generated by the requesting entity's server (e.g., when the requesting entity sends initial presence), the requesting entity itself (or, more precisely, its client) is allowed to generate presence stanzas of type "probe". In this JEP we make use of this ability to query the target entity's server regarding the entity's physical presence.</p> <p>As defined in <cite>XMPP IM</cite>, presence stanzas of type "probe" are handled on behalf of the target entity by the entity's server. While normally these presence stanzas are generated by the requesting entity's server (e.g., when the requesting entity sends initial presence), the requesting entity itself (or, more precisely, its client) is allowed to generate presence stanzas of type "probe". In this document we make use of this ability to query the target entity's server regarding the entity's physical presence.</p>
<p>In the following example, a star-crossed lover pokes the server of his beloved to determine her physical presence (notice that the value of 'to' address lacks a resource identifier and therefore is a bare JID, not a full JID).</p> <p>In the following example, a star-crossed lover pokes the server of his beloved to determine her physical presence (notice that the value of 'to' address lacks a resource identifier and therefore is a bare JID, not a full JID).</p>
<example caption='Poking via the server'><![CDATA[ <example caption='Poking via the server'><![CDATA[
<presence <presence
@ -51,7 +51,7 @@
<poke xmlns='http://jabber.org/protocol/poke'/> <poke xmlns='http://jabber.org/protocol/poke'/>
</presence> </presence>
]]></example> ]]></example>
<p>If the user's server does not support the POKE protocol, it SHOULD ignore the extension and treat the presence stanza as a normal (non-IRL) presence probe. However, the user's server MAY return a "Service Unavailable" error to the requesting entity to inform the requesting entity that IRL probes are not supported (for details regarding error syntax, refer to &jep0086;):</p> <p>If the user's server does not support the POKE protocol, it SHOULD ignore the extension and treat the presence stanza as a normal (non-IRL) presence probe. However, the user's server MAY return a "Service Unavailable" error to the requesting entity to inform the requesting entity that IRL probes are not supported (for details regarding error syntax, refer to &xep0086;):</p>
<example caption='Server returns service unavailable error'><![CDATA[ <example caption='Server returns service unavailable error'><![CDATA[
<presence <presence
type='error' type='error'
@ -79,11 +79,11 @@
</error> </error>
</presence> </presence>
]]></example> ]]></example>
<p>If the requesting entity has permission to discover the user's physical presence, the server SHOULD attempt to determine if the user is physically present. Methods for doing so are implementation-specific and therefore out of scope for this JEP, but possible mechanisms might include:</p> <p>If the requesting entity has permission to discover the user's physical presence, the server SHOULD attempt to determine if the user is physically present. Methods for doing so are implementation-specific and therefore out of scope for this document, but possible mechanisms might include:</p>
<ol> <ol>
<li>sending messages to contacts in the user's roster who would be likely to have knowledge of the user's whereabouts (perhaps derived from physical proximity information gleaned from &jep0054; or &jep0080; data)</li> <li>sending messages to contacts in the user's roster who would be likely to have knowledge of the user's whereabouts (perhaps derived from physical proximity information gleaned from &xep0054; or &xep0080; data)</li>
<li>generating an IQ "get" in the 'poke' namespace to each of the user's connected resources</li> <li>generating an IQ "get" in the 'poke' namespace to each of the user's connected resources</li>
<li>sending specialized commands to each of the user's connected resources using &jep0050;</li> <li>sending specialized commands to each of the user's connected resources using &xep0050;</li>
</ol> </ol>
<p>If the server determines that the user is physically present in the vicinity of a client, it SHOULD return that information to the requesting entity, including the appropriate resource:</p> <p>If the server determines that the user is physically present in the vicinity of a client, it SHOULD return that information to the requesting entity, including the appropriate resource:</p>
<example caption='Server returns success'><![CDATA[ <example caption='Server returns success'><![CDATA[
@ -108,7 +108,7 @@
</error> </error>
</presence> </presence>
]]></example> ]]></example>
<p>The server SHOULD NOT return a "Not Found" error unless the user does not exist. If the server determines that the user has died, it MAY return a "Gone" error with appropriate descriptive text, although it SHOULD wait to do so pending notification of next-of-kin; note well that such notification is out of scope for this JEP (though this seems like a sensible application of the &jep0060; protocol):</p> <p>The server SHOULD NOT return a "Not Found" error unless the user does not exist. If the server determines that the user has died, it MAY return a "Gone" error with appropriate descriptive text, although it SHOULD wait to do so pending notification of next-of-kin; note well that such notification is out of scope for this document (though this seems like a sensible application of the &xep0060; protocol):</p>
<example caption='Server returns gone error'><![CDATA[ <example caption='Server returns gone error'><![CDATA[
<presence <presence
type='error' type='error'
@ -183,14 +183,14 @@
<p>Responding entities (whether server or client) MUST NOT return physical presence information to requesting entities that are not entitled to discover such information.</p> <p>Responding entities (whether server or client) MUST NOT return physical presence information to requesting entities that are not entitled to discover such information.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; shall add the 'http://jabber.org/protocol/poke' namespace to its registry of protocol namespaces.</p> <p>The &REGISTRAR; shall add the 'http://jabber.org/protocol/poke' namespace to its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Method Values' anchor='registrar-methods'> <section2 topic='Method Values' anchor='registrar-methods'>
<p>The Jabber Registrar shall maintain a registry of values for the 'method' attribute. The following values shall be added initially:</p> <p>The XMPP Registrar shall maintain a registry of values for the 'method' attribute. The following values shall be added initially:</p>
<ul> <ul>
<li>dna</li> <li>dna</li>
<li>infrared</li> <li>infrared</li>
@ -215,7 +215,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0132: http://www.jabber.org/jeps/jep-0132.html XEP-0132: http://www.xmpp.org/extensions/xep-0132.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -240,4 +240,4 @@
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Service Administration</title> <title>Service Administration</title>
<abstract>This JEP defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands.</abstract> <abstract>This document defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0133</number> <number>0133</number>
<status>Active</status> <status>Active</status>
@ -15,7 +15,7 @@
<jig>Standards JIG</jig> <jig>Standards JIG</jig>
<dependencies> <dependencies>
<spec>RFC 3920</spec> <spec>RFC 3920</spec>
<spec>JEP-0050</spec> <spec>XEP-0050</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
@ -73,7 +73,7 @@
<version>0.2</version> <version>0.2</version>
<date>2004-07-22</date> <date>2004-07-22</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Added several more use cases; defined complete protocol flows; specified Jabber Registrar considerations.</remark> <remark>Added several more use cases; defined complete protocol flows; specified XMPP Registrar considerations.</remark>
</revision> </revision>
<revision> <revision>
<version>0.1</version> <version>0.1</version>
@ -83,21 +83,21 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>There exists a set of common service-level tasks that administrators often need to perform in relation to Jabber/XMPP servers and components. Examples include creating users, disabling accounts, and blacklisting domains for inbound or outbound communications. Because such tasks can be performed with respect to a server or with respect to many kinds of add-on components (e.g., a text conferencing component that conforms to &jep0045;), it makes sense to define a generic protocol for such interactions. This JEP describes such a protocol by specifying a profile of &jep0050; and associated &jep0004; fields, rather than by defining a specialized and distinct protocol.</p> <p>There exists a set of common service-level tasks that administrators often need to perform in relation to Jabber/XMPP servers and components. Examples include creating users, disabling accounts, and blacklisting domains for inbound or outbound communications. Because such tasks can be performed with respect to a server or with respect to many kinds of add-on components (e.g., a text conferencing component that conforms to &xep0045;), it makes sense to define a generic protocol for such interactions. This document describes such a protocol by specifying a profile of &xep0050; and associated &xep0004; fields, rather than by defining a specialized and distinct protocol.</p>
</section1> </section1>
<section1 topic='Requirements' anchor='reqs'> <section1 topic='Requirements' anchor='reqs'>
<p>This JEP addresses the following requirements:</p> <p>This document addresses the following requirements:</p>
<ul> <ul>
<li>Enable users with appropriate privileges to perform common administrative tasks with respect to Jabber/XMPP servers and components.</li> <li>Enable users with appropriate privileges to perform common administrative tasks with respect to Jabber/XMPP servers and components.</li>
<li>Re-use existing XMPP and Jabber protocols wherever possible.</li> <li>Re-use existing XMPP and Jabber protocols wherever possible.</li>
</ul> </ul>
</section1> </section1>
<section1 topic='Discovery' anchor='disco'> <section1 topic='Discovery' anchor='disco'>
<p>A server or component MUST advertise any administrative commands it supports via &jep0030; (as described in <cite>JEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service in question.</p> <p>A server or component MUST advertise any administrative commands it supports via &xep0030; (as described in <cite>XEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service in question.</p>
<p>In order to interact with a particular component attached to a server, an administrator needs to first discover that component and the commands it support, then send the appropriate command to the component itself. A server SHOULD NOT process commands on behalf of associated components, just as it does not handle service discovery requests on behalf of such components.</p> <p>In order to interact with a particular component attached to a server, an administrator needs to first discover that component and the commands it support, then send the appropriate command to the component itself. A server SHOULD NOT process commands on behalf of associated components, just as it does not handle service discovery requests on behalf of such components.</p>
</section1> </section1>
<section1 topic='Use Cases' anchor='usecases'> <section1 topic='Use Cases' anchor='usecases'>
<p>This JEP defines a profile of <cite>JEP-0050: Ad-Hoc Commands</cite> that enables a service-level administrator to complete the following use cases:</p> <p>This document defines a profile of <cite>XEP-0050: Ad-Hoc Commands</cite> that enables a service-level administrator to complete the following use cases:</p>
<ol> <ol>
<li>Add User</li> <li>Add User</li>
<li>Delete User</li> <li>Delete User</li>
@ -131,8 +131,8 @@
<li>Restart Service</li> <li>Restart Service</li>
<li>Shut Down Service</li> <li>Shut Down Service</li>
</ol> </ol>
<p>Naturally, not all of these use cases apply to all service types (e.g., adding a user may not apply to a multi-user chat service). An implementation or deployment MAY support any subset of the use cases defined herein. In addition, although this JEP aims to define common use cases, an implementation or deployment MAY support additional commands not defined herein, which may or may not be publicly registered.</p> <p>Naturally, not all of these use cases apply to all service types (e.g., adding a user may not apply to a multi-user chat service). An implementation or deployment MAY support any subset of the use cases defined herein. In addition, although this document aims to define common use cases, an implementation or deployment MAY support additional commands not defined herein, which may or may not be publicly registered.</p>
<p><em>Note: The text that follows assumes that implementors have read and understood <cite>JEP-0050: Ad-Hoc Commands</cite> and <cite>JEP-0004: Data Forms</cite>.</em></p> <p><em>Note: The text that follows assumes that implementors have read and understood <cite>XEP-0050: Ad-Hoc Commands</cite> and <cite>XEP-0004: Data Forms</cite>.</em></p>
<section2 topic='Add User' anchor='add-user'> <section2 topic='Add User' anchor='add-user'>
<p>A user is defined as any entity that has a persistent relationship with a service (most commonly through the creation a registered account with the service) and whose account is in some sense hosted by the service. Adding a user MUST result in the creation of an account, along with any implementation-specific data for such an account (e.g., database entries or a roster file). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#add-user".</p> <p>A user is defined as any entity that has a persistent relationship with a service (most commonly through the creation a registered account with the service) and whose account is in some sense hosted by the service. Adding a user MUST result in the creation of an account, along with any implementation-specific data for such an account (e.g., database entries or a roster file). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#add-user".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
@ -1223,7 +1223,7 @@
]]></example> ]]></example>
</section2> </section2>
<section2 topic='Get Number of Online Users' anchor='get-online-users-num'> <section2 topic='Get Number of Online Users' anchor='get-online-users-num'>
<p>It may be helpful to enable an administrator to retrieve the number of registered users who are online at any one moment. By "online user" is meant any user or account that currently has an IM session, as specified in Section 3 of <cite>RFC 3921</cite> or its equivalent (e.g., &jep0078;), whether that user is actively sending XML stanzas or is idle. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users-num".</p> <p>It may be helpful to enable an administrator to retrieve the number of registered users who are online at any one moment. By "online user" is meant any user or account that currently has an IM session, as specified in Section 3 of <cite>RFC 3921</cite> or its equivalent (e.g., &xep0078;), whether that user is actively sending XML stanzas or is idle. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Online Users'><![CDATA[ <example caption='Admin Requests Number of Online Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1337,7 +1337,7 @@
]]></example> ]]></example>
</section2> </section2>
<section2 topic='Get List of Registered Users' anchor='get-registered-users-list'> <section2 topic='Get List of Registered Users' anchor='get-registered-users-list'>
<p>On a server or service without many registered users, it may be helpful to enable an administrator to retrieve a list of all registered users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this JEP). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-registered-users-list".</p> <p>On a server or service without many registered users, it may be helpful to enable an administrator to retrieve a list of all registered users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-registered-users-list".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Registered Users'><![CDATA[ <example caption='Admin Requests List of Registered Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1452,10 +1452,10 @@
</iq> </iq>
]]></example> ]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p> <p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the Jabber Registrar; however, such fields are not defined herein.</p> <p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2> </section2>
<section2 topic='Get List of Disabled Users' anchor='get-disabled-users-list'> <section2 topic='Get List of Disabled Users' anchor='get-disabled-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all disabled users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this JEP). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-disabled-users-list".</p> <p>It may be helpful to enable an administrator to retrieve a list of all disabled users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-disabled-users-list".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Disabled Users'><![CDATA[ <example caption='Admin Requests List of Disabled Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1551,10 +1551,10 @@
</iq> </iq>
]]></example> ]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p> <p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the Jabber Registrar; however, such fields are not defined herein.</p> <p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2> </section2>
<section2 topic='Get List of Online Users' anchor='get-online-users-list'> <section2 topic='Get List of Online Users' anchor='get-online-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all online users. Because the number of online users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this JEP). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users".</p> <p>It may be helpful to enable an administrator to retrieve a list of all online users. Because the number of online users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Online Users'><![CDATA[ <example caption='Admin Requests List of Online Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1660,10 +1660,10 @@
</iq> </iq>
]]></example> ]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p> <p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the Jabber Registrar; however, such fields are not defined herein.</p> <p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2> </section2>
<section2 topic='Get List of Active Users' anchor='get-active-users-list'> <section2 topic='Get List of Active Users' anchor='get-active-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all active users. Because the number of active users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this JEP). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-active-users".</p> <p>It may be helpful to enable an administrator to retrieve a list of all active users. Because the number of active users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-active-users".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Active Users'><![CDATA[ <example caption='Admin Requests List of Active Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1762,10 +1762,10 @@
</iq> </iq>
]]></example> ]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p> <p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the Jabber Registrar; however, such fields are not defined herein.</p> <p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2> </section2>
<section2 topic='Get List of Idle Users' anchor='get-idle-users-list'> <section2 topic='Get List of Idle Users' anchor='get-idle-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all idle users. Because the number of idle users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this JEP). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-idle-users".</p> <p>It may be helpful to enable an administrator to retrieve a list of all idle users. Because the number of idle users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-idle-users".</p>
<p>A sample protocol flow for this use case is shown below.</p> <p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Active Users'><![CDATA[ <example caption='Admin Requests List of Active Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe' <iq from='bard@shakespeare.lit/globe'
@ -1866,7 +1866,7 @@
</iq> </iq>
]]></example> ]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p> <p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the Jabber Registrar; however, such fields are not defined herein.</p> <p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2> </section2>
<section2 topic='Send Announcement to Online Users' anchor='announce'> <section2 topic='Send Announcement to Online Users' anchor='announce'>
<p>Administrators of some existing Jabber servers have found it useful to be able to send an announcement to all online users of the server (e.g., to announce a server shutdown); this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). The message shall be sent only to users who currently have a "session" with the service. Obviously there may be latency in sending the message if the number of active users is extremely large. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#announce".</p> <p>Administrators of some existing Jabber servers have found it useful to be able to send an announcement to all online users of the server (e.g., to announce a server shutdown); this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). The message shall be sent only to users who currently have a "session" with the service. Obviously there may be latency in sending the message if the number of active users is extremely large. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#announce".</p>
@ -2527,25 +2527,25 @@
<td>The ad-hoc commands protocol is not supported.</td> <td>The ad-hoc commands protocol is not supported.</td>
</tr> </tr>
</table> </table>
<p>For the syntax of these errors, see &jep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p> <p>For the syntax of these errors, see &xep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p> <p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; shall include the following information in its registries.</p> <p>The &REGISTRAR; shall include the following information in its registries.</p>
<section2 topic='Protocol Namespaces' anchor='registrar-protocol'> <section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
<p>Upon advancement of this JEP to a status of Active, the Jabber Registrar shall add "http://jabber.org/protocol/admin" to its registry of protocol namespaces.</p> <p>The XMPP Registrar includes "http://jabber.org/protocol/admin" in its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'> <section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&jep0068; defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. The reserved fields for the 'http://jabber.org/protocol/admin' namespace are specified below.</p> <p>&xep0068; defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. The reserved fields for the 'http://jabber.org/protocol/admin' namespace are specified below.</p>
<code caption='Registry Submission'><![CDATA[ <code caption='Registry Submission'><![CDATA[
<form_type> <form_type>
<name>http://jabber.org/protocol/admin</name> <name>http://jabber.org/protocol/admin</name>
<doc>JEP-0133</doc> <doc>XEP-0133</doc>
<desc>Forms used for administration of servers and components.</desc> <desc>Forms used for administration of servers and components.</desc>
<field var='accountjid' <field var='accountjid'
type='jid-multi' type='jid-multi'
@ -2651,6 +2651,6 @@
</section2> </section2>
</section1> </section1>
<section1 topic='XML Schema'> <section1 topic='XML Schema'>
<p>Because the protocol defined here is a profile of <cite>JEP-0050: Ad-Hoc Commands</cite>, no schema definition is needed.</p> <p>Because the protocol defined here is a profile of <cite>XEP-0050: Ad-Hoc Commands</cite>, no schema definition is needed.</p>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Protocol Design Guidelines</title> <title>Protocol Design Guidelines</title>
<abstract>This JEP defines best practices for the intelligent design of Jabber protocols and other XMPP extensions.</abstract> <abstract>This document defines best practices for the intelligent design of Jabber protocols and other XMPP extensions.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0134</number> <number>0134</number>
<status>Active</status> <status>Active</status>
@ -41,7 +41,7 @@
<version>0.2</version> <version>0.2</version>
<date>2004-08-31</date> <date>2004-08-31</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Added references to several additional RFCs and JEPs.</remark> <remark>Added references to several additional RFCs and XEPs.</remark>
</revision> </revision>
<revision> <revision>
<version>0.1</version> <version>0.1</version>
@ -58,9 +58,9 @@
<p><em>Background</em></p> <p><em>Background</em></p>
<p>When the &JSF; submitted the <cite>XMPP Core</cite> and <cite>XMPP IM</cite> specifications to the &IETF;, it ceded change control over the core XML streaming technology developed by the Jabber community. However, the JSF has reserved the right to define extensions to XMPP; furthermore, that right is not exclusive to the JSF, since anyone can define their own public or private extensions to XMPP. These extensions are usually in the form of structured XML data that is qualified by a unique namespace other than those currently reserved by the IETF or the JSF.</p> <p>When the &JSF; submitted the <cite>XMPP Core</cite> and <cite>XMPP IM</cite> specifications to the &IETF;, it ceded change control over the core XML streaming technology developed by the Jabber community. However, the JSF has reserved the right to define extensions to XMPP; furthermore, that right is not exclusive to the JSF, since anyone can define their own public or private extensions to XMPP. These extensions are usually in the form of structured XML data that is qualified by a unique namespace other than those currently reserved by the IETF or the JSF.</p>
<p><em>Meaning</em></p> <p><em>Meaning</em></p>
<p>When we say that "XMPP is Sacred", we mean that good protocol design must work within the context of XMPP and not require changes to the core protocols. For one thing, any such changes would need to be pursued within the IETF. Further, the core semantics most likely provide everything that a protocol designer needs. If you think that you need to define a new kind of top-level stanza (other than &MESSAGE;, &PRESENCE;, and &IQ;) or a new value of the 'type' attribute for any stanza kind, then you need to think again. Treat XMPP as a transport layer and build extensions on top of that layer (among other things, this implies that you must not modify the foundation when you are working on higher-level structures, for example by adding adding elements and attributes to the XMPP schemas on the theory that if applications will ignore them; define your own extensions in a separate namespace). A further implication of respecting XMPP is using structured data formats (e.g., applications of &w3xml; rather than binary or plaintext formats) whenever possible. Finally, as explained in <cite>XMPP Core</cite>, the &PRESENCE; stanza exists to broadcast network and communications availability only; for more advanced information publishing, use &jep0060;.</p> <p>When we say that "XMPP is Sacred", we mean that good protocol design must work within the context of XMPP and not require changes to the core protocols. For one thing, any such changes would need to be pursued within the IETF. Further, the core semantics most likely provide everything that a protocol designer needs. If you think that you need to define a new kind of top-level stanza (other than &MESSAGE;, &PRESENCE;, and &IQ;) or a new value of the 'type' attribute for any stanza kind, then you need to think again. Treat XMPP as a transport layer and build extensions on top of that layer (among other things, this implies that you must not modify the foundation when you are working on higher-level structures, for example by adding adding elements and attributes to the XMPP schemas on the theory that if applications will ignore them; define your own extensions in a separate namespace). A further implication of respecting XMPP is using structured data formats (e.g., applications of &w3xml; rather than binary or plaintext formats) whenever possible. Finally, as explained in <cite>XMPP Core</cite>, the &PRESENCE; stanza exists to broadcast network and communications availability only; for more advanced information publishing, use &xep0060;.</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>A good example of honoring the XMPP specifications is &jep0126;; while the Jabber community had informally defined &lt;presence type='invisible'/&gt; at one point, that protocol was abandoned in favor of an XMPP-compliant approach. Another example is &jep0071;, which re-uses &w3xhtml; (a structured format that shares with XMPP a common root in XML) rather than &rtf; (an unstructured format that does not derive from XML). Further examples are the "extended presence" JEPS (see &jep0119;), which are built on top of JEP-0060 rather than overloading the &PRESENCE; stanza.</p> <p>A good example of honoring the XMPP specifications is &xep0126;; while the Jabber community had informally defined &lt;presence type='invisible'/&gt; at one point, that protocol was abandoned in favor of an XMPP-compliant approach. Another example is &xep0071;, which re-uses &w3xhtml; (a structured format that shares with XMPP a common root in XML) rather than &rtf; (an unstructured format that does not derive from XML). Further examples are the "extended presence" speficiations (see &xep0119;), which are built on top of XEP-0060 rather than overloading the &PRESENCE; stanza.</p>
</section2> </section2>
<section2 topic='Keep Clients Simple' anchor='simple'> <section2 topic='Keep Clients Simple' anchor='simple'>
<p><em>Background</em></p> <p><em>Background</em></p>
@ -74,15 +74,15 @@
<li>Don't force additional requirements (such as XSLT processors) onto clients unless absolutely necessary.</li> <li>Don't force additional requirements (such as XSLT processors) onto clients unless absolutely necessary.</li>
</ul> </ul>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>One good example of keeping clients simple is the presence stanza: the client has only to send &PRESENCE; and the server takes care of presence probes, broadcasts, and appropriate routing decisions. Another example is &jep0045;: although the protocol involves some complexity, it was written so that older clients can join and participate in MUC rooms even if they don't understand the more advanced MUC extensions.</p> <p>One good example of keeping clients simple is the presence stanza: the client has only to send &PRESENCE; and the server takes care of presence probes, broadcasts, and appropriate routing decisions. Another example is &xep0045;: although the protocol involves some complexity, it was written so that older clients can join and participate in MUC rooms even if they don't understand the more advanced MUC extensions.</p>
</section2> </section2>
<section2 topic='Re-Use Existing Protocols' anchor='reuse'> <section2 topic='Re-Use Existing Protocols' anchor='reuse'>
<p><em>Background</em></p> <p><em>Background</em></p>
<p>The Jabber community has been developing wire protocols for XML streaming, presence, and instant messaging since 1999. In that time, members of the community have defined a number of building blocks that can be used as the basis for further development. Furthermore, many smart people have created open protocols within other standards development organizations, including the IETF, the &W3C;, &OASIS;, the &ITU;, and the &DUBLINCORE;.</p> <p>The Jabber community has been developing wire protocols for XML streaming, presence, and instant messaging since 1999. In that time, members of the community have defined a number of building blocks that can be used as the basis for further development. Furthermore, many smart people have created open protocols within other standards development organizations, including the IETF, the &W3C;, &OASIS;, the &ITU;, and the &DUBLINCORE;.</p>
<p><em>Meaning</em></p> <p><em>Meaning</em></p>
<p>Good protocol designers "stand on the shoulders of giants" by re-using protocols that have been defined within the JSF and within other standards development organizations. That does not mean we don't define new protocols, because sometimes that is necessary. However, we are aware of work completed by others and we make use of it, especially when that work is outside the Jabber community's core competence areas (e.g., security or multimedia data formats rather than XML streaming, presence, and real-time messaging). Furthermore, the JSF prefers to re-use open protocols wherever possible. Finally, just as with XMPP, so also with XMPP extensions defined through the JSF: do not modify existing schemas (e.g., adding new elements and attributes) except through the JEP process; instead, define extensions in a separate namespace).</p> <p>Good protocol designers "stand on the shoulders of giants" by re-using protocols that have been defined within the JSF and within other standards development organizations. That does not mean we don't define new protocols, because sometimes that is necessary. However, we are aware of work completed by others and we make use of it, especially when that work is outside the Jabber community's core competence areas (e.g., security or multimedia data formats rather than XML streaming, presence, and real-time messaging). Furthermore, the JSF prefers to re-use open protocols wherever possible. Finally, just as with XMPP, so also with XMPP extensions defined through the JSF: do not modify existing schemas (e.g., adding new elements and attributes) except through the XMPP extension process; instead, define extensions in a separate namespace).</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>Examples of re-using existing Jabber protocols include &jep0095; (which re-uses &jep0020;) and <cite>JEP-0126: Invisibility</cite> (which re-uses the privacy lists protocol defined in <cite>XMPP IM</cite>). Examples of re-using non-Jabber protocols include &jep0065; (which makes use of &rfc1928;) and &jep0127; (which defines a way to send &oasiscap; data via Jabber). Here again JEP-0071 provides an example: it re-uses XHTML 1.0 (an open protocol developed by a recognized standards development organization) rather than RTF (a closed protocol under the control of the Microsoft Corporation).</p> <p>Examples of re-using existing Jabber protocols include &xep0095; (which re-uses &xep0020;) and <cite>XEP-0126: Invisibility</cite> (which re-uses the privacy lists protocol defined in <cite>XMPP IM</cite>). Examples of re-using non-Jabber protocols include &xep0065; (which makes use of &rfc1928;) and &xep0127; (which defines a way to send &oasiscap; data via Jabber). Here again XEP-0071 provides an example: it re-uses XHTML 1.0 (an open protocol developed by a recognized standards development organization) rather than RTF (a closed protocol under the control of the Microsoft Corporation).</p>
</section2> </section2>
<section2 topic='Modular is Better' anchor='modular'> <section2 topic='Modular is Better' anchor='modular'>
<p><em>Background</em></p> <p><em>Background</em></p>
@ -90,7 +90,7 @@
<p><em>Meaning</em></p> <p><em>Meaning</em></p>
<p>The best Jabber protocols are quite focused and provide limited but powerful functionality that can be applied in a specific domain or, sometimes, re-used by other Jabber protocols. Even if the domain is more complex, a protocol that addresses it needs to clearly define its scope, limit that scope as much as possible, and specify only the protocols necessary to meet the core requirements.</p> <p>The best Jabber protocols are quite focused and provide limited but powerful functionality that can be applied in a specific domain or, sometimes, re-used by other Jabber protocols. Even if the domain is more complex, a protocol that addresses it needs to clearly define its scope, limit that scope as much as possible, and specify only the protocols necessary to meet the core requirements.</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>&jep0030; and &jep0004; are good examples of focused, single-purpose protocols. By contrast, <cite>Multi-User Chat</cite> is more complex, but it limits itself to the domain of text conferencing in the context of virtual rooms (e.g., it does not address service-level administration) and consists of separate namespaces for end-user, moderator, and room owner functionality. A good example of a protocol that is focused on a smaller domain is &jep0144;.</p> <p>&xep0030; and &xep0004; are good examples of focused, single-purpose protocols. By contrast, <cite>Multi-User Chat</cite> is more complex, but it limits itself to the domain of text conferencing in the context of virtual rooms (e.g., it does not address service-level administration) and consists of separate namespaces for end-user, moderator, and room owner functionality. A good example of a protocol that is focused on a smaller domain is &xep0144;.</p>
</section2> </section2>
<section2 topic='Know Your Strengths' anchor='strengths'> <section2 topic='Know Your Strengths' anchor='strengths'>
<p><em>Background</em></p> <p><em>Background</em></p>
@ -100,13 +100,13 @@
<note>There are no hard-and-fast rules regarding a reasonable upper limit on the average XML stanza. (Note the use of both 'reasonable' and 'average' in that sentence.) In reality, there is a continuum of stanza sizes, and different sizes may be appropriate for different types of XMPP applications and deployments. While sending 2 gigabyte or 2 megabyte stanzas is wrong in the current context of Jabber technologies, we cannot legitimately say that a 2 kilobyte, 20 kilobyte, or even 200 kilobyte stanza is unreasonable. Is the stanza sent over an open network with current server implementations, or over a closed network with specially tuned servers and clients? Does the application generate one such stanza every second, every minute, every hour? Considerations of this kind help us determine if the use of XMPP is "reasonable" in some sense. However, when protocol extensions are defined in Jabber Enhancement Proposals, the Jabber Council will require clear explanation of design choices and reasonable stanza size limits if the extension will generally require what might be considered larger than normal stanzas.</note> <note>There are no hard-and-fast rules regarding a reasonable upper limit on the average XML stanza. (Note the use of both 'reasonable' and 'average' in that sentence.) In reality, there is a continuum of stanza sizes, and different sizes may be appropriate for different types of XMPP applications and deployments. While sending 2 gigabyte or 2 megabyte stanzas is wrong in the current context of Jabber technologies, we cannot legitimately say that a 2 kilobyte, 20 kilobyte, or even 200 kilobyte stanza is unreasonable. Is the stanza sent over an open network with current server implementations, or over a closed network with specially tuned servers and clients? Does the application generate one such stanza every second, every minute, every hour? Considerations of this kind help us determine if the use of XMPP is "reasonable" in some sense. However, when protocol extensions are defined in Jabber Enhancement Proposals, the Jabber Council will require clear explanation of design choices and reasonable stanza size limits if the extension will generally require what might be considered larger than normal stanzas.</note>
is probably not a good idea, and applications that would depend on such behavior are better designed to communicate their data out of band.</p> is probably not a good idea, and applications that would depend on such behavior are better designed to communicate their data out of band.</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>&jep0096; is a good example of respecting the strengths and weaknesses of XMPP, since it specifies that going out of band is the preferred mechanism for bandwidth-heavy data transfers.</p> <p>&xep0096; is a good example of respecting the strengths and weaknesses of XMPP, since it specifies that going out of band is the preferred mechanism for bandwidth-heavy data transfers.</p>
</section2> </section2>
<section2 topic='Be Explicit' anchor='explicit'> <section2 topic='Be Explicit' anchor='explicit'>
<p><em>Background</em></p> <p><em>Background</em></p>
<p>In the beginning was the code (mainly &jabberd;). Although code is explicit in its own way, not everyone reads code, and detailed specifications are necessary in order to make functionality reproducible in different codebases. The Jabber community has learned that lesson the hard way.</p> <p>In the beginning was the code (mainly &jabberd;). Although code is explicit in its own way, not everyone reads code, and detailed specifications are necessary in order to make functionality reproducible in different codebases. The Jabber community has learned that lesson the hard way.</p>
<p><em>Meaning</em></p> <p><em>Meaning</em></p>
<p>Detailed, explicit specifications are good specifications. Define your terms. Use conformance terminology such as MUST and SHOULD rather than loose English words such as "does" and "will". Follow the &jep0143;. Specify error conditions. Include lots of examples. Restrict the allowable XML via schemas and datatypes as specified in &w3xmlschema1; and &w3xmlschema2;.</p> <p>Detailed, explicit specifications are good specifications. Define your terms. Use conformance terminology such as MUST and SHOULD rather than loose English words such as "does" and "will". Follow the &xep0143;. Specify error conditions. Include lots of examples. Restrict the allowable XML via schemas and datatypes as specified in &w3xmlschema1; and &w3xmlschema2;.</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p><cite>XMPP Core</cite> and <cite>XMPP IM</cite> are large documents that define the Extensible Messaging and Presence Protocol in excruciating detail. Although such specifications are not fun to write, they provide a model for good protocol design and documentation.</p> <p><cite>XMPP Core</cite> and <cite>XMPP IM</cite> are large documents that define the Extensible Messaging and Presence Protocol in excruciating detail. Although such specifications are not fun to write, they provide a model for good protocol design and documentation.</p>
</section2> </section2>
@ -116,7 +116,7 @@
<p><em>Meaning</em></p> <p><em>Meaning</em></p>
<p>In general, a protocol needs to define the skeleton of functionality, but not necessarily specific parameters or values to be used within a certain domain. In order to allow for growth and change, it often makes sense to specify that the &REGISTRAR; shall keep track of certain parameters and values, rather than to explicitly limit them in the protocol itself.</p> <p>In general, a protocol needs to define the skeleton of functionality, but not necessarily specific parameters or values to be used within a certain domain. In order to allow for growth and change, it often makes sense to specify that the &REGISTRAR; shall keep track of certain parameters and values, rather than to explicitly limit them in the protocol itself.</p>
<p><em>Examples</em></p> <p><em>Examples</em></p>
<p>Whereas the old &jep0094; and &jep0011; protocols defined certain hardcoded values for entity types and categories, <cite>Service Discovery</cite> has left that function up to the Jabber Registrar. Similarly, &jep0095; defines a registry for its profiles, &jep0079; defines registries for processing conditions and actions, and a number of JEPs register FORM_TYPE values as specified in &jep0068;.</p> <p>Whereas the old &xep0094; and &xep0011; protocols defined certain hardcoded values for entity types and categories, <cite>Service Discovery</cite> has left that function up to the XMPP Registrar. Similarly, &xep0095; defines a registry for its profiles, &xep0079; defines registries for processing conditions and actions, and a number of XMPP Extension Protocols register FORM_TYPE values as specified in &xep0068;.</p>
</section2> </section2>
<section2 topic='Privacy and Security Matter' anchor='privacy'> <section2 topic='Privacy and Security Matter' anchor='privacy'>
<p><em>Background</em></p> <p><em>Background</em></p>
@ -131,9 +131,9 @@
<p>There are no security features or concerns directly related to this proposal, which is informational in nature. However, as discussed above, protocols that are developed following these guidelines should appropriately address privacy and security considerations. Helpful guidelines for security in relation to Internet protocol design can be found in &rfc3552;.</p> <p>There are no security features or concerns directly related to this proposal, which is informational in nature. However, as discussed above, protocols that are developed following these guidelines should appropriately address privacy and security considerations. Helpful guidelines for security in relation to Internet protocol design can be found in &rfc3552;.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>This JEP requires no interaction with the Jabber Registrar.</p> <p>This document requires no interaction with the XMPP Registrar.</p>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>File Sharing</title> <title>File Sharing</title>
<abstract>This JEP specifies a simple extension to existing protocols for file sharing over Jabber/XMPP.</abstract> <abstract>This document specifies a simple extension to existing protocols for file sharing over Jabber/XMPP.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0135</number> <number>0135</number>
<status>Deferred</status> <status>Deferred</status>
@ -15,8 +15,8 @@
<jig>Standards JIG</jig> <jig>Standards JIG</jig>
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>JEP-0030</spec> <spec>XEP-0030</spec>
<spec>JEP-0096</spec> <spec>XEP-0096</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
@ -30,12 +30,12 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>Existing Jabber protocols provide a strong foundation for the controlled, permissions-based sharing of files between Jabber entities, e.g., to enable shared workspaces among ad-hoc workgroups and the attachment of files to &jep0045; rooms.</p> <p>Existing Jabber protocols provide a strong foundation for the controlled, permissions-based sharing of files between Jabber entities, e.g., to enable shared workspaces among ad-hoc workgroups and the attachment of files to &xep0045; rooms.</p>
<p>This document defines several additional building blocks (a simple request protocol along with well-known service discovery nodes) that tie together existing protocols to enable the sharing of files between Jabber entities.</p> <p>This document defines several additional building blocks (a simple request protocol along with well-known service discovery nodes) that tie together existing protocols to enable the sharing of files between Jabber entities.</p>
</section1> </section1>
<section1 topic='Requirements' anchor='reqs'> <section1 topic='Requirements' anchor='reqs'>
<ol> <ol>
<li>Enable a requesting entity to find files shared by an offering entity without depending on third parties (such as &jep0060; services or dedicated <link url="#hosting">file-hosting services</link>) (REQUIRED).</li> <li>Enable a requesting entity to find files shared by an offering entity without depending on third parties (such as &xep0060; services or dedicated <link url="#hosting">file-hosting services</link>) (REQUIRED).</li>
<li>Enable a requesting entity to discover detailed file information (OPTIONAL).</li> <li>Enable a requesting entity to discover detailed file information (OPTIONAL).</li>
<li>Enable a requesting entity to ask for files shared by an offering entity (REQUIRED).</li> <li>Enable a requesting entity to ask for files shared by an offering entity (REQUIRED).</li>
<li>Re-use existing Jabber/XMPP protocols wherever possible.</li> <li>Re-use existing Jabber/XMPP protocols wherever possible.</li>
@ -46,7 +46,7 @@
</section1> </section1>
<section1 topic='Discovering Support and Address of Offering Entity' anchor='disco'> <section1 topic='Discovering Support and Address of Offering Entity' anchor='disco'>
<section2 topic='Offering Entity is File Owner' anchor='disco-owner'> <section2 topic='Offering Entity is File Owner' anchor='disco-owner'>
<p>If an entity directly supports the protocol defined herein, it SHOULD include a feature of "http://jabber.org/protocol/files" in its response to a &jep0030; information request. The protocol flow is shown in the following example (an end user querying a chatroom):</p> <p>If an entity directly supports the protocol defined herein, it SHOULD include a feature of "http://jabber.org/protocol/files" in its response to a &xep0030; information request. The protocol flow is shown in the following example (an end user querying a chatroom):</p>
<example caption='User Queries a Room Regarding Support'><![CDATA[ <example caption='User Queries a Room Regarding Support'><![CDATA[
<iq type='get' <iq type='get'
from='hag66@shakespeare.lit/pda' from='hag66@shakespeare.lit/pda'
@ -67,7 +67,7 @@
</query> </query>
</iq> </iq>
]]></example> ]]></example>
<p>This JEP stipulates that communications regarding files MUST occur by sending stanzas to the well-known service discovery node "files" (or sub-nodes thereof as defined below). Therefore, even if (as in the foregoing example) the file owner directly supports the protocol defined herein, the requesting entity MUST send subsequent file-related service discovery requests to the node "files" (or sub-nodes thereof). The file owner also SHOULD list that node in its response to a service discovery items request, as shown in the following example:</p> <p>This document stipulates that communications regarding files MUST occur by sending stanzas to the well-known service discovery node "files" (or sub-nodes thereof as defined below). Therefore, even if (as in the foregoing example) the file owner directly supports the protocol defined herein, the requesting entity MUST send subsequent file-related service discovery requests to the node "files" (or sub-nodes thereof). The file owner also SHOULD list that node in its response to a service discovery items request, as shown in the following example:</p>
<example caption='User Queries a Room Regarding Items'><![CDATA[ <example caption='User Queries a Room Regarding Items'><![CDATA[
<iq type='get' <iq type='get'
from='hag66@shakespeare.lit/pda' from='hag66@shakespeare.lit/pda'
@ -174,7 +174,7 @@
</query> </query>
</iq> </iq>
]]></example> ]]></example>
<p>Note: The NodeID MUST begin with the string 'files' followed by the '/' character followed the name of the directory or file; further subdirectories or files within a directory MUST follow the same pattern (e.g., "files/somedir/anotherfile"). Thus the protocol defined herein enforces semantic meaning on NodeIDs; this is OPTIONAL within <strong>Service Discovery</strong> but REQUIRED by this JEP.</p> <p>Note: The NodeID MUST begin with the string 'files' followed by the '/' character followed the name of the directory or file; further subdirectories or files within a directory MUST follow the same pattern (e.g., "files/somedir/anotherfile"). Thus the protocol defined herein enforces semantic meaning on NodeIDs; this is OPTIONAL within <strong>Service Discovery</strong> but REQUIRED by this document.</p>
<p>If the offering entity has only a few files to share, it may be appropriate to make them available via service discovery only, thus requiring the requesting entity to "walk the tree" of directories and files as described in the <link url="#find-disco">Finding All Files via Service Discovery</link> section. However, if the offering entity has a larger number of files to share, the number of service discovery requests and responses required to "walk the tree" of all directories and files might result in excessive amounts of traffic between the requesting entity and the offering entity; in this case, the offering entity SHOULD provide a "tree file" that defines the hierarchy of directories and files in the standardized format specified in the <link url="#find-tree">Retrieving the Tree File</link> section. The number of files that counts as "large" is not defined herein and is left up to the implementation or deployment; in practice, it is RECOMMENDED for the offering entity to provide a tree file if it has more than five (5) files to share.</p> <p>If the offering entity has only a few files to share, it may be appropriate to make them available via service discovery only, thus requiring the requesting entity to "walk the tree" of directories and files as described in the <link url="#find-disco">Finding All Files via Service Discovery</link> section. However, if the offering entity has a larger number of files to share, the number of service discovery requests and responses required to "walk the tree" of all directories and files might result in excessive amounts of traffic between the requesting entity and the offering entity; in this case, the offering entity SHOULD provide a "tree file" that defines the hierarchy of directories and files in the standardized format specified in the <link url="#find-tree">Retrieving the Tree File</link> section. The number of files that counts as "large" is not defined herein and is left up to the implementation or deployment; in practice, it is RECOMMENDED for the offering entity to provide a tree file if it has more than five (5) files to share.</p>
</section2> </section2>
<section2 topic='Finding All Files via Service Discovery' anchor='find-disco'> <section2 topic='Finding All Files via Service Discovery' anchor='find-disco'>
@ -343,7 +343,7 @@ share
]]></code> ]]></code>
</section2> </section2>
<section2 topic='Retrieving the Tree File' anchor='find-tree'> <section2 topic='Retrieving the Tree File' anchor='find-tree'>
<p>Obviously, finding all files via service discovery is a tedious process. Therefore, it is RECOMMENDED that the offering entity provide a "tree file" if it has more than five (5) files to share. The format of the tree file is defined by the 'http://jabber.org/profile/si/profile/tree-transfer' namespace that is specified in &jep0105;. The tree file MUST be named "tree.xml" and MUST be available at the well-known service discovery node "tree.xml". The offering entity MAY create a different tree file for each requesting entity (depending on the requesting entity's permissions to view certain directories and files); for this reason, the tree file SHOULD NOT be contained in the root "files" directory itself (note that its NodeID is "tree.xml", not "files/tree.xml").</p> <p>Obviously, finding all files via service discovery is a tedious process. Therefore, it is RECOMMENDED that the offering entity provide a "tree file" if it has more than five (5) files to share. The format of the tree file is defined by the 'http://jabber.org/profile/si/profile/tree-transfer' namespace that is specified in &xep0105;. The tree file MUST be named "tree.xml" and MUST be available at the well-known service discovery node "tree.xml". The offering entity MAY create a different tree file for each requesting entity (depending on the requesting entity's permissions to view certain directories and files); for this reason, the tree file SHOULD NOT be contained in the root "files" directory itself (note that its NodeID is "tree.xml", not "files/tree.xml").</p>
<p>If the offering entity provides a tree file, it MUST communicate that fact in the disco#items result it returns to the requesting entity in response to the initial request:</p> <p>If the offering entity provides a tree file, it MUST communicate that fact in the disco#items result it returns to the requesting entity in response to the initial request:</p>
<example caption='Requesting the File List'><![CDATA[ <example caption='Requesting the File List'><![CDATA[
<iq type='get' <iq type='get'
@ -393,7 +393,7 @@ share
</section2> </section2>
<section2 topic='Determining File Details' anchor='find-details'> <section2 topic='Determining File Details' anchor='find-details'>
<p>As is evident from the foregoing examples, neither "walking the tree" via <strong>Service Discovery</strong> nor retrieving the tree file will yield the kind of detailed information about a file (MIME type, file size, descriptive text, etc.) that can help a user or application decide whether to retrieve the file.</p> <p>As is evident from the foregoing examples, neither "walking the tree" via <strong>Service Discovery</strong> nor retrieving the tree file will yield the kind of detailed information about a file (MIME type, file size, descriptive text, etc.) that can help a user or application decide whether to retrieve the file.</p>
<p>To address the felt need for more detailed information about files, an offering entity MAY provide such information in response to disco#info requests sent to a specific NodeID (file or directory) by including extended information structured according to &jep0128;. The following examples illustrate this usage.</p> <p>To address the felt need for more detailed information about files, an offering entity MAY provide such information in response to disco#info requests sent to a specific NodeID (file or directory) by including extended information structured according to &xep0128;. The following examples illustrate this usage.</p>
<example caption='Requesting File Information'><![CDATA[ <example caption='Requesting File Information'><![CDATA[
<iq type='get' <iq type='get'
from='hag66@shakespeare.lit/pda' from='hag66@shakespeare.lit/pda'
@ -434,7 +434,7 @@ share
</query> </query>
</iq> </iq>
]]></example> ]]></example>
<p>The fields shown are RECOMMENDED, and are specified more fully in the <link url='#registrar'>Jabber Registrar Considerations</link> section of this document.</p> <p>The fields shown are RECOMMENDED, and are specified more fully in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document.</p>
</section2> </section2>
</section1> </section1>
<section1 topic='Retrieving a File' anchor='retrieve'> <section1 topic='Retrieving a File' anchor='retrieve'>
@ -449,7 +449,7 @@ share
</iq> </iq>
]]></example> ]]></example>
<p>Note: If the requested file was found by means of the tree file rather than service discovery, the NodeID of the retrieve request MUST be constructed according to the rules specified above for service discovery NodeIDs (i.e., 'files' followed by the '/' character followed by the name of the directory or file, followed by additional '/' characters and subdirectory or file names as needed).</p> <p>Note: If the requested file was found by means of the tree file rather than service discovery, the NodeID of the retrieve request MUST be constructed according to the rules specified above for service discovery NodeIDs (i.e., 'files' followed by the '/' character followed by the name of the directory or file, followed by additional '/' characters and subdirectory or file names as needed).</p>
<p>If the offering entity agrees to share the file with the requesting entity, it MUST return an IQ result to the requesting entity and then immediately initiate a file transfer to the requesting entity following the protocol defined in &jep0096;:</p> <p>If the offering entity agrees to share the file with the requesting entity, it MUST return an IQ result to the requesting entity and then immediately initiate a file transfer to the requesting entity following the protocol defined in &xep0096;:</p>
<example caption='Offering Entity Agrees to Share File'><![CDATA[ <example caption='Offering Entity Agrees to Share File'><![CDATA[
<iq type='result' id='retrieve1'/> <iq type='result' id='retrieve1'/>
]]></example> ]]></example>
@ -477,53 +477,53 @@ share
</si> </si>
</iq> </iq>
]]></example> ]]></example>
<p>The value of the &lt;si/&gt; element's 'id' attribute MUST be the same as the value of the 'sid' attribute communicated in the tree file or the 'name' attribute communicated via service discovery; for this reason, the service discovery 'name' attribute is REQUIRED for NodeIDs that correspond to files, and its value MUST follow the rules for the 'sid' attribute specified in JEP-0105.</p> <p>The value of the &lt;si/&gt; element's 'id' attribute MUST be the same as the value of the 'sid' attribute communicated in the tree file or the 'name' attribute communicated via service discovery; for this reason, the service discovery 'name' attribute is REQUIRED for NodeIDs that correspond to files, and its value MUST follow the rules for the 'sid' attribute specified in XEP-0105.</p>
<p>Upon receiving the file transfer initiation from the offering entity, the requesting entity SHOULD check the SI 'id' in order to correlate the file transfer with the request; if there is a match, the requesting entity SHOULD silently accept the file transfer and not require intervention by a human before proceeding.</p> <p>Upon receiving the file transfer initiation from the offering entity, the requesting entity SHOULD check the SI 'id' in order to correlate the file transfer with the request; if there is a match, the requesting entity SHOULD silently accept the file transfer and not require intervention by a human before proceeding.</p>
<p>If the offering entity does not agree to share the file with the requesting entity, it MUST return an appropriate IQ error to the requesting entity, such as "Not Authorized", "Forbidden", "Payment Required", "Registration Required", or "Not Found" (see &jep0086; regarding error syntax).</p> <p>If the offering entity does not agree to share the file with the requesting entity, it MUST return an appropriate IQ error to the requesting entity, such as "Not Authorized", "Forbidden", "Payment Required", "Registration Required", or "Not Found" (see &xep0086; regarding error syntax).</p>
</section1> </section1>
<section1 topic='File-Hosting Services' anchor='hosting'> <section1 topic='File-Hosting Services' anchor='hosting'>
<p>A dedicated file-hosting service may agree to host files on behalf of a user or other entity, in which case the hosting service (or, to be precise, a specific resource of the hosting service) becomes the offering entity in the use cases defined herein. While the nature of such hosting services is outside the scope of this document, the following guidelines may be helpful to implementers.</p> <p>A dedicated file-hosting service may agree to host files on behalf of a user or other entity, in which case the hosting service (or, to be precise, a specific resource of the hosting service) becomes the offering entity in the use cases defined herein. While the nature of such hosting services is outside the scope of this document, the following guidelines may be helpful to implementers.</p>
<p>First, a file-hosting service SHOULD provide a distinct JID for each account on the service in order to enable communications between the requesting entity and the hosting service. For example, let us suppose that &lt;files.shakespeare.lit&gt; is a file-hosting service; specific accounts on the service could be structured as JIDs of the form &lt;account@files.shakespeare.lit&gt; or &lt;files.shakespeare.lit/account&gt;, in which case the requesting entity would communicate directly with that JID and treat that JID as the offering entity. The file-hosting service SHOULD enable the file owner (e.g., an end user whose JID is &lt;romeo@montague.net&gt;) to upload files to the service using standard Internet protocols (such as HTTP, FTP, scp, or JEP-0096), control who can view or retrieve files, and otherwise configure the offering entity. The file owner SHOULD also list the JID of the "offering entity" in response to service discovery items requests sent to the user's bare JID, so that requesting entities can find files hosted by the service on the file owner's behalf.</p> <p>First, a file-hosting service SHOULD provide a distinct JID for each account on the service in order to enable communications between the requesting entity and the hosting service. For example, let us suppose that &lt;files.shakespeare.lit&gt; is a file-hosting service; specific accounts on the service could be structured as JIDs of the form &lt;account@files.shakespeare.lit&gt; or &lt;files.shakespeare.lit/account&gt;, in which case the requesting entity would communicate directly with that JID and treat that JID as the offering entity. The file-hosting service SHOULD enable the file owner (e.g., an end user whose JID is &lt;romeo@montague.net&gt;) to upload files to the service using standard Internet protocols (such as HTTP, FTP, scp, or XEP-0096), control who can view or retrieve files, and otherwise configure the offering entity. The file owner SHOULD also list the JID of the "offering entity" in response to service discovery items requests sent to the user's bare JID, so that requesting entities can find files hosted by the service on the file owner's behalf.</p>
<p>It is possible that some Jabber server deployments would choose to offer file-hosting capabilities for their users (if supported in the underlying server implementation), so that the offering entity would have the same &lt;user@host&gt; address as the file owner. In this case, the server itself can be considered a file-hosting service.</p> <p>It is possible that some Jabber server deployments would choose to offer file-hosting capabilities for their users (if supported in the underlying server implementation), so that the offering entity would have the same &lt;user@host&gt; address as the file owner. In this case, the server itself can be considered a file-hosting service.</p>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>Managing access to files and directories is the responsibility of the offering entity. However, the offering entity SHOULD NOT share files with requesting entities that are not known to it via presence subscription, prior registration, room occupancy, or some similar mechanism.</p> <p>Managing access to files and directories is the responsibility of the offering entity. However, the offering entity SHOULD NOT share files with requesting entities that are not known to it via presence subscription, prior registration, room occupancy, or some similar mechanism.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>No interaction with &IANA; is required as a result of this JEP.</p> <p>No interaction with &IANA; is required as a result of this document.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>Upon advancement of this JEP to a status of Draft, the &REGISTRAR; shall add the 'http://jabber.org/protocol/files' namespace to its registry of protocol namespaces.</p> <p>Upon advancement of this document to a status of Draft, the &REGISTRAR; shall add the 'http://jabber.org/protocol/files' namespace to its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-nodes'> <section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-nodes'>
<p>Upon advancement of this JEP to a status of Draft, the Jabber Registrar shall add 'files' and 'tree.xml' to its registry of well-known service discovery nodes.</p> <p>Upon advancement of this document to a status of Draft, the XMPP Registrar shall add 'files' and 'tree.xml' to its registry of well-known service discovery nodes.</p>
</section2> </section2>
<section2 topic='Service Discovery Identities' anchor='registrar-identities'> <section2 topic='Service Discovery Identities' anchor='registrar-identities'>
<p>Upon advancement of this JEP to a status of Draft, the Jabber Registrar shall add a category of 'filesys' to its registry of service discovery identities, with two associated types: 'directory' and 'file'.</p> <p>Upon advancement of this document to a status of Draft, the XMPP Registrar shall add a category of 'filesys' to its registry of service discovery identities, with two associated types: 'directory' and 'file'.</p>
</section2> </section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'> <section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&jep0068; defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. This JEP reserves the FORM_TYPE "http://jabber.org/protocol/files" as well as specific fields for use within the context of that FORM_TYPE, as specified in the following registry submission.</p> <p>&xep0068; defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. This document reserves the FORM_TYPE "http://jabber.org/protocol/files" as well as specific fields for use within the context of that FORM_TYPE, as specified in the following registry submission.</p>
<code caption='Registry Submission'><![CDATA[ <code caption='Registry Submission'><![CDATA[
<form_type> <form_type>
<name>http://jabber.org/protocol/files</name> <name>http://jabber.org/protocol/files</name>
<doc>JEP-01xx</doc> <doc>XEP-01xx</doc>
<desc>Service Discovery extension for file descriptions.</desc> <desc>Service Discovery extension for file descriptions.</desc>
<field var='date' <field var='date'
type='text-single' type='text-single'
label='Equivalent to date attribute from JEP-0096'/> label='Equivalent to date attribute from XEP-0096'/>
<field var='description' <field var='description'
type='text-single' type='text-single'
label='Equivalent to desc element from JEP-0096'/> label='Equivalent to desc element from XEP-0096'/>
<field var='hash' <field var='hash'
type='text-single' type='text-single'
label='Equivalent to hash attribute from JEP-0096'/> label='Equivalent to hash attribute from XEP-0096'/>
<field var='mime-type' <field var='mime-type'
type='text-single' type='text-single'
label='Equivalent to mime-type attribute from JEP-0095'/> label='Equivalent to mime-type attribute from XEP-0095'/>
<field var='size' <field var='size'
type='text-single' type='text-single'
label='Equivalent to size attribute from JEP-0096'/> label='Equivalent to size attribute from XEP-0096'/>
</form_type> </form_type>
]]></code> ]]></code>
</section2> </section2>
@ -557,4 +557,4 @@ share
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,10 +1,10 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Message Archiving</title> <title>Message Archiving</title>
<abstract>This document defines mechanisms and preferences for the archiving and retrieval of XMPP messages.</abstract> <abstract>This document defines mechanisms and preferences for the archiving and retrieval of XMPP messages.</abstract>
@ -16,11 +16,11 @@
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>XMPP IM</spec> <spec>XMPP IM</spec>
<spec>JEP-0030</spec> <spec>XEP-0030</spec>
<spec>JEP-0059</spec> <spec>XEP-0059</spec>
<spec>JEP-0060</spec> <spec>XEP-0060</spec>
<spec>JEP-0155</spec> <spec>XEP-0155</spec>
<spec>JEP-0163</spec> <spec>XEP-0163</spec>
<spec>W3C XML Encryption</spec> <spec>W3C XML Encryption</spec>
<spec>W3C XML Signature</spec> <spec>W3C XML Signature</spec>
</dependencies> </dependencies>
@ -52,7 +52,7 @@
<version>0.7</version> <version>0.7</version>
<date>2006-09-08</date> <date>2006-09-08</date>
<initials>ip</initials> <initials>ip</initials>
<remark><p>Added preferences, results set management and notes; reinstated encryption and replication; simplified auto-archiving and off-the-record (with JEP-0155); many minor changes</p></remark> <remark><p>Added preferences, results set management and notes; reinstated encryption and replication; simplified auto-archiving and off-the-record (with XEP-0155); many minor changes</p></remark>
</revision> </revision>
<revision> <revision>
<version>0.6</version> <version>0.6</version>
@ -64,7 +64,7 @@
<version>0.5</version> <version>0.5</version>
<date>2006-05-03</date> <date>2006-05-03</date>
<initials>psa/jp/jk</initials> <initials>psa/jp/jk</initials>
<remark><p>Integrated text from server-side archiving proposal; added partial support to collection retrieval; harmonized XML formats and namespaces; defined Jabber Registrar considerations and XML schema.</p></remark> <remark><p>Integrated text from server-side archiving proposal; added partial support to collection retrieval; harmonized XML formats and namespaces; defined XMPP Registrar considerations and XML schema.</p></remark>
</revision> </revision>
<revision> <revision>
<version>0.4</version> <version>0.4</version>
@ -102,7 +102,7 @@
<p>Complying with <strong>XMPP Core</strong>, the server MUST respond to all &IQ; element of type 'get' or 'set'. However, most successful responses have been omitted from this document in the interest of conciseness.</p> <p>Complying with <strong>XMPP Core</strong>, the server MUST respond to all &IQ; element of type 'get' or 'set'. However, most successful responses have been omitted from this document in the interest of conciseness.</p>
</section1> </section1>
<section1 topic='Determining Server Support' anchor='disco'> <section1 topic='Determining Server Support' anchor='disco'>
<p>A client discovers whether its server supports this protocol using &jep0030;.</p> <p>A client discovers whether its server supports this protocol using &xep0030;.</p>
<example caption='Client Service Discovery request'> <example caption='Client Service Discovery request'>
<![CDATA[ <![CDATA[
<iq type='get' to='montague.net'> <iq type='get' to='montague.net'>
@ -275,7 +275,7 @@
</section2> </section2>
</section1> </section1>
<section1 topic='Off The Record' anchor='otr'> <section1 topic='Off The Record' anchor='otr'>
<p>A user will sometimes exchange messages with contacts who prefer that their conversations are not archived by either party. Any client that archives messages SHOULD support &jep0155; and its 'otr' field both to give other contacts the opportunity to indicate this preference, and to negotiate an "Off The Record" (OTR) policy that complies with its user's own <link url='#pref'>Archiving Preferences</link>.</p> <p>A user will sometimes exchange messages with contacts who prefer that their conversations are not archived by either party. Any client that archives messages SHOULD support &xep0155; and its 'otr' field both to give other contacts the opportunity to indicate this preference, and to negotiate an "Off The Record" (OTR) policy that complies with its user's own <link url='#pref'>Archiving Preferences</link>.</p>
<p>A client MUST NOT agree to enable OTR unless it has confirmed that its server will allow it to switch off <link url='#auto'>Automated Archiving</link>.</p> <p>A client MUST NOT agree to enable OTR unless it has confirmed that its server will allow it to switch off <link url='#auto'>Automated Archiving</link>.</p>
<p>If a Chat Session Negotiation agreed to enable OTR then the clients MUST NOT allow messages sent in <em>either</em> direction to be archived in any way (including <link url='#manual'>Manual Archiving</link> and <link url='#auto'>Automated Archiving</link>). <note>If a client (or user) acts in bad faith then its contacts cannot prevent it archiving conversations.</note></p> <p>If a Chat Session Negotiation agreed to enable OTR then the clients MUST NOT allow messages sent in <em>either</em> direction to be archived in any way (including <link url='#manual'>Manual Archiving</link> and <link url='#auto'>Automated Archiving</link>). <note>If a client (or user) acts in bad faith then its contacts cannot prevent it archiving conversations.</note></p>
<p>Note: If a contact does not include an 'otr' field in its initial Chat Session Negotiation request, and a user's Archiving Preferences indicate that OTR is <em>required</em>, then the client MUST refuse the request. It MAY then send its own Chat Session Negotiation request with an 'otr' field.</p> <p>Note: If a contact does not include an 'otr' field in its initial Chat Session Negotiation request, and a user's Archiving Preferences indicate that OTR is <em>required</em>, then the client MUST refuse the request. It MAY then send its own Chat Session Negotiation request with an 'otr' field.</p>
@ -286,7 +286,7 @@
<section2 topic='Introduction' anchor='manual-intro'> <section2 topic='Introduction' anchor='manual-intro'>
<p>While automated archiving is easy for the client and server to implement, there are many contexts in which manual archiving is required. For examples, when:</p> <p>While automated archiving is easy for the client and server to implement, there are many contexts in which manual archiving is required. For examples, when:</p>
<ul> <ul>
<li>Messages are encrypted using evanscent keys, as in &jep0116;</li> <li>Messages are encrypted using evanscent keys, as in &xep0116;</li>
<li>A client's own server does not support automated archiving but it (or another server) does support manual archiving</li> <li>A client's own server does not support automated archiving but it (or another server) does support manual archiving</li>
<li>A server does not support encryption of auto-archived collections</li> <li>A server does not support encryption of auto-archived collections</li>
<li>A client wants to maintain a unified archive for messages that were transmitted both in and out-of-band (e.g. SMS or email)</li> <li>A client wants to maintain a unified archive for messages that were transmitted both in and out-of-band (e.g. SMS or email)</li>
@ -299,7 +299,7 @@
<p>The client uniquely specifies a collection using a pair of attributes:</p> <p>The client uniquely specifies a collection using a pair of attributes:</p>
<ul> <ul>
<li>'with' (the full JID with which the messages were exchanged)</li> <li>'with' (the full JID with which the messages were exchanged)</li>
<li>'start' (the UTC start time of the conversation thread, which MUST be UTC and adhere to the DateTime format specified in &jep0082;)</li> <li>'start' (the UTC start time of the conversation thread, which MUST be UTC and adhere to the DateTime format specified in &xep0082;)</li>
</ul> </ul>
<p>A friendly name for the collection MAY be specified with a 'subject' attribute. Note the <link url='#security-subject'>Security Considerations</link> regarding the subject attribute.</p> <p>A friendly name for the collection MAY be specified with a 'subject' attribute. Note the <link url='#security-subject'>Security Considerations</link> regarding the subject attribute.</p>
<p>Each collection MAY contain &lt;note/&gt;, &lt;to/&gt; or &lt;from/&gt; elements (or &lt;EncryptedData/&gt; and &lt;EncryptedKey/&gt; elements - see <link url='#crypt'>Encryption</link>).</p> <p>Each collection MAY contain &lt;note/&gt;, &lt;to/&gt; or &lt;from/&gt; elements (or &lt;EncryptedData/&gt; and &lt;EncryptedKey/&gt; elements - see <link url='#crypt'>Encryption</link>).</p>
@ -352,7 +352,7 @@
]]></example> ]]></example>
</section2> </section2>
<section2 topic='Groupchat Messages' anchor='impl-muc'> <section2 topic='Groupchat Messages' anchor='impl-muc'>
<p>A client MAY archive messages that it receives from &jep0045; rooms. The 'with' attribute MUST be the bare JID of the room. The client MUST include a 'name' attribute for each &lt;from/&gt; element to specify the room nickname of the message sender:</p> <p>A client MAY archive messages that it receives from &xep0045; rooms. The 'with' attribute MUST be the bare JID of the room. The client MUST include a 'name' attribute for each &lt;from/&gt; element to specify the room nickname of the message sender:</p>
<example caption='Storing groupchat messages in a collection'><![CDATA[ <example caption='Storing groupchat messages in a collection'><![CDATA[
<iq type='set' to='montague.net' id='up3'> <iq type='set' to='montague.net' id='up3'>
<store xmlns='http://jabber.org/protocol/archive' <store xmlns='http://jabber.org/protocol/archive'
@ -380,7 +380,7 @@
<section1 topic='Encryption' anchor='crypt'> <section1 topic='Encryption' anchor='crypt'>
<p>The examples above are not encrypted for clarity. However, clients SHOULD encrypt manually-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later versions). Servers MUST support the manual-archiving of encrypted collections.</p> <p>The examples above are not encrypted for clarity. However, clients SHOULD encrypt manually-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later versions). Servers MUST support the manual-archiving of encrypted collections.</p>
<p>Before uploading a sequence of messages to a collection, the client SHOULD select a symmetric data encryption algorithm, generate a suitable random encryption key, give the key a unique (for the user) name, encrypt the symmetric key with one of the user's public keys, and wrap the result inside one or more &lt;EncryptedKey/&gt; elements, as specified in &w3xmlenc;.</p> <p>Before uploading a sequence of messages to a collection, the client SHOULD select a symmetric data encryption algorithm, generate a suitable random encryption key, give the key a unique (for the user) name, encrypt the symmetric key with one of the user's public keys, and wrap the result inside one or more &lt;EncryptedKey/&gt; elements, as specified in &w3xmlenc;.</p>
<p>To ensure that all its user's clients will be able to decrypt the collection, the client SHOULD create one &lt;EncryptedKey/&gt; element for each of its user's public keys that are being published using &jep0189;. However, the client MUST NOT create an &lt;EncryptedKey/&gt; element for any public key until it has confirmed that it belongs to the user. Note: The fact that a public key is being published using <cite>Public Key Publishing</cite> is <em>not</em> sufficient proof of ownership, since the user's server may have been compromised at some stage. The method of confirmation is beyond the scope of this document.</p> <p>To ensure that all its user's clients will be able to decrypt the collection, the client SHOULD create one &lt;EncryptedKey/&gt; element for each of its user's public keys that are being published using &xep0189;. However, the client MUST NOT create an &lt;EncryptedKey/&gt; element for any public key until it has confirmed that it belongs to the user. Note: The fact that a public key is being published using <cite>Public Key Publishing</cite> is <em>not</em> sufficient proof of ownership, since the user's server may have been compromised at some stage. The method of confirmation is beyond the scope of this document.</p>
<p>The client SHOULD use the symmetric key to encrypt the joined sequence of &lt;to/&gt;, &lt;from/&gt; and &lt;note/&gt; elements, base64 encode the resulting sequence of bytes, and wrap it inside an &lt;EncryptedData/&gt; element, as described in <cite>XML Encryption</cite>.</p> <p>The client SHOULD use the symmetric key to encrypt the joined sequence of &lt;to/&gt;, &lt;from/&gt; and &lt;note/&gt; elements, base64 encode the resulting sequence of bytes, and wrap it inside an &lt;EncryptedData/&gt; element, as described in <cite>XML Encryption</cite>.</p>
<p>Clients may add one or more &lt;EncryptedData/&gt; or &lt;EncryptedKey/&gt; elements to a collection using exactly the same method as for &lt;to/&gt;, &lt;from/&gt; and &lt;note/&gt; elements (see <link url='#manual-upload'>Uploading Messages to a Collection</link>). One collection may contain &lt;EncryptedData/&gt; elements encrypted with different symmetric keys.</p> <p>Clients may add one or more &lt;EncryptedData/&gt; or &lt;EncryptedKey/&gt; elements to a collection using exactly the same method as for &lt;to/&gt;, &lt;from/&gt; and &lt;note/&gt; elements (see <link url='#manual-upload'>Uploading Messages to a Collection</link>). One collection may contain &lt;EncryptedData/&gt; elements encrypted with different symmetric keys.</p>
<p>When appending &lt;EncryptedData/&gt; elements to a collection, the client MAY reuse a symmetric KEY that has already been uploaded to the collection. In this case the client SHOULD NOT resend &lt;EncryptedKey/&gt; elements.</p> <p>When appending &lt;EncryptedData/&gt; elements to a collection, the client MAY reuse a symmetric KEY that has already been uploaded to the collection. In this case the client SHOULD NOT resend &lt;EncryptedKey/&gt; elements.</p>
@ -424,7 +424,7 @@
<section1 topic='Automated Archiving' anchor='auto'> <section1 topic='Automated Archiving' anchor='auto'>
<section2 topic='Toggling Auto-Archiving' anchor='auto-toggle'> <section2 topic='Toggling Auto-Archiving' anchor='auto-toggle'>
<p>A client MAY enable or disable automatic archiving for messages sent over its stream. Automatic archiving MUST default to disabled for each new stream that is opened, unless administrator policies <em>require</em> that every message is logged automatically (see <link url='#security'>Security Considerations</link>). Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's general <link url='#pref'>Archiving Preferences</link>.</p> <p>A client MAY enable or disable automatic archiving for messages sent over its stream. Automatic archiving MUST default to disabled for each new stream that is opened, unless administrator policies <em>require</em> that every message is logged automatically (see <link url='#security'>Security Considerations</link>). Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's general <link url='#pref'>Archiving Preferences</link>.</p>
<p>Note: Both parties to an ESession (see &jep0116;) MUST either disable archiving or use an archiving method other than automatic, since ESession decryption keys are short-lived - making it impossible to decrypt automatically archived messages.</p> <p>Note: Both parties to an ESession (see &xep0116;) MUST either disable archiving or use an archiving method other than automatic, since ESession decryption keys are short-lived - making it impossible to decrypt automatically archived messages.</p>
<example caption='Client enables auto archiving'><![CDATA[ <example caption='Client enables auto archiving'><![CDATA[
<iq type='set' id='auto1'> <iq type='set' id='auto1'>
<auto save='true' xmlns='http://jabber.org/protocol/archive'/> <auto save='true' xmlns='http://jabber.org/protocol/archive'/>
@ -474,7 +474,7 @@
<li>Retrieving a collection</li> <li>Retrieving a collection</li>
<li>Removing a collection</li> <li>Removing a collection</li>
</ol> </ol>
<p>Requirements and protocol flows for each of these use cases are defined below. The protocols to retrieve a list of collections and an indivdual collection both make extensive use of &jep0059;. Clients and servers SHOULD support all the features defined in that protocol.</p> <p>Requirements and protocol flows for each of these use cases are defined below. The protocols to retrieve a list of collections and an indivdual collection both make extensive use of &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.</p>
<section2 topic='Retrieving a List of Collections' anchor='manage-list'> <section2 topic='Retrieving a List of Collections' anchor='manage-list'>
<p>To request a list of collections the client sends a &lt;list/&gt; element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>Jabber Date and Time Profiles</cite>). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.</p> <p>To request a list of collections the client sends a &lt;list/&gt; element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>Jabber Date and Time Profiles</cite>). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.</p>
<p>If the 'with' attribute is omitted then collections with any JID are returned. If only 'start' is specified then all collections on or after that date should be returned. If only 'end' is specified then all collections prior to that date should be returned.</p> <p>If the 'with' attribute is omitted then collections with any JID are returned. If only 'start' is specified then all collections on or after that date should be returned. If only 'end' is specified then all collections prior to that date should be returned.</p>
@ -901,7 +901,7 @@
<p>After receiving each result set page the client SHOULD delete from its local archive any collections that have been removed from the master archive. The client should also retrieve from the server the content of each collection that has been modified (see <link url='#retrieve'>Retrieving a Collection</link>) and add it to its local copy of the archive (deleting any older version of the same collection that it may already have).</p> <p>After receiving each result set page the client SHOULD delete from its local archive any collections that have been removed from the master archive. The client should also retrieve from the server the content of each collection that has been modified (see <link url='#retrieve'>Retrieving a Collection</link>) and add it to its local copy of the archive (deleting any older version of the same collection that it may already have).</p>
</section1> </section1>
<section1 topic='File Format' anchor='fileformat'> <section1 topic='File Format' anchor='fileformat'>
<p><em>Note the file format specified in this section is likely to be deprecated once a standards-based format has been published in a separate JEP.</em></p> <p><em>Note the file format specified in this section is likely to be deprecated once a standards-based format has been published in a separate specification.</em></p>
<p>So that clients can share archived messages, this document specifies a common format for storage on disk (similar to email formats like mbox and Maildir). The file format uses the same XML constructs as the protocol. Each file may contain messages exchanged with a single JID. Any number of items may be stored in an archive file.</p> <p>So that clients can share archived messages, this document specifies a common format for storage on disk (similar to email formats like mbox and Maildir). The file format uses the same XML constructs as the protocol. Each file may contain messages exchanged with a single JID. Any number of items may be stored in an archive file.</p>
<example caption='Example file'><![CDATA[ <example caption='Example file'><![CDATA[
<?xml version='1.0'?> <?xml version='1.0'?>
@ -917,7 +917,7 @@
</section1> </section1>
<section1 topic='Implementation Notes' anchor='impl'> <section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Time Synchronization' anchor='impl-sync'> <section2 topic='Time Synchronization' anchor='impl-sync'>
<p>When creating a new collection, it is RECOMMENDED that the client synchronizes the collection start time that it sends to the server with server time. This is important since the user may subsequently retrieve the stored collection using client machines whose UTC clocks are not synchronized with the client machine that stored the collection. (i.e. Either or both of the clients' UTC clocks may be wrong.) The client can achieve this synchronization with server time by using &jep0090; to estimate the difference between the server and client UTC clocks.</p> <p>When creating a new collection, it is RECOMMENDED that the client synchronizes the collection start time that it sends to the server with server time. This is important since the user may subsequently retrieve the stored collection using client machines whose UTC clocks are not synchronized with the client machine that stored the collection. (i.e. Either or both of the clients' UTC clocks may be wrong.) The client can achieve this synchronization with server time by using &xep0090; to estimate the difference between the server and client UTC clocks.</p>
<p>When retrieving collections, it is RECOMMENDED that the client adjusts the start times of the collections it receives from server to be synchronized with the clock of the client machine.</p> <p>When retrieving collections, it is RECOMMENDED that the client adjusts the start times of the collections it receives from server to be synchronized with the clock of the client machine.</p>
</section2> </section2>
<section2 topic='Bandwidth Considerations' anchor='impl-bandwidth'> <section2 topic='Bandwidth Considerations' anchor='impl-bandwidth'>
@ -929,26 +929,26 @@
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<section2 topic='Automatic Archiving Defaulting to On' anchor='security-autoon'> <section2 topic='Automatic Archiving Defaulting to On' anchor='security-autoon'>
<p>If automatic archiving defaults to enabled then that creates serious privacy issues for users of legacy clients that do not support this protocol, and (more seriously) for those contacts who they unwittingly mislead by agreeing to disable logging (via the 'otr' field defined in JEP-0155).</p> <p>If automatic archiving defaults to enabled then that creates serious privacy issues for users of legacy clients that do not support this protocol, and (more seriously) for those contacts who they unwittingly mislead by agreeing to disable logging (via the 'otr' field defined in XEP-0155).</p>
</section2> </section2>
<section2 topic='Plain Text Subject' anchor='security-encrypt'> <section2 topic='Plain Text Subject' anchor='security-encrypt'>
<p>Since the subject of each collection will not be encrypted, the client MUST warn its human user (if any) before including 'subject' attributes on encrypted collections.</p> <p>Since the subject of each collection will not be encrypted, the client MUST warn its human user (if any) before including 'subject' attributes on encrypted collections.</p>
</section2> </section2>
<section2 topic='Store Headers' anchor='security-store'> <section2 topic='Store Headers' anchor='security-store'>
<p>The client that originates a message MAY specify a 'false' value for the 'store' header (see &jep0131;). The recipient MUST NOT archive such a message or any of the information it contains.</p> <p>The client that originates a message MAY specify a 'false' value for the 'store' header (see &xep0131;). The recipient MUST NOT archive such a message or any of the information it contains.</p>
<p>If the sender plans to use 'store' headers it MUST use Service Discovery to determine whether or not the recipient supports them. Note: Since servers are not required to check the content of message stanzas for headers, if the recipient is using automatic archiving then it MUST indicate that it does not support 'store' headers.</p> <p>If the sender plans to use 'store' headers it MUST use Service Discovery to determine whether or not the recipient supports them. Note: Since servers are not required to check the content of message stanzas for headers, if the recipient is using automatic archiving then it MUST indicate that it does not support 'store' headers.</p>
<p>If the recipient does not support 'store' headers, then the sender MUST confirm with its human user (if any) before sending such a message.</p> <p>If the recipient does not support 'store' headers, then the sender MUST confirm with its human user (if any) before sending such a message.</p>
</section2> </section2>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>No interaction with &IANA; is required as a result of this JEP.</p> <p>No interaction with &IANA; is required as a result of this document.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/archive' in its registry of protocol namespaces (see &NAMESPACES;):</p> <p>The &REGISTRAR; shall include 'http://jabber.org/protocol/archive' in its registry of protocol namespaces (see &NAMESPACES;):</p>
</section2> </section2>
<section2 topic='Service Discovery Features' anchor='registrar-features'> <section2 topic='Service Discovery Features' anchor='registrar-features'>
<p>The Jabber Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;):</p> <p>The XMPP Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;):</p>
<ul> <ul>
<li>http://jabber.org/protocol/archive#auto</li> <li>http://jabber.org/protocol/archive#auto</li>
<li>http://jabber.org/protocol/archive#encrypt</li> <li>http://jabber.org/protocol/archive#encrypt</li>
@ -1223,4 +1223,4 @@
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,10 +1,10 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Publishing Stream Initiation Requests</title> <title>Publishing Stream Initiation Requests</title>
<abstract>This documents defines an XMPP protocol extension for publishing the availability of a particular Stream Initiation request, such as a file.</abstract> <abstract>This documents defines an XMPP protocol extension for publishing the availability of a particular Stream Initiation request, such as a file.</abstract>
@ -15,14 +15,14 @@
<jig>Standards JIG</jig> <jig>Standards JIG</jig>
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>JEP-0030</spec> <spec>XEP-0030</spec>
<spec>JEP-0095</spec> <spec>XEP-0095</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>sipub</shortname> <shortname>sipub</shortname>
<schemaloc> <schemaloc>
<url>http://jabber.org/protocol/sipub/sipub.xsd</url> <url>http://www.xmpp.org/schemas/sipub.xsd</url>
</schemaloc> </schemaloc>
&linuxwolf; &linuxwolf;
&temas; &temas;
@ -52,19 +52,19 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>&jep0095; defines a protocol to initiate a data stream between two Jabber/XMPP entities (e.g., for the purpose of &jep0096;). However, the sender is still responsible for informing potential receivers about the existence of a given stream. This JEP provides an automated way for a sender to announce the availability of a stream without initiating the data transfer. The purpose is to provide a "pull" protocol that enables a receiver to then request initiation of the stream from the sender.</p> <p>&xep0095; defines a protocol to initiate a data stream between two Jabber/XMPP entities (e.g., for the purpose of &xep0096;). However, the sender is still responsible for informing potential receivers about the existence of a given stream. This JEP provides an automated way for a sender to announce the availability of a stream without initiating the data transfer. The purpose is to provide a "pull" protocol that enables a receiver to then request initiation of the stream from the sender.</p>
</section1> </section1>
<section1 topic='Requirements' anchor='requirements'> <section1 topic='Requirements' anchor='requirements'>
<p>This proposal addresses the following requirements:</p> <p>This proposal addresses the following requirements:</p>
<ul> <ul>
<li>Allow a potential receiver (rather than the sender) to initiate a data stream.</li> <li>Allow a potential receiver (rather than the sender) to initiate a data stream.</li>
<li>Integrate Stream Initiation (SI) with &jep0060;.</li> <li>Integrate Stream Initiation (SI) with &xep0060;.</li>
<li>Integrate Stream Initiation with &jep0004;.</li> <li>Integrate Stream Initiation with &xep0004;.</li>
</ul> </ul>
</section1> </section1>
<section1 topic='Use Cases' anchor='usecase'> <section1 topic='Use Cases' anchor='usecase'>
<section2 topic='Publishing an SI Request' anchor='usecase.publish'> <section2 topic='Publishing an SI Request' anchor='usecase.publish'>
<p>A stream owner uses the &lt;sipub/&gt; element to announce that it can perform a specific SI request. This element can be sent to a publish-subscribe (JEP-0060) node, or sent directly to potential recipients within a &MESSAGE; stanza.</p> <p>A stream owner uses the &lt;sipub/&gt; element to announce that it can perform a specific SI request. This element can be sent to a publish-subscribe (XEP-0060) node, or sent directly to potential recipients within a &MESSAGE; stanza.</p>
<p>The format of the &lt;sipub/&gt; element is as follows:</p> <p>The format of the &lt;sipub/&gt; element is as follows:</p>
<example caption='Sample &lt;sipub/&gt;'><![CDATA[ <example caption='Sample &lt;sipub/&gt;'><![CDATA[
<sipub xmlns='http://jabber.org/protocol/sipub' <sipub xmlns='http://jabber.org/protocol/sipub'
@ -75,7 +75,7 @@
<profile xmlns='si-profile' ...>...</profile> <profile xmlns='si-profile' ...>...</profile>
</sipub> </sipub>
]]></example> ]]></example>
<p>This format is nearly identical to that for the stream initiation &lt;si/&gt; element (see <cite>JEP-0095</cite>). The major difference is the lack of the feature negotiation for the stream methods, and the addition of a 'from' attribute.</p> <p>This format is nearly identical to that for the stream initiation &lt;si/&gt; element (see <cite>XEP-0095</cite>). The major difference is the lack of the feature negotiation for the stream methods, and the addition of a 'from' attribute.</p>
<p>The 'from' attribute SHOULD be present, and MUST be present if the stanza containing the &lt;sipub/&gt; is not from the stream owner (e.g., if the stream is advertised at a publish-subscribe node). If present, this attribute MUST be the valid JID for the stream owner.</p> <p>The 'from' attribute SHOULD be present, and MUST be present if the stanza containing the &lt;sipub/&gt; is not from the stream owner (e.g., if the stream is advertised at a publish-subscribe node). If present, this attribute MUST be the valid JID for the stream owner.</p>
<p>The 'id' attribute is an opaque identifier. This attribute MUST be present, and MUST be a valid non-empty string. It uniquely identifies the published request at the potential sender.</p> <p>The 'id' attribute is an opaque identifier. This attribute MUST be present, and MUST be a valid non-empty string. It uniquely identifies the published request at the potential sender.</p>
<p>As with stream initiation, the 'profile' attribute MUST be present, and MUST be the namespace URI governing the profile information. It identifies the format for the SI profile.</p> <p>As with stream initiation, the 'profile' attribute MUST be present, and MUST be the namespace URI governing the profile information. It identifies the format for the SI profile.</p>
@ -126,7 +126,7 @@
</event> </event>
</message> </message>
]]></example> ]]></example>
<p>The &lt;sipub/&gt; element MAY also be included directly within a &MESSAGE; stanza sent to another entity (or multiple entities, e.g., in &jep0045; or via &jep0033;). This can be especially useful for informing an offline entity about an available stream.</p> <p>The &lt;sipub/&gt; element MAY also be included directly within a &MESSAGE; stanza sent to another entity (or multiple entities, e.g., in &xep0045; or via &xep0033;). This can be especially useful for informing an offline entity about an available stream.</p>
<example caption='Advertising a stream in a message stanza'><![CDATA[ <example caption='Advertising a stream in a message stanza'><![CDATA[
<message from='romeo@montague.net/pda' to='juliet@capulet.com'> <message from='romeo@montague.net/pda' to='juliet@capulet.com'>
<sipub xmlns='http://jabber.org/protocol/si-pub' <sipub xmlns='http://jabber.org/protocol/si-pub'
@ -144,8 +144,8 @@
]]></example> ]]></example>
</section2> </section2>
<section2 topic='Integration with Data Forms' anchor='usecase.xdata'> <section2 topic='Integration with Data Forms' anchor='usecase.xdata'>
<p>One of the goals of sipub is to integrate <cite>Stream Initiation</cite> with <cite>Data Forms</cite> to provide a "file upload" capability. This is accomplished via the datatypes specified in &jep0122;. Each datatype is specific to the profile desired.</p> <p>One of the goals of sipub is to integrate <cite>Stream Initiation</cite> with <cite>Data Forms</cite> to provide a "file upload" capability. This is accomplished via the datatypes specified in &xep0122;. Each datatype is specific to the profile desired.</p>
<p>For example the datatype "sipub:file-transfer" is used to identify the file upload field(s) corresponding to <cite>JEP-0096</cite>:</p> <p>For example the datatype "sipub:file-transfer" is used to identify the file upload field(s) corresponding to <cite>XEP-0096</cite>:</p>
<example caption='"Upload File" Data Forms Field'><![CDATA[ <example caption='"Upload File" Data Forms Field'><![CDATA[
<field var='file' type='text-single' label='File to Upload'> <field var='file' type='text-single' label='File to Upload'>
<validate xmlns='http://jabber.org/protocol/xdata-validate' <validate xmlns='http://jabber.org/protocol/xdata-validate'
@ -243,23 +243,23 @@
</section2> </section2>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>This JEP introduces no security concerns beyond those specified in <cite>JEP-0060</cite> and the relevant Stream Initiation profile in use.</p> <p>This JEP introduces no security concerns beyond those specified in <cite>XEP-0060</cite> and the relevant Stream Initiation profile in use.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p> <p>This JEP requires no interaction with &IANA;.</p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar.namespaces'> <section2 topic='Protocol Namespaces' anchor='registrar.namespaces'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/sipub' in its registry of protocol namespaces.</p> <p>The &REGISTRAR; includes 'http://jabber.org/protocol/sipub' in its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Data Form Validation Datatypes' anchor='registrar.xdata-validate'> <section2 topic='Data Form Validation Datatypes' anchor='registrar.xdata-validate'>
<p>The Jabber Registrar includes 'sipub:' in its registry of Data Forms Validation Datatype Prefixes.</p> <p>The XMPP Registrar includes 'sipub:' in its registry of Data Forms Validation Datatype Prefixes.</p>
<p>Normally, each SI profile that wishes to be considered for use with Data Forms MUST register its own datatype qualified by the "sipub:" prefix. However, this JEP provides an initial seed, based on the currently accepted SI profiles. The following datatypes shall be registered for use with Data Forms Validation:</p> <p>Normally, each SI profile that wishes to be considered for use with Data Forms MUST register its own datatype qualified by the "sipub:" prefix. However, this JEP provides an initial seed, based on the currently accepted SI profiles. The following datatypes shall be registered for use with Data Forms Validation:</p>
<code caption='Data Forms Validation Datatypes Registry Submission'><![CDATA[ <code caption='Data Forms Validation Datatypes Registry Submission'><![CDATA[
<datatype> <datatype>
<name>sipub:file-transfer</name> <name>sipub:file-transfer</name>
<desc>Datatype for publishing an SI using the File Transfer Profile</desc> <desc>Datatype for publishing an SI using the File Transfer Profile</desc>
<doc>JEP-0096</doc> <doc>XEP-0096</doc>
</datatype> </datatype>
]]></code> ]]></code>
</section2> </section2>
@ -277,7 +277,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0137: http://www.jabber.org/jeps/jep-0137.html XEP-0137: http://www.jabber.org/xeps/xep-0137.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -317,4 +317,4 @@
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Stream Compression</title> <title>Stream Compression</title>
<abstract>This document defines an XMPP extension for negotiating compression of XML streams.</abstract> <abstract>This document defines an XMPP protocol extension for negotiating compression of XML streams.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0138</number> <number>0138</number>
<status>Draft</status> <status>Draft</status>
@ -20,12 +20,12 @@
<supersededby/> <supersededby/>
<shortname>compress</shortname> <shortname>compress</shortname>
<schemaloc> <schemaloc>
<ns>feature</ns> <ns>compress</ns>
<url>http://jabber.org/protocol/compress/feature.xsd</url> <url>http://www.xmpp.org/schemas/compress.xsd</url>
</schemaloc> </schemaloc>
<schemaloc> <schemaloc>
<ns>compress</ns> <ns>feature</ns>
<url>http://jabber.org/protocol/compress/compress.xsd</url> <url>http://www.xmpp.org/schemas/compress-feature.xsd</url>
</schemaloc> </schemaloc>
<registry/> <registry/>
&hildjj; &hildjj;
@ -81,7 +81,7 @@
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>&xmppcore; specifies the use of Transport Layer Security (TLS; see &rfc2246;) for encryption of XML streams, and TLS includes the ability to compress encrypted traffic (see &rfc3749;). However, not all computing platforms are able to implement TLS, and traffic compression may be desirable for communication by applications on such computing platforms. This JEP defines a mechanism for negotiating the compression of XML streams outside the context of TLS.</p> <p>&xmppcore; specifies the use of Transport Layer Security (TLS; see &rfc2246;) for encryption of XML streams, and TLS includes the ability to compress encrypted traffic (see &rfc3749;). However, not all computing platforms are able to implement TLS, and traffic compression may be desirable for communication by applications on such computing platforms. This document defines a mechanism for negotiating the compression of XML streams outside the context of TLS.</p>
</section1> </section1>
<section1 topic='Use Case' anchor='usecase'> <section1 topic='Use Case' anchor='usecase'>
@ -141,7 +141,7 @@
<!-- <!--
<section1 topic='Feature Negotiation (Optional)' anchor='negotiation'> <section1 topic='Feature Negotiation (Optional)' anchor='negotiation'>
<p>The initiating entity and receiving entity MAY support &jep0020; for more fine-grained negotiation of parameters (such as compression levels). Such support is OPTIONAL, and the initiating entity should expect that the receiving entity may not support feature negotiation. Because use of &jep0030; to discover negotiable features is inconvenient during stream negotiation, the initiating entity SHOULD negotiate only features that are registered for use with the 'http://jabber.org/protocol/compress' FORM_TYPE as described in the <link url="#registrar-formtype">Field Standardization</link> section of this document.</p> <p>The initiating entity and receiving entity MAY support &xep0020; for more fine-grained negotiation of parameters (such as compression levels). Such support is OPTIONAL, and the initiating entity should expect that the receiving entity may not support feature negotiation. Because use of &xep0030; to discover negotiable features is inconvenient during stream negotiation, the initiating entity SHOULD negotiate only features that are registered for use with the 'http://jabber.org/protocol/compress' FORM_TYPE as described in the <link url="#registrar-formtype">Field Standardization</link> section of this document.</p>
<p>The initiating entity MAY include a feature negotiation child within the initial &lt;compress/&gt; element requesting stream compression:</p> <p>The initiating entity MAY include a feature negotiation child within the initial &lt;compress/&gt; element requesting stream compression:</p>
<example caption='Initiating Entity Requests Stream Compression (With Feature Negotiation)'><![CDATA[ <example caption='Initiating Entity Requests Stream Compression (With Feature Negotiation)'><![CDATA[
<compress xmlns='http://jabber.org/protocol/compress'> <compress xmlns='http://jabber.org/protocol/compress'>
@ -185,12 +185,12 @@
<li>If stream compression is negotiated, it MUST be used in both directions.</li> <li>If stream compression is negotiated, it MUST be used in both directions.</li>
<li>TLS compression and stream compression SHOULD NOT be used simultaneously.</li> <li>TLS compression and stream compression SHOULD NOT be used simultaneously.</li>
<li>If both TLS (whether including TLS compression or not) and stream compression are used, then TLS MUST be negotiated first, followed by negotiation of stream compression.</li> <li>If both TLS (whether including TLS compression or not) and stream compression are used, then TLS MUST be negotiated first, followed by negotiation of stream compression.</li>
<li>Negotiation of stream compression SHOULD be completed before authentication via SASL (see <cite>RFC 3920</cite>) or &jep0078;.</li> <li>Negotiation of stream compression SHOULD be completed before authentication via SASL (see <cite>RFC 3920</cite>) or &xep0078;.</li>
</ul> </ul>
</section1> </section1>
<section1 topic='Mandatory-to-Implement Technologies' anchor='mandatory'> <section1 topic='Mandatory-to-Implement Technologies' anchor='mandatory'>
<p>A compliant implementation MUST implement the ZLIB compression method as specified in &rfc1950;. All other methods are OPTIONAL; such methods may be defined in future JEPs or by registration as described in the <link url='#registrar-methods'>Compression Methods Registry</link> section of this document.</p> <p>A compliant implementation MUST implement the ZLIB compression method as specified in &rfc1950;. All other methods are OPTIONAL; such methods may be defined in future specifications or by registration as described in the <link url='#registrar-methods'>Compression Methods Registry</link> section of this document.</p>
</section1> </section1>
<section1 topic='Implementation Notes' anchor='impl'> <section1 topic='Implementation Notes' anchor='impl'>
@ -207,18 +207,18 @@
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;. </p> <p>This document requires no interaction with &IANA;. </p>
</section1> </section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Stream Features' anchor='registrar-stream'> <section2 topic='Stream Features' anchor='registrar-stream'>
<p>The &REGISTRAR; includes 'http://jabber.org/features/compress' in its registry of stream features.</p> <p>The &REGISTRAR; includes 'http://jabber.org/features/compress' in its registry of stream features.</p>
</section2> </section2>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The Jabber Registrar includes 'http://jabber.org/protocol/compress' in its registry of protocol namespaces.</p> <p>The XMPP Registrar includes 'http://jabber.org/protocol/compress' in its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Compression Methods Registry' anchor='registrar-methods'> <section2 topic='Compression Methods Registry' anchor='registrar-methods'>
<p>The Jabber Registrar maintains a registry of compression methods at &lt;<link url='http://www.jabber.org/registrar/compress.html'>http://www.jabber.org/registrar/compress.html</link>&gt;.</p> <p>The XMPP Registrar maintains a registry of compression methods at &lt;<link url='http://www.jabber.org/registrar/compress.html'>http://www.jabber.org/registrar/compress.html</link>&gt;.</p>
<section3 topic='Process' anchor='registrar-methods-process'> <section3 topic='Process' anchor='registrar-methods-process'>
&REGPROCESS; &REGPROCESS;
<code><![CDATA[ <code><![CDATA[
@ -247,7 +247,7 @@
</section2> </section2>
<!-- <!--
<section2 topic='Field Standardization' anchor='registrar-formtype'> <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. Reserved fields shall be registered with the Jabber Registrar as necessary.</p> <p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. Reserved fields shall be registered with the XMPP Registrar as necessary.</p>
</section2> </section2>
--> -->
</section1> </section1>
@ -266,7 +266,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0138: http://www.jabber.org/jeps/jep-0138.html XEP-0138: http://www.xmpp.org/extensions/xep-0138.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -296,7 +296,7 @@
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The protocol documented by this schema is defined in The protocol documented by this schema is defined in
JEP-0138: http://www.jabber.org/jeps/jep-0138.html XEP-0138: http://www.xmpp.org/extensions/xep-0138.html
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
@ -335,4 +335,4 @@
</section2> </section2>
</section1> </section1>
</jep> </xep>

View File

@ -1,13 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [ <!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent"> <!ENTITY % ents SYSTEM "xep.ent">
%ents; %ents;
]> ]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<jep> <xep>
<header> <header>
<title>Security JIG</title> <title>Security JIG</title>
<abstract>This JEP proposes the formation of a Jabber Interest Group devoted to the analysis of security threats related to Jabber technologies.</abstract> <abstract>This document proposes the formation of a Jabber Interest Group devoted to the analysis of security threats related to Jabber technologies.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0139</number> <number>0139</number>
<status>Retracted</status> <status>Retracted</status>
@ -28,7 +28,7 @@
<version>0.2</version> <version>0.2</version>
<date>2004-09-15</date> <date>2004-09-15</date>
<initials>psa</initials> <initials>psa</initials>
<remark>Changed status to Retracted since it now appears unnecessary to form a JIG in order to complete this work; rather, it should be sufficient to write a JEP and solicit feedback from appropriate security experts before the Last Call. However, such a JEP should use the process described herein.</remark> <remark>Changed status to Retracted since it now appears unnecessary to form a JIG in order to complete this work; rather, it should be sufficient to write a XEP and solicit feedback from appropriate security experts before the Last Call. However, such a XEP should use the process described herein.</remark>
</revision> </revision>
<revision> <revision>
<version>0.1</version> <version>0.1</version>
@ -44,7 +44,7 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>Because security is a core value within the Jabber community, it is appropriate for the Jabber Software Foundation to assess potential security threats related to technologies that implement the Jabber protocols (including XMPP and defined XMPP extensions), as well as ways to address the threats (for general information about the Internet threat model, see &rfc3552;). Furthermore, since security threats are wide-ranging and of broad concern, it would be valuable for interested members of the entire Jabber community to discuss these matters. Unfortunately, security discussions can often be theoretical, contentious, and inconclusive. Thus it is imperative that discussion proceed based on a methodical process of threat identification, risk analysis, and prioritization before moving on to documentation of threat responses (preferably in protocol specifications such as &jep0001;). This JEP proposes a forum and process for such security discussions in the form of a Jabber Interest Group (see &jep0002;) that shall report to the &COUNCIL; in accordance with Article VIII of the &BYLAWS;.</p> <p>Because security is a core value within the Jabber community, it is appropriate for the Jabber Software Foundation to assess potential security threats related to technologies that implement the Jabber protocols (including XMPP and defined XMPP extensions), as well as ways to address the threats (for general information about the Internet threat model, see &rfc3552;). Furthermore, since security threats are wide-ranging and of broad concern, it would be valuable for interested members of the entire Jabber community to discuss these matters. Unfortunately, security discussions can often be theoretical, contentious, and inconclusive. Thus it is imperative that discussion proceed based on a methodical process of threat identification, risk analysis, and prioritization before moving on to documentation of threat responses (preferably in protocol specifications such as &xep0001;). This document proposes a forum and process for such security discussions in the form of a Jabber Interest Group (see &xep0002;) that shall report to the &COUNCIL; in accordance with Article VIII of the &BYLAWS;.</p>
</section1> </section1>
<section1 topic='Scope and Role' anchor='scope'> <section1 topic='Scope and Role' anchor='scope'>
<p>The role of the Security JIG shall be to identify and describe security threats related to Jabber technologies, analyze their potential risk, assign priorities to each threat, provide references to existing responses, and (where appropriate) provisionally recommend improvements in Jabber protocols and technologies in order to address the identified threats. The Security JIG shall not itself develop or approve protocols, which tasks shall remain under the purview of the &SJIG; and the Jabber Council respectively.</p> <p>The role of the Security JIG shall be to identify and describe security threats related to Jabber technologies, analyze their potential risk, assign priorities to each threat, provide references to existing responses, and (where appropriate) provisionally recommend improvements in Jabber protocols and technologies in order to address the identified threats. The Security JIG shall not itself develop or approve protocols, which tasks shall remain under the purview of the &SJIG; and the Jabber Council respectively.</p>
@ -75,7 +75,7 @@
<li>The estimated likelihood of the threat (e.g., high/medium/low)</li> <li>The estimated likelihood of the threat (e.g., high/medium/low)</li>
<li>The estimated potential damage the threat could cause (e.g., high/medium/low)</li> <li>The estimated potential damage the threat could cause (e.g., high/medium/low)</li>
<li>A resulting priority for addressing the threat</li> <li>A resulting priority for addressing the threat</li>
<li>Existing approaches for addressing the threat (e.g., as documented in a JEP)</li> <li>Existing approaches for addressing the threat (e.g., as documented in a XEP)</li>
<li>The gap between the identified threat and existing responses</li> <li>The gap between the identified threat and existing responses</li>
<li>Potential approaches to addressing the threat or closing the gap, including implementation issues associated with each approach (since security measures that cannot or will not be implemented are useless)</li> <li>Potential approaches to addressing the threat or closing the gap, including implementation issues associated with each approach (since security measures that cannot or will not be implemented are useless)</li>
<li>Current recommended approach (which may be "do nothing at this time")</li> <li>Current recommended approach (which may be "do nothing at this time")</li>
@ -83,8 +83,8 @@
<p>The template will not fully define the foregoing information, but instead specify what information must be defined for each threat when completing the analysis described in Step 3.</p> <p>The template will not fully define the foregoing information, but instead specify what information must be defined for each threat when completing the analysis described in Step 3.</p>
</li> </li>
<li> <li>
<p>An evolving document that completes the template defined in Step 2 for all identified threats by following the process established in Step 1. The result will be a thorough analysis of all potential security threats related to Jabber protocols and technologies. Note: This document shall not define complete solutions to the identified threats, although it may outline potential and recommended approaches. Solutions shall be defined in standalone documents such as JEPs.</p> <p>An evolving document that completes the template defined in Step 2 for all identified threats by following the process established in Step 1. The result will be a thorough analysis of all potential security threats related to Jabber protocols and technologies. Note: This document shall not define complete solutions to the identified threats, although it may outline potential and recommended approaches. Solutions shall be defined in standalone documents such as XEPs.</p>
</li> </li>
</ol> </ol>
</section1> </section1>
</jep> </xep>