[Standards] LAST CALL: XEP-0136 (Message Archiving)

Peter Saint-Andre stpeter at stpeter.im
Fri Apr 11 20:10:07 UTC 2008


Alexey Melnikov wrote:
> XMPP Extensions Editor wrote:
> 
>> This message constitutes notice of a Last Call for comments on
>> XEP-0136 (Message Archiving). Abstract: This document defines
>> mechanisms and preferences for the archiving and retrieval of XMPP
>> messages. URL: http://www.xmpp.org/extensions/xep-0136.html This Last
>> Call begins today and shall end at the close of business on
>> 2008-04-18. Please consider the following questions during this Last
>> Call and send your feedback to the standards at xmpp.org discussion list:
>> 1. Is this specification needed to fill gaps in the XMPP protocol
>> stack or to clarify an existing protocol? 2. Does the specification
>> solve the problem stated in the introduction and requirements? 3. Do
>> you plan to implement this specification in your code? If not, why
>> not? 4. Do you have any security concerns related to this
>> specification? 5. Is the specification accurate and clearly written?
>> Your feedback is appreciated!
> 
> In general I think the document is in a good shape. It contains some
> useful suggestions for implementors, which I like.
> 
> Below are my detailed comments from reviewing the document:
> 
>>2.2.4 Method Element
>>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.
> 
> It took me several passes to figure out what this text is trying to say.
> Maybe it would be better to say that <pref/> element MUST include
> <method/> element for each type defined in section 2.2.4.2.

I've cleaned that up by moving the description of the <pref/> syntax to
Section 2.2 as follows:

******

2.2 Preference Syntax

Archiving preferences are encapsulated in four children of the <pref/>
element: <auto/>, <default/>, <item/>, and <method/>. These are defined
in the following sections.

In order to capture a complete set of preferences, when the server
returns the user's preferences to the client the <pref/> element:

    * MUST include an <auto/> element that specifies whether automatic
archiving is on or off.
    * MUST include a <default/> element that specifies the user's
default settings for OTR Mode and Save Mode.
    * MAY include one or more <item/> elements that specify preferences
related to particular contacts.
    * MUST include at least three <method/> elements, differentiated by
the value of the 'type' attribute (i.e., at least one <method/> element
each for "auto", "local", and "manual").

An example follows.

Example 1. Complete preferences

<iq type='result' id='pref1' to='juliet at capulet.com/chamber'>
  <pref xmlns='urn:xmpp:tmp:archive'>
    <auto save='false'/>
    <default expire='31536000' otr='concede' save='body'/>
    <item jid='romeo at montague.net' otr='require' save='false'/>
    <item expire='630720000' jid='benvolio at montague.net' otr='forbid'
save='message'/>
    <method type='auto' use='forbid'/>
    <method type='local' use='concede'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>

******

>>2.4 Setting Default Modes
> [...]
>>The server MAY be configured to return a <feature-not-implemented/>
> error in the following cases:
>>• If it does not allow the saving of full message stanza content, and
> the client set the value of the 'save'
>>attribute to 'message' or 'stream', and any of the user's connected
> resources have Automated Archiving enabled.
>>• If administrator policies require that at least the <body/> elements
> (or the full content) of every message
>>are logged automatically, and the client sets the value of the 'save'
> attribute to 'false' (or 'body').
> 
> Should the second case return something other than
> <feature-not-implemented/>?

Good point. For the second case I think it would be better to return a
<not-acceptable/> condition.

> Examples show that changes to settings by a resource are pushed out to
> the resource that caused the change. Should this be optimized out?

I think we were following the roster model (all resources receive a
push). Some say this simplifies the client (just wait for pushes). I'm
mostly agnostic on that.

>> 2.6 Setting Archiving Method Preferences
>> Example 12. Client Sets Method Preferences
>> <iq type='set' id='pref4'>
>> <pref xmlns='urn:xmpp:tmp:archive'>
>> <method type='auto' use='concede'/>
>> <method type='local' use='forbid'/>
>> <method type='manual' use='prefer'/>
>> </pref>
>> </iq> 
> 
> This section doesn't describe if it is Ok for the client to only modify
> one archiving type at a time (.e.g. if <pref> contains just one
> <method>) and if not, what should be the error response

In fact that section doesn't include any text whatsoever!

I think that (1) it's fine for the client to set only one or two method
preferences, (2) the server must not modify any unset preferences, and
(3) the push must include all the prefs, not just those set by the
client. Therefore I have the following text in Section 2.6:

******

2.6 Setting Archiving Method Preferences

The client can set one or more method preferences by sending an IQ-set
containing a <pref/> element that in turn contains one or more <method/>
elements.

Example 13. Client Sets Method Preferences

<iq type='set' id='pref4'>
  <pref xmlns='urn:xmpp:tmp:archive'>
    <method type='auto' use='concede'/>
    <method type='local' use='forbid'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>


Example 14. Server Acknowleges Change

<iq type='result' id='pref4' to='juliet at capulet.com/chamber'/>


If the client includes less than three <method/> elements, the server
MUST NOT modify the unspecified methods and MUST leave them as currently
stored on the server. However, when the server pushes the method
preferences it MUST include all of the preferences, not only those that
were set by the client.

Example 15. Server Pushes New Method Preferences

<iq type='set' id='push5' to='juliet at capulet.com/chamber'>
  <pref xmlns='urn:xmpp:tmp:archive'>
    <method type='auto' use='concede'/>
    <method type='local' use='forbid'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>

<iq type='set' id='push6' to='juliet at capulet.com/pda'>
  <pref xmlns='urn:xmpp:tmp:archive'>
    <method type='auto' use='concede'/>
    <method type='local' use='forbid'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>

******

>> 3.1 OTR Negotiation
> 
> [...]
> 
>> 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
>> Automated Archiving.
> 
> An example of how this can be done (or a reference to a section
> describing how this can be done) would be helpful here.

Hmm. AFAICT, the client needs to figure this out based on the rules in
Section 5.1. So if you log in and don't receive a warning message, you
can assume that automatic archiving is not on by default (yes, I hear
the objections already: "but message delivery is not reliable so you
might not receive the warning message!"). If you do receive a warning
message because automatic archiving is on by default, the only way to
determine if it can be turned off is to try. If you receive an error as
described in SEction 5.2 then you know that automatic archiving cannot
be turned off.

That seems rather messy. See also below.

>>The following table shows what stanza session negotiation values
>> the initating party (i.e., the "user")
> 
> typo: initiating

Fixed.

>>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).
> 
> While I think this sentence is correct, is it possible to simplify/split
> it into multiple, as it is hard to understand?

Changed to:

******

The following table shows how to instantiate the user's OTR preference
in a stanza session negotiation (SSN) offer. The various OTR preferences
map to particular values of the SSN 'logging' field, including the order
of values for that field. In particular, an SSN logging value of 'may'
means that the receiving party MAY enable message logging and an SSN
logging value of 'mustnot' means that the receiving party MUST NOT
enable message logging.

******

> In section 4.2:
> 
>> Note: The content of <message/> elements that have different thread
>> IDs SHOULD be archived in separate collections.
> 
> Is this a requirement on the client or on the server? 

I think it is a client requirement.

> If this is a
> requirement on the server, than an example demonstrating what the server
> should do if it finds a <message/> with non matching tread ID.

I suppose a server could try to enforce this rule to save the client
from its own stupidity, but I don't see that it's necessary.

>> 4.6 Groupchat Messages
>> A client MAY archive messages that it receives from Multi-User Chat
>> [8] rooms. The 'with' attribute MUST be the bare JID of the room. The
>> client MUST include a 'name' attribute for each <from/> element to
>> specify the room nickname (and, if available, bare JID) of the message
>> sender:
> 
> Before I saw the example, I misread this as "the name attribute can
> contain either nickname and/or bare JID". Please clarify that any JID is
> recorded in the 'jid' attribute.

Changed to:

******

A client MAY archive messages that it receives from Multi-User Chat [8]
rooms. The 'with' attribute MUST be the bare JID of the room. The client
MUST include a 'name' attribute for each <from/> element to specify the
room nickname of the message sender and MAY include a 'jid' attribute to
specify the full or bare JID of the sender (if available).

******

>> 5.1 Toggling Auto-Archiving
>> If server administration policies require that every message is logged
>> automatically (see Security Considerations) then:
>> • The server MUST enable automatic archiving when each stream is opened.
>> • Clients MUST NOT be allowed to disable automatic archiving.
>> • Automatic archiving MUST NOT be subject to users' Archiving
>> Preferences.
> 
> I don't think the last requirement is entirely clear. How is this
> different from the previous requirement?

I think we don't need the third bullet.

>> 5.2 Not-Implemented Responses
>> The server MUST return a <feature-not-implemented/> error in the
>> following cases:

I think these should be distinct error cases. I would suggest the
following...

>> • 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 Archiving
>> Preferences.

<feature-not-implemented/>

>> • If administrator policies require that every message is logged
>> automatically, and the client is trying to disable automatic archiving.

<not-acceptable/>

>> • If the client is trying to enable encryption, but the server does
>> not support encryption 

also <feature-not-implemented/>

>> or the user did not specify a public key and is
>> not publishing any keys using XEP-0189.

<not-allowed/>

> 
> The last listed case (user didn't specify a public key) is not
> "not-implemented". This is a distinct error condition and another error
> code should be used, if possible.

Thus:

******

5. Automatic Archiving

If server administration policies require that every message is logged
automatically (see Security Considerations) then:

    * The server MUST enable automatic archiving when each stream is opened.
    * Clients MUST NOT be allowed to disable automatic archiving.
    * If the server has not received a request from a client for its
user's archiving preferences (see Determining Preferences) within a few
seconds of authenticating the client then the server MUST send a warning
message to the client:

Example 28. Server warns user of a legacy client about compulsory archiving

<message from='capulet.com' to='juliet at capulet.com/chamber'>
  <body>WARNING: All messages that you send or
        receive will be recorded by the server.</body>
</message>


Otherwise:

    * Automatic archiving MUST default to disabled when each stream is
opened.
    * A client MAY enable or disable automatic archiving for messages
sent over its stream at any time. Note: If the client switches off all
auto-archiving then the server MUST close and archive all active
collections.
    * Once automatic archiving is switched on then the server MUST
automatically archive messages only according to the user's Archiving
Preferences.
    * Note: Both parties to an ESession (see Encrypted Session
Negotiation [10]) SHOULD 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.

The client can enable auto-archiving by setting the 'save' attribute to
"true" or "1".

Example 29. Client enables auto archiving

<iq type='set' id='auto1'>
  <auto save='true' xmlns='urn:xmpp:tmp:archive'/>
</iq>


If the server does not support the saving of full message stanza or
stream content and the user has specified the 'message' or 'stream' Save
Mode in one of its Archiving Preferences, the server MUST return a
<feature-not-implemented/> error.

Example 30. Server Does Not Support Full Message or Stream Content

<iq type='error' id='auto1'>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>


The client can enable auto-archiving with server-side encryption by
setting the 'save' attribute to "true" or "1" and setting the 'encrypt'
attribute to "true" or "1".

Example 31. Client enables auto archiving with encryption

<iq type='set' id='auto2'>
  <auto encrypt='true' save='true' xmlns='urn:xmpp:tmp:archive'/>
</iq>


If the server does not support encryption but the client attempts to
enable encryption, the server MUST return a <feature-not-implemented/>
error.

Example 32. Server Does Not Support Encrypted Messages

<iq type='error' id='auto2'>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>


If the server supports encryption but there is no public key available
for the user (e.g., as published via Public Key Publishing [11], the
server MUST return a <not-acceptable/> error.

Example 33. No Public Key Available

<iq type='error' id='auto2'>
  <error type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>


The client can disable auto-archiving by setting the 'save' attribute to
"false" or "0".

Example 34. Client disables auto archiving

<iq type='set' id='auto3'>
  <auto save='false' xmlns='urn:xmpp:tmp:archive'/>
</iq>


If service policies require that every message is logged automatically,
the server MUST return a <not-acceptable/> error.

Example 35. Automatic Archiving is Compulsory

<iq type='error' id='auto3'>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>


******

>> 6.1 Retrieving a List of Collections
>> 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 XEP-0082). The 'with' attribute MAY be
>> specified to limit the list to a single participating full JID, bare
>> JID or domain. 
> 
> So if the client specifies a domain, does it mean that the server should
> return all collections with any JID in that domain?

There is continuing controversy over that. Currently, the answer is
"yes". We've been talking about adding an 'exactmatch' attribute so that
you could specify that you want to receive only collections that match
(say) example.com instead of *@example.com. We would do that like so:

<iq type='get' id='coll1'>
  <list xmlns='urn:xmpp:tmp:archive'
        exactmatch='true'
        with='example.com'/>
</iq>

We would specify that attribute for privacy lists and multi-user chat,
too (where we do similar kinds of matching).

> I think <changed> and <removed> are only mentioned in passing before
> section 9.4 (Replication), so some explanation early on (where they
> referenced for the first time) would be helpful.

In fact there should be a <created/> element, too. Thus:

******

7. Replication

This section describes how a client can replicate an archive locally.
[13] 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). [14]

The client can "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 modified (created, changed,
or removed) in its master archive since the last update to the client's
copy of the archive.

Replication uses the <modified/> element. The list of collections that
have been modified since a given time is requested by sending a
<modified/> element to the server. The server then returns the list of
collections that have been created, changed, or removed. A collection
that has been created is specified with a <created/> element, a
collection that has been changed is specified with a <changed/> element,
and a collection that has been removed is specified with a <removed/>
element.

When requesting the list of modified collections, the client MUST embed
appropriate Result Set Management data in the <modified/> element. The
<modified/> element MUST include a 'start' attribute that specifies a
UTC datetime (see XEP-0082) that it has previously received from the
server or that it has determined locally (e.g., when synchronizing for
the first time the client SHOULD choose a suitable time for the first
page request, such as 1970-01-01T00:00:00Z).

Example 54. Requesting a page of modifications

<iq type='get' id='sync1'>
  <modified xmlns='urn:xmpp:tmp:archive'
            start='1469-07-21T01:14:47Z'
            version='3'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>50</max>
    </set>
  </modified>
</iq>


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 after the time specified by the
'start' attribute, 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 XML
character data of the <last/> element is a unique, persistent identifier
created by the server, which MUST be treated as opaque by the client.

Example 55. Receiving a page of modifications

<iq type='result' to='romeo at montague.net/orchard' id='sync1'>
  <modified xmlns='urn:xmpp:tmp:archive'>
    <created with='juliet at capulet.com/chamber'
             start='1469-07-21T02:56:15Z'
             version='0'/>
    <changed with='benvolio at capulet.com/home'
             start='1469-07-21T12:37:58Z'
             version='1'/>
    [ ... up to 47 more collections ... ]
    <removed with='balcony at house.capulet.com'
             start='1469-07-21T03:16:37Z'
             version='3'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <last>ja923ljasnvla09woei777</last>
      <count>1372</count>
    </set>
  </modified>
</iq>


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 it will not be
reflected in all the local copies of the archive.

Note: Along with its copy of the archive the client SHOULD save the most
recent <last/> identifier that it received from the server. The next
time it synchronizes with the server it SHOULD specify that identifier
when requesting the first result set page by including it as the XML
character data of the <after/> element in Result Set Management.

Example 56. Requesting the next page of modifications

<iq type='get' id='sync2'>
  <modified xmlns='urn:xmpp:tmp:archive'
            start='1469-07-21T01:14:47Z'
            version='3'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <after>ja923ljasnvla09woei777</after>
      <max>50</max>
    </set>
  </modified>
</iq>


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 Retrieving a Collection) and
add it to its local copy of the archive (deleting any older version of
the same collection that it may already have).

******

And (in the schema):

******

  <xs:element name='modified'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='changed' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='created' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='removed' minOccurs='0' maxOccurs='unbounded'/>
        <xs:any processContents='lax' namespace='##other' minOccurs='0'
maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='start' type='xs:dateTime' use='required'/>
    </xs:complexType>
  </xs:element>

******

> Regards,
> Alexey

Thanks for the review!

Peter

-- 
Peter Saint-Andre
https://stpeter.im/


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 7338 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://mail.jabber.org/pipermail/standards/attachments/20080411/34422a2e/attachment.bin>


More information about the Standards mailing list