From a7e5ecb79de0463482031dcaa8b3cdf524ebc157 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Tue, 11 Jun 2013 14:28:52 -0600 Subject: [PATCH] 0.2 --- xep-0313.xml | 256 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 183 insertions(+), 73 deletions(-) diff --git a/xep-0313.xml b/xep-0313.xml index da159581..3de80921 100644 --- a/xep-0313.xml +++ b/xep-0313.xml @@ -7,7 +7,7 @@
Message Archive Management - This document defines a protocol to query and control and archive of messages stored on a server. + This document defines a protocol to query and control an archive of messages stored on a server. &LEGALNOTICE; 0313 Experimental @@ -31,6 +31,12 @@ me@matthewwild.co.uk me@matthewwild.co.uk + + 0.2 + 2013-05-31 + mw +

Document the ability to page through results by message UIDs, define the <archived/> element, and various minor improvements.

 + 0.1 2012-04-18 @@ -46,7 +52,7 @@ multiple clients.

- +

As this extension aims to make things easy for client developers, some research was made into the way clients handle history today. The resulting protocol was designed to allow for the following primary usage scenarios:

@@ -86,19 +92,19 @@ - +

An archive is a collection of messages stored on a user's server. Messages sent to or from a user's account are generally automatically added to a user's archive by the server. The collection is ordered chronologically by the time each message was sent/received.

Exactly which messages a server archives is left up to implementation and deployment policy, but as a minimum servers SHOULD NOT archive messages that do not have a <body/> child tag.

-

At a minimum, a stored message consists of the following pieces of information:

+

A stored message consists of at least the following pieces of information:

  • A timestamp of when the message was sent (for an outgoing message) or received (for an incoming message).
  • The remote JID that the stanza is to (for an outgoing message) or from (for an incoming message).
    • -
  • A server-assigned UID that MUST be unique within the archive.
    • +
  • A server-assigned UID that MUST be unpredictable and unique within the archive.
  • The message stanza itself. The entire original stanza SHOULD be stored, but at a minimum only the <body/> tag MUST be preserved (ie. the server might, at its discretion, strip certain extensions from messages before storage).
    • @@ -106,12 +112,34 @@

    A server MAY impose limits on the size of a user's archive. For example a server might begin to discard old messages once the archive reaches a certain size, or only keep messages until they reach a certain age. The UIDs of deleted messages MUST NOT be reused for new messages.

    -

    Finally, there is no restriction on where an archive may be hosted. Servers that archive - messages on behalf of local users SHOULD expose archives to the user on their bare JID, while a +

    There is no restriction on where an archive may be hosted. Servers that archive + messages on behalf of local users SHOULD expose archives to the user on the user's bare JID, while a MUC service might allow MAM queries to be sent to the room's bare JID.

    + +

    When an incoming message is archived, the server SHOULD add an <archived/> element to the message, + which informs the client of where the message is stored. The element MUST contain a 'by' attribute + giving the JID of the archive (i.e. where the client would send queries to) and an 'id' attribute + giving the message's UID within the archive.

    +

    Servers MUST NOT include the <archived/> element in messages addressed to JIDs that do not + have permission to access the archive, such as a user's outgoing messages to their contacts.

    + + Call me but love, and I'll be new baptized; Henceforth I never will be Romeo. + + +]]> +

    Naturally a message might be archived in multiple places, and include multiple <archived/> + elements with different 'by' attributes. Clients MUST be prepared to handle this situation, and + MUST ignore additional elements with 'by' attributes from entities they don't recognise, or that have + not been determined to have MAM support (see Determining support). Archiving + servers supporting MAM MUST strip any existing <archived/> element with a 'by' attribute equal to + an archive that they provide.

    +     - +

    A client is able to query the archive for all messages within a certain timespan, optionally restricting results to those to/from a particular JID. To allow limiting the results or paging through them a client may use &xep0059;, which MUST be supported by servers.

    @@ -131,11 +159,11 @@

    To ensure that the client knows when the results are complete, the server MUST delay the result <iq/> until after it has pushed all the results to the client. An optional 'queryid' attribute allows the client to match results to a certain query.

    - -

    The query can contain any combination of three filtering tags - <with/>, <start/> - and <end/>. By default all messages match a query, the filters are used to request a subset - of the archived messages.

    - + +

    By default all messages match a query, and filters are used to request a subset of the archived + messages. The query can contain any combination of three filtering tags - <with/>, <start/> + and <end/>. However each of these tags MUST NOT be specified more than once in a query.

    +

    If a <with/> element is present in the <query/>, it contains a JID against which to match messages. The server MUST only return messages if they match the supplied JID.

    If <with/> is omitted, the server SHOULD return all messages in the selected timespan, @@ -143,16 +171,16 @@ - juliet@capulet.com + juliet@capulet.lit ]]>

    If (and only if) the supplied JID is a bare JID (i.e. no resource is present), then the server SHOULD return messages if their bare to/from address would match it. For example, - if the client supplies with='juliet@capulet.com' this filter would also match messages to - or from "juliet@capulet.com/balcony" and "juliet@capulet.com/chamber".

    + if the client supplies a 'with' of "juliet@capulet.lit" the query would also match messages to + or from "juliet@capulet.lit/balcony" and "juliet@capulet.lit/chamber".

     - +

    The <start/> and <end/> elements, if provided, MUST contain timestamps formatted according to the DateTime profile defined in &xep0082;

    The <start/> element is used to filter out messages before a certain date/time. @@ -181,7 +209,7 @@ ]]> - +

    Finally, in order for the client or server to limit the number of results transmitted at a time a server MUST support &xep0059; and SHOULD support the paging mechanism defined therein. A client MAY include a <set/> element in its query.

    @@ -192,73 +220,120 @@ 2010-08-07T00:00:00Z - 10 + 10 ]]>

    To conserve resources, a server MAY place a reasonable limit on how many stanzas may be pushed to a client in one request. If a query returns a number of stanzas greater than this - limit and either the client did not specify a limit using RSM then the server should return - a policy-violation error to the client. If the query did include a <set/> element then - the server SHOULD simply return its limited results and adjust the <before/> and <after/> - in its reply to allow the client to page through them by timestamp.

    - - Too many results + Too many results ]]> + If the query did include a <set/> element then the server SHOULD simply return + its limited results and in its <iq> result adjust the <before/> and + <after/> to reflect the timestamps of the first and last message it is returning + to the client. This allows clients to page through results by timestamp.

    +

    The result response MUST also include an RSM <set/> element indicating the + UID of the first and last message of the (possibly limited) result set. This + allows clients to accurately page through messages. +

    + + + 2010-06-07T00:00:00Z + 2010-07-07T05:03:27Z + + 28482-98726-73623 + 09af3-cc343-b409f + 20 + + + + ]]> +

    The <first> and <last> elements specify the UID of the first and last returned + results (not of the results that matched the query).

    + +

    The RSM <count> element and the 'index' attribute on the RSM <first> element are optional, + but servers SHOULD include them. Please refer to the RSM specification for more information + surrounding their meaning and use.

    +     + +

    Having previously made a query that returned results limited by the server (as described above), a client + can re-send the same request and receive the next 'page' of results. It does this by including a <set> + element with its request, containing an <after/> with the UID of the last message it received + from the previous query.

    + + + 2010-08-07T00:00:00Z + + 10 + 09af3-cc343-b409f + + + + ]]> +

    Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.

         - +

    The server responds to the archive query by transmitting to the client all the messages that match the criteria the client requested. The results are sent as individual stanzas, with the original message encapsulated in a <forwarded/> element as described in &xep0297;.

    The result messages MUST contain a <result/> element with an 'id' attribute that gives - the current message's UID. If the client gave a 'queryid' attribute in its initial query, the - server MUST also include that in this result element.

    -

    The <forwarded/> element SHOULD contain the original message as it was received, and - SHOULD also contain a <delay/> element qualified by the 'urn:xmpp:delay' namespace - specified in &xep0203;. The value of the 'stamp' attribute MUST be the time the message was - originally received by the forwarding entity. + the current message's archive UID. If the client gave a 'queryid' attribute in its initial + query, the server MUST also include that in this result element. +

    +

    The <result/> element contains a <forwarded/> element which SHOULD contain the + original message as it was received, and SHOULD also contain a <delay/> element + qualified by the 'urn:xmpp:delay' namespace specified in &xep0203;. The value of the 'stamp' + attribute MUST be the time the message was originally received by the forwarding entity.

    - - - - - Call me but love, and I'll be new baptized; Henceforth I never will be Romeo. - - + + + + + + Call me but love, and I'll be new baptized; Henceforth I never will be Romeo. + + + - - - - - - What man art thou that thus bescreen'd in night so stumblest on my counsel? - - + + + + + + What man art thou that thus bescreen'd in night so stumblest on my counsel? + + + ]]>     - +

    Depending on implementation and deployment policies, a server MAY allow the user to have control over the server's archiving behaviour. This specification defines a basic protocol for this, and also allows a server to offer more advanced configuration to a user.

    - +

    If the server supports and allows configuration then it SHOULD implement the protocol defined in this section. This allows the user to configure the following preferences:

      @@ -268,12 +343,12 @@
    - + - romeo@montague.net + romeo@montague.lit - montague@montague.net + montague@montague.lit @@ -282,17 +357,17 @@ MAY be different to the preferences sent by the client):

    - + - romeo@montague.net + romeo@montague.lit - montague@montague.net + montague@montague.lit ]]> - +

    If a JID is in neither the 'always archive' nor the 'never archive' list then whether it is archived depends on this setting, the default.

    @@ -303,7 +378,7 @@
  • 'roster' - messages are archived only if the contact's bare JID is in the user's roster.
- +

The <prefs/> element MAY contain an <always/> child element. If present, it contains a list of <jid/> elements, each containing a single JID. The server SHOULD archive any messages to/from this JID (see 'JID matching'). @@ -312,7 +387,7 @@ empty list.

- +

The <prefs/> element MAY contain an <never/> child element. If present, it contains a list of <jid/> elements, each containing a single JID. The server SHOULD NOT archive any messages to/from this JID (see 'JID matching'). @@ -322,7 +397,7 @@

- +

In addition to this protocol, a server MAY offer more advanced configuration to the user through &xep0050;. Such an interface might, for example, allow the user to configure what types of messages to store, or set a limit on how long messages should remain in the @@ -330,8 +405,8 @@

If supported, such a configuration command SHOULD be presented on the well-defined command node of "urn:xmpp:mam#configure".

 - - + +

When comparing the message target JID against the user's roster (ie. when the user has set default='roster') the comparison MUST use the bare target JID (that is, stripped of any resource). @@ -346,28 +421,30 @@ - +

For outgoing messages, the server MUST use the value of the 'to' attribute as the target JID.

- +

For incoming messages, the server MUST use the value of the 'from' attribute as the target JID.

- -

If a server or other entity hosts archives and supports MAM queries, it MUST advertise that fact - by including the feature "urn:xmpp:mam:tmp" in response to a &xep0030; request:

+ +

If a server or other entity hosts archives and supports MAM queries, it MUST advertise + the 'urn:xmpp:mam:tmp' feature in response to &xep0030; requests made to archiving JIDs + (i.e. JIDs hosting an archive, such as users' bare JIDs): +

+ ]]> + ... @@ -377,4 +454,37 @@ ]]> + + + Clients and servers may receive messages containing <archived/> elements + that have not been verified. If proper handling of received <archived/> + elements is not followed, an attacker could disrupt a client's cache of + archived message UIDs, and prevent the client from fetching future messages + correctly (by using an 'id' that doesn't exist in the archive). + + +

An archive generally consists of private conversations, and so + a server MUST adequately protect an archive from unauthorized third-party + access. For example authorized parties for a user's archive would include + the just the user, and a MUC archive for a private room might be restricted + to room members. An implementation MAY choose to allow access to any archive + by server administrators.

+

A server SHOULD provide a mechanism for a user to disable archiving of + messages with all or specific contacts, such as via the configuration + protocol described in this document. This allows the user to prevent the + archiving of potentially sensitive messages in the first place.

+

A server MAY automatically prevent certain sensitive messages from being + archived. How such messages are identified is beyond the scope of this + specification, but technologies such as &xep0258; may be used, for example.

+ + + + + + + +

Many thanks to Kevin Smith, Dave Cridland, Kim Alvefur, Yann Leboulanger and Lance Stout + for their input and feedback on this specification.

+ +