mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 18:22:24 -05:00
0.14
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1164 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
2869c521c0
commit
105d4b6ba9
180
xep-0136.xml
180
xep-0136.xml
@ -37,11 +37,17 @@
|
||||
</author>
|
||||
&stpeter;
|
||||
&infiniti;
|
||||
<revision>
|
||||
<version>0.14</version>
|
||||
<date>2007-08-16</date>
|
||||
<initials>psa</initials>
|
||||
<remark><p>Clarified text regarding preference syntax; completed copy edit.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.13</version>
|
||||
<date>2007-01-08</date>
|
||||
<initials>psa/ip</initials>
|
||||
<remark><p>Harmonized chat session negotiation of message logging settings with XEP-0155; defined stream feature.</p></remark>
|
||||
<remark><p>Harmonized stanza session negotiation of message logging settings with XEP-0155; defined stream feature.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.12</version>
|
||||
@ -134,7 +140,7 @@
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'http://www.xmpp.org/extensions/xep-0136.html#ns-name', where 'name' is 'auto' for the <link url='#auto'>Automated Archiving</link> feature, 'encrypt' for the <em>server-side</em> encryption feature (see <link url='#auto'>Automated Archiving</link>), 'manage' for the <link url='#manage'>Archive Management</link> feature, 'manual' for the <link url='#manual'>Manual Archiving</link> feature, and 'pref' for the <link url='#pref'>Archiving Preferences</link> feature.</p>
|
||||
<p>For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'http://www.xmpp.org/extensions/xep-0136.html#ns-name' &NSNOTE;, where 'name' is 'auto' for the <link url='#auto'>Automated Archiving</link> feature, 'encrypt' for the <em>server-side</em> encryption feature (see <link url='#auto'>Automated Archiving</link>), 'manage' for the <link url='#manage'>Archive Management</link> feature, 'manual' for the <link url='#manual'>Manual Archiving</link> feature, and 'pref' for the <link url='#pref'>Archiving Preferences</link> feature.</p>
|
||||
<example caption='Server Service Discovery response'>
|
||||
<![CDATA[
|
||||
<iq type='result' to='romeo@montague.net/orchard' id='disco1'>
|
||||
@ -153,8 +159,8 @@
|
||||
<section1 topic='Archiving Preferences' anchor='pref'>
|
||||
<section2 topic='Introduction' anchor='pref-reqs'>
|
||||
<p>Not all users want to archive messages. A client SHOULD save its user's default archiving preference (or "Save Mode") to its own server (i.e., specify whether by default all conversations should be archived or not). In addition, a client MAY save different preferences for particular contacts.</p>
|
||||
<p>Some users may also prefer that the messages they exchange with contacts are "<link url='#otr'>Off The Record</link>" (OTR). A client SHOULD save its user's default and contact-specific OTR preferences (or "OTR Modes") to its own server.</p>
|
||||
<p>Whichever archiving method a client uses (e.g., local file archiving, or automatic or manual archiving to a server), it SHOULD adhere to its user's archiving preferences. However, a client MAY maintain a set of preferences in a local file which takes precedence over the preferences stored on the server for both local archiving and manual archiving.</p>
|
||||
<p>Some users may also prefer that the messages they exchange with contacts are "<link url='#otr'>Off The Record</link>" (OTR). <note>The "OTR" mode for message archiving is not to be confused with the "OTR" technology for "off-the-record communications" described at <<link url='http://www.cypherpunks.ca/otr/'>http://www.cypherpunks.ca/otr/</link>>.</note> A client SHOULD save its user's default and contact-specific OTR preferences (or "OTR Modes") to its own server.</p>
|
||||
<p>Whichever archiving method a client uses (e.g., local archiving to files or a database, or server-side archiving that happens either automatically or manually), it SHOULD adhere to its user's archiving preferences. However, a client MAY maintain a set of preferences in a local file which takes precedence over the preferences stored on the server for both local archiving and server-side archiving.</p>
|
||||
<p>This section addresses the following use cases:</p>
|
||||
<ol start='1'>
|
||||
<li>A client determines its user's current default Save Mode and OTR Mode, and the Modes for particular contacts.</li>
|
||||
@ -162,22 +168,101 @@
|
||||
<li>A client sets the Save Mode and OTR Mode for a particular contact.</li>
|
||||
</ol>
|
||||
</section2>
|
||||
<section2 topic='Preference Syntax' anchor='pref-syntax'>
|
||||
<p>Archiving preferences are encapsulated in four children of the <pref/> element: <auto/>, <default/>, <item/>, and <method/>. These are defined in the following sections.</p>
|
||||
<section3 topic='Auto Element' anchor='pref-syntax-auto'>
|
||||
<p>The <auto/> element specifies the current <link url='#auto'>Automated Archiving</link> settings for <em>this stream</em>.</p>
|
||||
<p>This element MUST be empty and MUST include a boolean 'save' attribute &BOOLEANNOTE; that specifies whether automated archiving is enabled or disabled for this stream.</p>
|
||||
</section3>
|
||||
<section3 topic='Default Element' anchor='pref-syntax-default'>
|
||||
<p>The <default/> element specifies the default settings for both OTR Mode and Save Mode. The element MUST be empty and MUST include an 'otr' attribute and a 'save' attribute. The element MAY include an 'expire' attribute.</p>
|
||||
<section4 topic='expire Attribute' anchor='pref-syntax-default-expire'>
|
||||
<p>If the 'save' attribute is <em>not</em> set to 'false' then is RECOMMENDED to also include an 'expire' attribute, which indicates how many seconds after messages are archived that the server SHOULD delete them.</p>
|
||||
</section4>
|
||||
<section4 topic='otr Attribute' anchor='pref-syntax-default-otr'>
|
||||
<p>The 'otr' attribute specifies the user's default setting for OTR Mode. The allowable values are:</p>
|
||||
<ul>
|
||||
<li>approve -- the user MUST explicitly approve off-the-record communication.</li>
|
||||
<li>concede -- communications MAY be off the record if requested by another user.</li>
|
||||
<li>forbid -- communications MUST NOT be off the record.</li>
|
||||
<li>oppose -- communications SHOULD NOT be off the record even if requested.</li>
|
||||
<li>prefer -- communications SHOULD be off the record if possible.</li>
|
||||
<li>require -- communications MUST be off the record. *</li>
|
||||
</ul>
|
||||
<p>* Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'. An 'otr' attribute value of "require" in Message Archiving is equivalent to a 'logging' attribute value of "mustnot" in Stanza Session Negotiation; for details, see the <link url='#otr-nego'>OTR Negotiation</link> section of this document.</p>
|
||||
</section4>
|
||||
<section4 topic='save Attribute' anchor='pref-syntax-default-save'>
|
||||
<p>The 'save' attribute specifies the user's default setting for Save Mode. The allowable values are:</p>
|
||||
<ul>
|
||||
<li>body -- the saving entity SHOULD save only &BODY; elements. *</li>
|
||||
<li>false -- the saving entity MUST save nothing.</li>
|
||||
<li>message -- the saving entity SHOULD save the full XML content of each &MESSAGE; element. **</li>
|
||||
<li>stream -- the saving entity SHOULD save every byte that passes over the stream in either direction. ***</li>
|
||||
</ul>
|
||||
<p>* Note: When archiving <em>locally</em> a client MAY save the full XML content of each &MESSAGE; element even if the Save Mode is 'body'.</p>
|
||||
<p>** Note: Support for the 'message' value is optional and, to conserve bandwidth and storage space, it is RECOMMENDED that client implementations do not specify the 'message' value. <note>Stream compression typically does not mitigate bandwidth and storage issues since collections SHOULD be encrypted, and since clients running in constrained runtime environments typically cannot take advantage of stream compression (no binary data, only XML, may be transfered).</note></p>
|
||||
<p>*** Note: The upload, retrieval and management of 'stream' archives is currently beyond the scope of this document.</p>
|
||||
</section4>
|
||||
</section3>
|
||||
<section3 topic='Item Element' anchor='pref-syntax-item'>
|
||||
<p>The <item/> element specifies the settings for both the OTR Mode and Save Mode with regard to a particular entity. The element MUST be empty and MUST include a 'jid' attribute, an 'otr' attribute, and a 'save' attribute. The element MAY include an 'expire' attribute.</p>
|
||||
<section4 topic='expire Attribute' anchor='pref-syntax-default-expire'>
|
||||
<p>If the 'save' attribute is <em>not</em> set to 'false' then is RECOMMENDED to also include an 'expire' attribute, which indicates how many seconds after messages are archived that the server SHOULD delete them.</p>
|
||||
</section4>
|
||||
<section4 topic='jid Attribute' anchor='pref-syntax-item-jid'>
|
||||
<p>The 'jid' attribute specifies the JabberID of the XMPP entity to which the preferences specified in this <item/> element apply.</p>
|
||||
</section4>
|
||||
<section4 topic='otr Attribute' anchor='pref-syntax-item-otr'>
|
||||
<p>The 'otr' attribute specifies the user's setting for OTR Mode with regard to the specified JID. The allowable values are:</p>
|
||||
<ul>
|
||||
<li>approve -- the user MUST explicitly approve off-the-record communication.</li>
|
||||
<li>concede -- communications MAY be off the record if requested by another user.</li>
|
||||
<li>forbid -- communications MUST NOT be off the record.</li>
|
||||
<li>oppose -- communications SHOULD NOT be off the record even if requested.</li>
|
||||
<li>prefer -- communications SHOULD be off the record if possible.</li>
|
||||
<li>require -- communications MUST be off the record. *</li>
|
||||
</ul>
|
||||
<p>* Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'. An 'otr' attribute value of "require" in Message Archiving is equivalent to a 'logging' attribute value of "mustnot" in Stanza Session Negotiation; for details, see the <link url='#otr-nego'>OTR Negotiation</link> section of this document.</p>
|
||||
</section4>
|
||||
<section4 topic='save Attribute' anchor='pref-syntax-item-save'>
|
||||
<p>The 'save' attribute specifies the user's setting for Save Mode with regard to the specified JID. The allowable values are:</p>
|
||||
<ul>
|
||||
<li>body -- the saving entity SHOULD save only &BODY; elements.</li>
|
||||
<li>false -- the saving entity MUST save nothing.</li>
|
||||
<li>message -- the saving entity SHOULD save the full XML content of each &MESSAGE; element.</li>
|
||||
<li>stream -- the saving entity SHOULD save every byte that passes over the stream in either direction. *</li>
|
||||
</ul>
|
||||
<p>* Note: The upload, retrieval and management of 'stream' archives is <em>currently</em> beyond the scope of this document.</p>
|
||||
</section4>
|
||||
</section3>
|
||||
<section3 topic='Method Element' anchor='pref-syntax-method'>
|
||||
<p>Each <method/> element specifies the the user's preferences for one available archiving method. The <method/> element MUST be empty and MUST include both the 'type' and 'use' attributes. The <pref/> element MUST include at least three <method/> elements, differentiated by the value of the 'type' attribute.</p>
|
||||
<section4 topic='type Attribute' anchor='pref-syntax-method-type'>
|
||||
<p>The allowable values of the 'type' attribute are:</p>
|
||||
<ul>
|
||||
<li>auto -- preferences for use of automatic archiving on the user's server.</li>
|
||||
<li>local -- preferences for use of local archiving to a file or database on the user's machine or device.</li>
|
||||
<li>manual -- preferences for use of manual archiving by the user's client to the user's server.</li>
|
||||
</ul>
|
||||
</section4>
|
||||
<section4 topic='use Attribute' anchor='pref-syntax-method-use'>
|
||||
<p>The allowable values of the 'use' attribute are:</p>
|
||||
<ul>
|
||||
<li>concede -- this method MAY be used if no other methods are available.</li>
|
||||
<li>forbid -- this method MUST NOT be used.</li>
|
||||
<li>prefer -- this method SHOULD be used if available.</li>
|
||||
</ul>
|
||||
</section4>
|
||||
</section3>
|
||||
</section2>
|
||||
<section2 topic='Determining Preferences' anchor='pref-determine'>
|
||||
<p>In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends an empty <pref/> element to its server:</p>
|
||||
<p>In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends to its server an IQ-get containing an empty <pref/> element qualified by the 'http://www.xmpp.org/extensions/xep-0136.html#ns' namespace &NSNOTE;.</p>
|
||||
<example caption='Client Requests Archiving Preferences'><![CDATA[
|
||||
<iq type='get' id='pref1'>
|
||||
<pref xmlns='http://www.xmpp.org/extensions/xep-0136.html#ns'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The server responds with the default Save Mode and OTR Mode (a single <default/> element) and any specific Save Modes and OTR Modes for individual contacts (zero or more <item/> elements).</p>
|
||||
<p>Each <default/> or <item/> element in the response MUST include a 'save' attribute, whose value MAY be 'false' (the saving entity MUST save nothing), 'body' (the saving entity SHOULD save only &BODY; elements), 'message' (the saving entity SHOULD save the full XML content of each &MESSAGE; element) or 'stream' (the saving entity SHOULD save every byte that passes over the stream in either direction). Note: The upload, retrieval and management of 'stream' archives is <em>currently</em> beyond the scope of this document.</p>
|
||||
<p>Note: Support for the 'message' value is optional and, to conserve bandwidth and storage space, it is RECOMMENDED that client implementations do not specify the 'message' value. <note>Stream compression typically does not mitigate bandwidth and storage issues since collections SHOULD be encrypted, and since clients running in constrained runtime environments typically cannot take advantage of stream compression (no binary data, only XML, may be transfered).</note></p>
|
||||
<p>Note: When archiving <em>locally</em> a client MAY save the full XML content of each &MESSAGE; element even if the Save Mode is 'body'.</p>
|
||||
<p>Each <default/> or <item/> element in the response whose 'save' attribute is not set to 'false' is RECOMMENDED to also include an 'expire' attribute which indicates how many seconds after messages are archived that the server SHOULD delete them.</p>
|
||||
<p>Each <default/> or <item/> element in the response MUST include an 'otr' attribute, whose value MAY be 'require', 'prefer', 'approve', 'concede', 'oppose', or 'forbid'. The client MUST be guided by the specified 'logging' attribute value when negotiating (see &xep0155;) whether or not all messages exchanged with a contact will be <link url='#otr'>Off The Record</link>. (Note: An 'otr' attribute value of "require" in Message Archiving is equivalent to a 'logging' attribute value of "mustnot" in Chat Session Negotiation; for details, see the <link url='#otr-nego'>OTR Negotiation</link> section of this document.)</p>
|
||||
<p>Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'.</p>
|
||||
<p>The server MUST also include <method/> elements that reflect the user's preferences for each of the possible archiving methods. There MUST be at least three such elements for local file archiving (type 'local'), automatic archiving by the user's server (type 'auto'), and manual archiving to a server (type 'manual'). The 'use' attribute of each <method/> element MUST be set to 'prefer', 'concede' or 'forbid' - indicating which archiving methods the user's clients SHOULD, MAY (if it does not support any preferred method) or MUST NOT use.</p>
|
||||
<p>The server MUST also include an <auto/> element reflecting the current <link url='#auto'>Automated Archiving</link> settings for <em>this stream</em>.</p>
|
||||
<example caption='Server Returns Preferences'><![CDATA[
|
||||
<iq type='result' id='pref1' to='juliet@capulet.com/chamber'>
|
||||
<pref xmlns='http://www.xmpp.org/extensions/xep-0136.html#ns'>
|
||||
@ -191,6 +276,15 @@
|
||||
</pref>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The foregoing preferences can be explained as follows:</p>
|
||||
<ol>
|
||||
<li>By default, message bodies should be saved (according the preferred method specified later), communications may be off the record if requested, and any saved messages should be expired after 1 year.</li>
|
||||
<li>When communicating with romeo@montague.net, both entities must not save messages and all communications must be off the record.</li>
|
||||
<li>When communicating with benvolio@montague.net, both entities should save full messages, communications must not be off the record, and any saved messages should be expired after 20 years.</li>
|
||||
<li>Server-side archiving must not occur automatically.</li>
|
||||
<li>Local archiving may be used if requested.</li>
|
||||
<li>Manual server-side archiving is preferred.</li>
|
||||
</ol>
|
||||
<p>If the user has never set the default Modes, the 'save' and 'otr' attributes SHOULD specify the server's default settings, and the 'unset' attribute SHOULD be set to 'true'. Note: The 'unset' attribute defaults to 'false'.</p>
|
||||
<example caption='Server Returns Service Default Preferences'><![CDATA[
|
||||
<iq type='result' id='pref1' to='juliet@capulet.com/chamber'>
|
||||
@ -300,11 +394,11 @@
|
||||
<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.</p>
|
||||
<section2 topic='OTR Negotiation' anchor='otr-nego'>
|
||||
<p>Any client that archives messages SHOULD support <cite>Chat Session Negotiation</cite> and its 'logging' 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>Any client that archives messages SHOULD support <cite>Stanza Session Negotiation</cite> and its 'logging' 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>Note: A client MUST NOT propose or agree to enable OTR (i.e., disallow message logging) unless it has confirmed that its server will allow it to switch off <link url='#auto'>Automated Archiving</link>.</p>
|
||||
<p>Both parties to a chat session negotiation may have OTR preferences (i.e, the initiating party or "user" and the responding party or "contact"). These preferences will interact in the ways specified below, resulting either in a successful negotiation or an unsuccessful negotiation (naturally, an unsuccessful negotiation can lead to a subsequent negotiation attempt by the user or the contact).</p>
|
||||
<p>The following table shows what chat session negotiation values the initating party (i.e., the "user") should send for the 'logging' field in the initial data form for a chat session negotiation (note: 'may' means that the receiving party MAY enable message logging and 'mustnot' means that the receiving party MUST NOT enable logging).</p>
|
||||
<table caption='Chat Session Negotiation logging options offered by initiating party (user)'>
|
||||
<p>Both parties to a stanza session negotiation may have OTR preferences (i.e, the initiating party or "user" and the responding party or "contact"). These preferences will interact in the ways specified below, resulting either in a successful negotiation or an unsuccessful negotiation (naturally, an unsuccessful negotiation can lead to a subsequent negotiation attempt by the user or the contact).</p>
|
||||
<p>The following table shows what stanza session negotiation values the initating party (i.e., the "user") should send for the 'logging' field in the initial data form for a stanza session negotiation (note: 'may' means that the receiving party MAY enable message logging and 'mustnot' means that the receiving party MUST NOT enable logging).</p>
|
||||
<table caption='Stanza Session Negotiation logging options offered by initiating party (user)'>
|
||||
<tr>
|
||||
<th>User's OTR Preference</th>
|
||||
<th>Offering 'logging' Negotiation Option(s)*</th>
|
||||
@ -337,9 +431,9 @@
|
||||
<p>* In order of preference, the first value is the default.</p>
|
||||
<p>** If the user receives no response it MUST NOT send any messages to the contact.</p>
|
||||
<p>*** Alternatively, the user MAY decide not to <em>initiate</em> an OTR negotiation and to save messages (until the contact initiates a negotiation).</p>
|
||||
<p>Note: When negotiating a chat session, the user MUST include the <required/> element inside the 'logging' <field/> element. If the user does not receive a successful response to its chat negotiation request (and if the OTR Mode is not 'require'), then it SHOULD proceed as if the contact had responded with the value of the 'logging' <field/> element set to 'may'.</p>
|
||||
<p>The following table shows what chat session negotiation values the responding party (i.e., "contact") should send for the 'logging' field in its response to a chat session negotiation request from the user.</p>
|
||||
<table caption='Chat Session Negotiation logging value selected by responding party (contact)'>
|
||||
<p>Note: When negotiating a stanza session, the user MUST include the <required/> element inside the 'logging' <field/> element. If the user does not receive a successful response to its chat negotiation request (and if the OTR Mode is not 'require'), then it SHOULD proceed as if the contact had responded with the value of the 'logging' <field/> element set to 'may'.</p>
|
||||
<p>The following table shows what stanza session negotiation values the responding party (i.e., "contact") should send for the 'logging' field in its response to a stanza session negotiation request from the user.</p>
|
||||
<table caption='Stanza Session Negotiation logging value selected by responding party (contact)'>
|
||||
<tr>
|
||||
<th>Contact's OTR Preference</th>
|
||||
<th colspan='4'>Responding 'logging' Negotiation Values*</th>
|
||||
@ -395,13 +489,13 @@
|
||||
</tr>
|
||||
</table>
|
||||
<p>* The first value is the default.</p>
|
||||
<p>** The negotiation fails and the parties MUST NOT exchange any messages; however, the recipient MAY attempt to initiate a chat session negotiation with the other party.</p>
|
||||
<p>Note: If a contact does not include a 'logging' 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 a 'logging' field.</p>
|
||||
<p>** The negotiation fails and the parties MUST NOT exchange any messages; however, the recipient MAY attempt to initiate a stanza session negotiation with the other party.</p>
|
||||
<p>Note: If a contact does not include a 'logging' field in its initial Stanza 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 Stanza Session Negotiation request with a 'logging' field.</p>
|
||||
<p>If a user's OTR preference for a contact changes during a Chat Session that has been negotiated with the contact, and if the new preference would affect the value of the 'logging' field that was previously negotiated, then the client MUST immediately renegotiate the 'logging' field according to the user's new OTR preference (or terminate the Chat Session).</p>
|
||||
</section2>
|
||||
<section2 topic='Notes' anchor='otr-notes'>
|
||||
<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 both clients MUST ensure that the Chat Session Negotiation messages themselves are not archived. For example, if <link url='#auto'>Automated Archiving</link> was enabled when the client received the initial Chat Session Negotiation request, then the client MUST immediately ask its server to delete its copy of the request (see <link url='#manage-remove'>Removing a Collection</link> for a description of how to remove the messages currently being recorded by the server).</p>
|
||||
<p>If a Stanza 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 from archiving conversations.</note></p>
|
||||
<p>If a Stanza Session Negotiation agreed to enable OTR then both clients MUST ensure that the Stanza Session Negotiation messages themselves are not archived. For example, if <link url='#auto'>Automated Archiving</link> was enabled when the client received the initial Stanza Session Negotiation request, then the client MUST immediately ask its server to delete its copy of the request (see <link url='#manage-remove'>Removing a Collection</link> for a description of how to remove the messages currently being recorded by the server).</p>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Manual Archiving' anchor='manual'>
|
||||
@ -428,7 +522,7 @@
|
||||
<p>If an opaque thread ID (found in the &THREAD; children of the &MESSAGE; elements whose content is stored in the collection) is associated with the conversation then it MUST be specified with a 'thread' attribute. Clients SHOULD include a &THREAD; child in each &MESSAGE; element they send that is part of a conversation they expect will be archived (see &xep0201;).</p>
|
||||
<p>Note: The content of &MESSAGE; elements that have different thread IDs SHOULD be archived in separate collections. The content of &MESSAGE; elements that have the same thread IDs SHOULD be archived in the same collection. The thread attribute SHOULD NOT be set to any value other than the exact content of the &THREAD; elements. If no &THREAD; elements appeared in the conversation the <chat/> element SHOULD have no thread attribute. Implementations SHOULD use the thread attribute for cross-referencing purposes only, within the archive each collection MUST be uniquely identified by the combination of its 'with' and 'start' attributes.</p>
|
||||
<p>Each collection MAY contain <note/>, <to/> or <from/> elements (or <EncryptedData/> and <EncryptedKey/> elements - see <link url='#crypt'>Encryption</link>).</p>
|
||||
<p>The text of each individual private note MUST be encapsulated in a <note/> element. The absolute time the note was created SHOULD be specified with a 'utc' attribute (which MUST be UTC and adhere to the DateTime format specified in <cite>Jabber Date and Time Profiles</cite>).</p>
|
||||
<p>The text of each individual private note MUST be encapsulated in a <note/> element. The absolute time the note was created SHOULD be specified with a 'utc' attribute (which MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>).</p>
|
||||
<p>The content of each individual message MUST be encapsulated in a <to/> or <from/> element. The time in whole seconds of the message relative to the previous message in the collection (or, for the first message, relative to the start of the collection) SHOULD be specified with a 'secs' attribute. Note: When deciding whether to round up or down to a number of whole seconds, entities MUST ensure that the sum of the 'secs' attribute and the 'secs' attributes of the preceeding messages will accurately reflect the absolute time of the message. (e.g., if a sequence of messages occur at exactly 0.51-second intervals then the 'secs' attributes should generally alternate between '0' or '1'.)</p>
|
||||
<p>The content of each <to/> or <from/> element SHOULD depend on the user's <link url='#pref'>Archiving Preferences</link>. <to/> or <from/> elements MUST NOT be empty. Note: A server MAY be configured to return a <feature-not-implemented/> error if any <to/> or <from/> element contains anything other than &BODY; elements.</p>
|
||||
</section2>
|
||||
@ -476,7 +570,7 @@
|
||||
]]></example>
|
||||
</section2>
|
||||
<section2 topic='Offline Messages' anchor='impl-offline'>
|
||||
<p>The client MAY specify an absolute time for any message by providing a longer 'utc' attribute (which MUST be UTC and adhere to the DateTime format specified in <cite>Jabber Date and Time Profiles</cite>) instead of a 'secs' attribute. The absolute time MAY be before the start time of the collection:</p>
|
||||
<p>The client MAY specify an absolute time for any message by providing a longer 'utc' attribute (which MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>) instead of a 'secs' attribute. The absolute time MAY be before the start time of the collection:</p>
|
||||
<example caption='Storing offline messages in a collection'><![CDATA[
|
||||
<iq type='set' id='up2'>
|
||||
<save xmlns='http://www.xmpp.org/extensions/xep-0136.html#ns'>
|
||||
@ -612,10 +706,10 @@
|
||||
<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 releases). 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 <EncryptedKey/> 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 <EncryptedKey/> element for each of its user's public keys that are being published using &xep0189;. However, the client MUST NOT create an <EncryptedKey/> 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 <EncryptedKey/> element for each of its user's public keys that are being published using &xep0189;. However, the client MUST NOT create an <EncryptedKey/> 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>XEP-0189</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 <to/>, <from/> and <note/> elements, base64 encode the resulting sequence of bytes, and wrap it inside an <EncryptedData/> element, as described in <cite>XML Encryption</cite>.</p>
|
||||
<p>Clients may add one or more <EncryptedData/> or <EncryptedKey/> elements to a collection using exactly the same method as for <to/>, <from/> and <note/> elements (see <link url='#manual-upload'>Uploading Messages to a Collection</link>). One collection may contain <EncryptedData/> elements encrypted with different symmetric keys.</p>
|
||||
<p>When appending <EncryptedData/> 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 <EncryptedKey/> elements.</p>
|
||||
<p>When appending <EncryptedData/> 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 <EncryptedKey/> elements.</p>
|
||||
<p>Note: A collection that contains <EncryptedData/> or <EncryptedKey/> elements MUST NOT contain <to/> or <from/> or <note/> elements.</p>
|
||||
<example caption='Storing encrypted messages and keys in a collection'><![CDATA[
|
||||
<iq type='set' id='crypt1'>
|
||||
@ -652,7 +746,7 @@
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The <CipherData/> child of each <EncryptedData/> element contains the base64-encoded symmetric-encrypted messages. The <EncryptionMethod/> and <KeyInfo/> children specify the symmetric encryption algorithm and the name of the symmetric key used to encrypt the messages.</p>
|
||||
<p>The <CarriedKeyName/> child of each <EncryptedKey/> element contains the name of the symmetric key it contains. The name is referenced by the <KeyName/> child of the <KeyInfo/> child of an <EncryptedData/> element. The <CipherData/> child of each <EncryptedKey/> element contains the base64-encoded public-key-encrypted symmetric key. The <EncryptionMethod/> and <KeyInfo/> children specify the public key encryption algorithm and the name of the public key used to encrypt the symmetric key. The name of the public key MAY refer to the name in the <KeyName/> child of one of the <KeyInfo/> elements that are being published using <cite>Public Key Publishing</cite>.</p>
|
||||
<p>The <CarriedKeyName/> child of each <EncryptedKey/> element contains the name of the symmetric key it contains. The name is referenced by the <KeyName/> child of the <KeyInfo/> child of an <EncryptedData/> element. The <CipherData/> child of each <EncryptedKey/> element contains the base64-encoded public-key-encrypted symmetric key. The <EncryptionMethod/> and <KeyInfo/> children specify the public key encryption algorithm and the name of the public key used to encrypt the symmetric key. The name of the public key MAY refer to the name in the <KeyName/> child of one of the <KeyInfo/> elements that are being published using <cite>XEP-0189</cite>.</p>
|
||||
</section1>
|
||||
<section1 topic='Automated Archiving' anchor='auto'>
|
||||
<section2 topic='Toggling Auto-Archiving' anchor='auto-toggle'>
|
||||
@ -685,7 +779,7 @@
|
||||
<section2 topic='Enabling Auto-Archiving with Encryption' anchor='auto-crypt'>
|
||||
<p>Servers (and clients) SHOULD support the encryption (and decryption) of automatically-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later releases).</p>
|
||||
<p>Whenever the client enables auto-archiving it SHOULD set the optional 'encrypt' attribute to 'true'. After receiving such a request, if the server supports encryption (see <link url='#disco'>Determining Server Support</link>), it MUST encrypt all the messages that it archives automatically (including any message collections that are currently being recorded) by following exactly the same procedure as clients use when manually archiving collections (see <link url='#crypt'>Encryption</link>).</p>
|
||||
<p>The client MAY also specify one or more public keys (in addition to any public keys that the user may be publishing using <cite>Public Key Publishing</cite>). The server MUST use them all to encrypt all the symmetric keys it generates and add these to the collection wrapped in <EncryptedKey/> elements.</p>
|
||||
<p>The client MAY also specify one or more public keys (in addition to any public keys that the user may be publishing using <cite>XEP-0189</cite>). The server MUST use them all to encrypt all the symmetric keys it generates and add these to the collection wrapped in <EncryptedKey/> elements.</p>
|
||||
<example caption='Client enables auto archiving with encryption'><![CDATA[
|
||||
<iq type='set' id='auto2'>
|
||||
<auto save='true'
|
||||
@ -713,7 +807,7 @@
|
||||
<ul>
|
||||
<li><p>If the client is trying to enable automatic archiving, but the server does not allow the saving of full message stanza content, and the user has specified the 'message' Save Mode in one of its <link url='#pref'>Archiving Preferences</link>.</p></li>
|
||||
<li><p>If administrator policies require that every message is logged automatically, and the client is trying to disable automatic archiving.</p></li>
|
||||
<li><p>If the client is trying to enable encryption, but the server does not support encryption or the user did not specify a public key and is not publishing any keys using <cite>Public Key Publishing</cite>.</p></li>
|
||||
<li><p>If the client is trying to enable encryption, but the server does not support encryption or the user did not specify a public key and is not publishing any keys using <cite>XEP-0189</cite>.</p></li>
|
||||
</ul>
|
||||
</section2>
|
||||
</section1>
|
||||
@ -726,7 +820,7 @@
|
||||
</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 &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.</p>
|
||||
<section2 topic='Retrieving a List of Collections' anchor='manage-list'>
|
||||
<p>To request a list of collections the client sends a <list/> 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 <list/> 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>XEP-0082</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>The client SHOULD use <cite>Result Set Management</cite> to limit the number of collections returned by the server in a single stanza, taking care not to request a page of collections that is so big it might exceed karma limits.</p>
|
||||
<example caption='Requesting the first page of a list with same JID'><![CDATA[
|
||||
@ -782,7 +876,7 @@
|
||||
</list>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: In accordance with <cite>Result Set Management</cite>, the client MUST assume the unique IDs it receives in the <first/> and <last/> elements are opaque. Servers MAY adopt a unique ID format other than the one suggested in the example above.</p>
|
||||
<p>Note: In accordance with <cite>Result Set Management</cite>, the client MUST assume that the unique IDs it receives in the <first/> and <last/> elements are opaque. Servers MAY adopt a unique ID format other than the one suggested in the example above.</p>
|
||||
<p>If no collections correspond to the request the server MUST return an empty <list/> element:</p>
|
||||
<example caption='Receiving an empty list'><![CDATA[
|
||||
<iq type='result' to='romeo@montague.net/orchard' id='list1'>
|
||||
@ -803,7 +897,7 @@
|
||||
<p>Refer to <cite>Result Set Management</cite> to learn more about the various ways that the pages of the list may be accessed.</p>
|
||||
</section2>
|
||||
<section2 topic='Retrieving a Collection' anchor='manage-retrieve'>
|
||||
<p>To request a page of messages from a collection the client sends a <retrieve/> element. The 'with' and 'start' attributes specify the participating full JID and the start time (see <cite>Jabber Date and Time Profiles</cite>). Both attributes MUST be included to uniquely identify a collection:</p>
|
||||
<p>To request a page of messages from a collection the client sends a <retrieve/> element. The 'with' and 'start' attributes specify the participating full JID and the start time (see <cite>XEP-0082</cite>). Both attributes MUST be included to uniquely identify a collection:</p>
|
||||
<p>The client SHOULD use <cite>Result Set Management</cite> to limit the number of messages returned by the server in a single stanza, taking care not to request a page of messages that is so big it might exceed karma limits.</p>
|
||||
<example caption='Requesting the first page of a collection'><![CDATA[
|
||||
<iq type='get' id='page1'>
|
||||
@ -1127,7 +1221,7 @@
|
||||
<section1 topic='Replication'>
|
||||
<p>This section describes how a client MAY replicate an archive locally. <note>Clients that run in constrained environments may not be able to implement replication if they are prevented from accessing (sufficient) local storage.</note> The existence of a local copy of the archive enables clients to search the content of all messages (including collections saved by another client machine). <note>Since collections SHOULD be stored on the server in a form that it cannot decrypt, server-side searching of the content of messages is beyond the scope of this protocol.</note></p>
|
||||
<p>The client MAY 'synchronize' its local copy of the archive with the 'master' archive on the server at any time. The first step is to request the list of collections that the server has changed (created, modified or removed) in its master archive since the last update to the client's copy of the archive.</p>
|
||||
<p>The client MUST request each page of the list using the <cite>Result Set Management</cite> protocol embeded in a <modified/> element. The content of the <after/> element SHOULD be a UTC time (see <cite>Jabber Date and Time Profiles</cite>) that it has previously received from the server (see below). When synchronizing for the first time, the client MAY choose a suitable time for the first page request (e.g. 1970-01-01T00:00:00Z).</p>
|
||||
<p>The client MUST request each page of the list using the <cite>Result Set Management</cite> protocol embedded in a <modified/> element. The content of the <after/> element SHOULD be a UTC time (see <cite>XEP-0082</cite>) that it has previously received from the server (see below). When synchronizing for the first time, the client MAY choose a suitable time for the first page request (e.g. 1970-01-01T00:00:00Z).</p>
|
||||
<example caption='Requesting a page of modifications'>
|
||||
<![CDATA[
|
||||
<iq type='get' id='sync1'>
|
||||
@ -1139,7 +1233,7 @@
|
||||
</modified>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created or removed <em>after</em> the time specified by the <after/> element then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include only 'with' and 'start' attribues. The server MUST set the content of the <last/> element to the UTC time (see <cite>Jabber Date and Time Profiles</cite>) that the last collection on the page was modified.</p>
|
||||
<p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created or removed <em>after</em> the time specified by the <after/> element then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include only 'with' and 'start' attribues. The server MUST set the content of the <last/> element to the UTC time (see <cite>XEP-0082</cite>) that the last collection on the page was modified.</p>
|
||||
<example caption='Receiving a page of modifications'><![CDATA[
|
||||
<iq type='result' to='romeo@montague.net/orchard' id='sync1'>
|
||||
<modified xmlns='http://www.xmpp.org/extensions/xep-0136.html#ns'>
|
||||
@ -1157,7 +1251,7 @@
|
||||
</modified>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: The server should remember the 'with' and 'start' attribues and the time of removal of all deleted collections. If this 'state' cannot be maintained indefinitely, then unless all the user's clients replicate before the server deletes its memory of a removal then it will not be reflected in all the local copies of the archive.</p>
|
||||
<p>Note: The server should remember the 'with' and 'start' attribues and the time of removal of all deleted collections. If this "state" cannot be maintained indefinitely, then unless all the user's clients replicate before the server deletes its memory of a removal then it will not be reflected in all the local copies of the archive.</p>
|
||||
<p>Note: Along with its copy of the archive the client SHOULD save the most recent <last/> time that it received from the server. The next time it synchronizes with the server it SHOULD specify that time when requesting the first result set page (see above).</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>
|
||||
@ -1189,7 +1283,7 @@
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Stream Feature' anchor='streamfeature'>
|
||||
<p>Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "http://www.xmpp.org/extensions/xep-0136.html#ns" (see <link url='#ns'>Protocol Namespace</link>) during stream setup (via the <feature/> element, which MUST NOT contain a <required/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include a <default/> child).</p>
|
||||
<p>Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "http://www.xmpp.org/extensions/xep-0136.html#ns" &NSNOTE; during stream setup (via the <feature/> element, which MUST NOT contain a <required/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include a <default/> child).</p>
|
||||
<example caption='Stream Feature'><![CDATA[
|
||||
<feature xmlns='http://www.xmpp.org/extensions/xep-0136.html#ns'/>
|
||||
]]></example>
|
||||
@ -1218,10 +1312,10 @@
|
||||
</section1>
|
||||
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||
<section2 topic='Protocol Namespace' anchor='ns'>
|
||||
<p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0155.html#ns"; upon advancement of this specification, the XMPP Registrar shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||||
<p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0155.html#ns"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||||
</section2>
|
||||
<section2 topic='Service Discovery Features' anchor='registrar-features'>
|
||||
<p>The XMPP 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;), where the string "http://www.xmpp.org/extensions/xep-0136.html#ns" shall be replaced with the URN issued by the XMPP Registrar:</p>
|
||||
<ul>
|
||||
<li>http://www.xmpp.org/extensions/xep-0136.html#ns-auto</li>
|
||||
<li>http://www.xmpp.org/extensions/xep-0136.html#ns-encrypt</li>
|
||||
@ -1231,12 +1325,12 @@
|
||||
</ul>
|
||||
</section2>
|
||||
<section2 topic='Field Standardization' anchor='registrar-formtype'>
|
||||
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Message Archiving:</p>
|
||||
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Message Archiving, where the FORM_TYPE "http://www.xmpp.org/extensions/xep-0136.html#ns" shall be replaced with the URN issued by the XMPP Registrar:</p>
|
||||
<code caption='Registry Submission'><![CDATA[
|
||||
<form_type>
|
||||
<name>http://www.xmpp.org/extensions/xep-0136.html#ns</name>
|
||||
<jep>XEP-0136</jep>
|
||||
<desc>Attributes of a message collection</desc>
|
||||
<doc>XEP-0136</doc>
|
||||
<desc>Attributes of a message collection stored using Message Archiving</desc>
|
||||
<field
|
||||
var='task'
|
||||
type='boolean'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user