0.11 RC1 added otr attribute values and explanatory tables

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@167 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0136.xml

@@ -40,7 +40,7 @@
     <version>0.11</version>
     <date>2006-11-03</date>
     <initials>ip</initials>
-    <remark><p>Changed the try and deny otr attribute values to prefer and forbid, and the never use attribute value to forbid</p></remark>
+    <remark><p>Added more otr attribute values and clarified their meaning, changed the never use attribute value to forbid</p></remark>
   </revision>
   <revision>
     <version>0.10</version>
@@ -121,7 +121,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 &lt;feature/&gt; element with the 'var' attribute set to 'http://jabber.org/protocol/archive#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, or "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 &lt;feature/&gt; element with the 'var' attribute set to 'http://jabber.org/protocol/archive#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, or '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'>
@@ -157,13 +157,12 @@
 </iq>
     ]]></example>
     <p>The server responds with the default Save Mode and OTR Mode (a single &lt;default/&gt; element) and any specific Save Modes and OTR Modes for individual contacts (zero or more &lt;item/&gt; elements).</p>
-    <p>Each &lt;default/&gt; or &lt;item/&gt; element in the response MUST include a 'save' attribute, whose value MAY be 'false' (the client MUST save no messages), 'body' (the client SHOULD save only &lt;body/&gt; elements) or 'all' (the client SHOULD save the full XML content of each &lt;message/&gt; element).</p>
+    <p>Each &lt;default/&gt; or &lt;item/&gt; element in the response MUST include a 'save' attribute, whose value MAY be 'false' (the client MUST save no messages), 'body' (the client SHOULD save only &lt;body/&gt; elements) or 'all' (the client SHOULD save the full XML content of each &MESSAGE; element).</p>
     <p>Note: Support for the 'all' value is optional and, to conserve bandwidth and storage space, it is RECOMMENDED that client implementations do not specify the 'all' value.</p>
-    <p>Note: When archiving <em>locally</em> a client MAY save the full XML content of each &lt;message/&gt; element even if the Save Mode is 'body'.</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 &lt;default/&gt; or &lt;item/&gt; 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 &lt;default/&gt; or &lt;item/&gt; element in the response MUST include an 'otr' attribute, whose value MAY be 'forbid' (if <link url='#otr'>Off The Record</link> is <em>required</em> by the contact the client MUST send no messages), 'allow' (the client SHOULD save messages unless the contact <em>requests</em> or requires OTR), 'prefer' (the client MUST do its best to negotiate OTR with the contact) or 'require' (the client MUST send no messages unless the contact explicitly agrees to OTR).</p>
+    <p>Each &lt;default/&gt; or &lt;item/&gt; element in the response MUST include an 'otr' attribute, whose value MAY be 'require', 'prefer', 'approve', 'allow', 'resist' or 'forbid'. The client MUST be guided by the specified 'otr' 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: If the OTR Mode is 'require' then the Save Mode MUST be 'false'.</p>
-    <p>Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'.</p>
+    <p>The server MUST also include &lt;method/&gt; 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 &lt;method/&gt; element MUST be set to 'prefer', 'allow' 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 &lt;method/&gt; 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 &lt;method/&gt; element MUST be set to "prefer", "allow" 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 &lt;auto/&gt; 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'>
@@ -178,7 +177,7 @@
   </pref>
 </iq>
     ]]></example>
-    <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>
+    <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'>
   <pref xmlns='http://jabber.org/protocol/archive'>
@@ -221,8 +220,8 @@
     ]]></example>
     <p>The server MAY be configured to return a &lt;feature-not-implemented/&gt; error in the following cases:</p>
     <ul>
-      <li><p>If it does not allow the saving of full message stanza content, and the client set the value of the 'save' attribute to "all", and any of the user's connected resources have <link url='#auto'>Automated Archiving</link> enabled.</p></li>
+      <li><p>If it does not allow the saving of full message stanza content, and the client set the value of the 'save' attribute to 'all', and any of the user's connected resources have <link url='#auto'>Automated Archiving</link> enabled.</p></li>
-      <li><p>If administrator policies require that at least the &lt;body/&gt; (or the full content) of every message is logged automatically, and the client sets the value of the 'save' attribute to "false" (or "body").</p></li>
+      <li><p>If administrator policies require that at least the &lt;body/&gt; (or the full content) of every message is logged automatically, and the client sets the value of the 'save' attribute to 'false' (or 'body').</p></li>
     </ul>
   </section2>
   <section2 topic='Setting Modes for a Contact' anchor='pref-jid'>
@@ -285,12 +284,104 @@
   </section2>
 </section1>
 <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 &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 user will sometimes exchange messages with contacts who prefer that their conversations are not archived by either party.</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>
+  <section2 topic='OTR Negotiation' anchor='otr-nego'>
-  <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>Any client that archives messages SHOULD support <cite>Chat Session Negotiation</cite> 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>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: A client MUST NOT propose or 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 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>
+    <table caption='OTR options offered when client initiates a chat negotiation'>
-  <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 'otr' field that was previously negotiated, then the client MUST immediately terminate the Chat Session and try to negotiate a new one according to the user's new OTR preference.</p>
+      <tr>
+        <th>OTR Archive Preference</th>
+        <th>Offered options*</th>
+      </tr>
+      <tr>
+        <td>require</td>
+        <td>true***</td>
+      </tr>
+      <tr>
+        <td>prefer</td>
+        <td>true,false</td>
+      </tr>
+      <tr>
+        <td>approve</td>
+        <td>true,false</td>
+      </tr>
+      <tr>
+        <td>allow</td>
+        <td>false,true**</td>
+      </tr>
+      <tr>
+        <td>resist</td>
+        <td>false,true**</td>
+      </tr>
+      <tr>
+        <td>forbid</td>
+        <td>false**</td>
+      </tr>
+    </table>
+    <p>* In order of preference, the first value is the default</p>
+    <p>** Alternatively, the client MAY decide not to <em>initiate</em> an OTR negotiation and to save messages (until the contact initiates a negotiation).</p>
+    <p>*** If the client receives no response it MUST NOT send any messages to the contact.</p>
+    <p>Note: When negotiating a chat session the client MUST include the &lt;required/&gt; element inside the 'otr' &lt;field/&gt; element. If the client receives no 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 'otr' &lt;field/&gt; element set to 'false'.</p>
+    <table caption='OTR state selected when client responds to each of the four possible offers'>
+      <tr>
+        <th>OTR Archive Preference</th>
+        <th>true</th>
+        <th>true,false*</th>
+        <th>false,true*</th>
+        <th>false</th>
+      </tr>
+      <tr>
+        <td>require</td>
+        <td>true</td>
+        <td>true</td>
+        <td>true</td>
+        <td>fail**</td>
+      </tr>
+      <tr>
+        <td>prefer</td>
+        <td>true</td>
+        <td>true</td>
+        <td>true</td>
+        <td>false</td>
+      </tr>
+      <tr>
+        <td>approve</td>
+        <td>true</td>
+        <td>true</td>
+        <td>false</td>
+        <td>false</td>
+      </tr>
+      <tr>
+        <td>allow</td>
+        <td>true</td>
+        <td>true</td>
+        <td>false</td>
+        <td>false</td>
+      </tr>
+      <tr>
+        <td>resist</td>
+        <td>true</td>
+        <td>false</td>
+        <td>false</td>
+        <td>false</td>
+      </tr>
+      <tr>
+        <td>forbid</td>
+        <td>fail**</td>
+        <td>false</td>
+        <td>false</td>
+        <td>false</td>
+      </tr>
+    </table>
+    <p>* The first value is the default.</p>
+    <p>** The client MUST NOT send any messages to the contact.</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>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 'otr' field that was previously negotiated, then the client MUST immediately renegotiate the 'otr' 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>
+  </section2>
 </section1>
 <section1 topic='Manual Archiving' anchor='manual'>
   <section2 topic='Introduction' anchor='manual-intro'>