JEP-0136: Message Archiving

Justin Karneges

Email: justin@affinix.com
JID: justin@andbit.net

Ian Paterson

Email: ian.paterson@clientside.co.uk
JID: ian@zoofy.com

Jon Perlow

Email: jonp@google.com
JID: jonp@google.com

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

1. Introduction

2. Determining Server Support

3. Archiving Preferences

3.1. Introducton

3.2. Determining Modes

3.3. Setting Default Modes

3.4. Setting Modes for a Contact

4. Off The Record

5. Manual Archiving

5.1. Introduction

5.2. Collections

5.3. Uploading Messages to a Collection

5.4. Groupchat Messages

5.5. Encryption

5.6. Updating Collection Attributes

6. Automated Archiving

7. Archive Management

7.1. Retrieving a List of Collections

7.2. Retrieving a Collection

7.3. Removing a Collection

8. Replication

9. File Format

10. Implementation Notes

10.1. Time Synchronization

10.2. Bandwidth Considerations

10.3. Storage Considerations

11. Security Considerations

11.1. Plain Text Subject

11.2. Store Headers

12. IANA Considerations

13. Jabber Registrar Considerations

13.1. Protocol Namespaces

13.2. Service Discovery Features

13.3. Cryptography Scheme Names

13.3.1. RSA-KEM-KDF2-SHA256

13.3.2. DEM1-SC2-KDF2-SHA256

14. XML Schemas

Notes

Revision History

    
<iq type='get' to='montague.net'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

    
<iq type='result'
    from='montague.net'
    to='romeo@montague.net/orchard'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
    ...
    <feature var='http://jabber.org/protocol/archive#auto'/>
    <feature var='http://jabber.org/protocol/archive#encrypt'/>
    <feature var='http://jabber.org/protocol/archive#manage'/>
    <feature var='http://jabber.org/protocol/archive#manual'/>
    <feature var='http://jabber.org/protocol/archive#pref'/>
    ...
  </query>
</iq>

3.1 Introducton

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.

Some users may also prefer that the messages they exchange with contacts are "Off The Record" (OTR). A client SHOULD save its user's default and contact-specific OTR preferences (or "OTR Modes") to its own server.

Whichever archiving method a client uses (e.g., local archiving, or automatic or manual archiving to a server), it SHOULD adhere to its user's archiving preferences.

This section addresses the following use cases:

1. A client determines its user's current default Save Mode and OTR Mode, and the Modes for particular contacts.
2. A client sets the default Save Mode and OTR Mode.
3. A client sets the Save Mode and OTR Mode for a particular contact.

3.2 Determining Modes

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends this query to its server:

Example 3. Client Requests Modes

<iq type='get' id='save1' from='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'/>
</iq>
    

The server responds with the default Save Mode and OTR Mode (<default/> element) and any Save Modes and OTR Modes for specific contacts (<item/> elements).

Each child 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 <body/> elements) or 'all' (the client SHOULD save the full XML content of each <message/> element).

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.

Note: When archiving locally a client MAY save the full XML content of each <message/> element even if the Save Mode is 'body'.

Each child element in the response MUST include an 'otr' attribute, whose value MAY be 'deny' (if Off The Record is required by the contact the client MUST send no messages), 'allow' (the client MAY save messages unless the contact requests OTR), 'try' (the client MUST try to negotiate OTR with the contact) or 'require' (the client MUST send no messages unless the contact explicitly agrees to OTR).

Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'.

Example 4. Server Returns Modes

<iq type='result' id='save1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='body' otr='allow'/>
    <item jid='romeo@montague.net' save='false' otr='require'/>
    <item jid='benvolio@montague.net' save='all' otr='deny'/>
  </pref>
</iq>
    

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".

Example 5. Server Returns Service Default Modes

<iq type='result' id='save1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='allow' unset='true'/>
  </pref>
</iq>
    

Once it has received a request for archiving preferences from the client, the server MUST send any subsequent changes to any of the user's archiving preferences to the client until the stream is closed (see below).

3.3 Setting Default Modes

A client may set the default Modes:

Example 6. Client Sets Default Modes

<iq type='set' id='save2' from='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='try'/>
  </pref>
</iq>
    

If the server can process the request, it acknowledges the change:

Example 7. Server Acknowledges Change

<iq type='result' id='save2' to='juliet@capulet.com/chamber'/>
    

The server then MUST inform all of the user's connected resources that have previously requested the user's archiving preferences:

Example 8. Server Pushes New Modes

<iq type='set' id='savepush1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='try'/>
  </pref>
</iq>

<iq type='set' id='savepush2' to='juliet@capulet.com/pda'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='try'/>
  </pref>
</iq>
    

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 "all", and any of the user's connected resources have Automated Archiving enabled.

• If administrator policies require that at least the <body/> (or the full content) of every message is logged automatically, and the client sets the value of the 'save' attribute to "false" (or "body").

Note: More error cases to follow.

3.4 Setting Modes for a Contact

A client may use a similar protocol to set the Modes for a particular contact or domain of contacts (bare JID, full JID or domain). Note: It is STRONGLY RECOMMENDED for the value of the 'jid' attribute to be a bare JID (<node@domain.tld>).

Example 9. Client Sets Modes for a Contact

<iq type='set' item='save3' from='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <item jid='romeo@montague.net' save='body' otr='allow'/>
  </pref>
</iq>
    

Example 10. Server Acknowleges Change

<iq type='result' id='save3' to='juliet@capulet.com/chamber'/>
    

Example 11. Server Pushes New Modes

<iq type='set' id='savepush3' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <item jid='romeo@montague.net' save='body' otr='allow'/>
  </pref>
</iq>

<iq type='set' id='savepush4' to='juliet@capulet.com/pda'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <item jid='romeo@montague.net' save='body' otr='allow'/>
  </pref>
</iq>
    

The same error cases apply as when Setting Default Modes.

5.1 Introduction

While automated archiving is easy for the client and server to implement, there are many contexts in which automated archiving is required. For examples, when:

• Messages are encrypted using evanscent keys, as in Encrypted Sessions [4]
• A client's own server does not support automated archiving but it (or another server) does support manual archiving
• A server does not support encryption of auto-archived collections
• A client wants to maintain a unified archive for messages that were transmitted both in and out-of-band (e.g. SMS or email)
• A client wants to append private notes to a conversation

Therefore, often a client will want to send or receive a sequence of messages, optionally add private notes to the sequence, optionally encrypt the sequence, and then ask the server to store it.

Such messages and notes SHOULD be stored on the server in the form of a "collection", i.e., a set of messages to/from the same user that are received near each other in time or as part of the same conversation thread. A collection is intended to mimic the natural flow of human conversations, which in instant messaging (IM) systems tend to occur in bursts (e.g., a five-minute conversation one day, followed by a ten-minute conversation the next).

5.2 Collections

The client uniquely specifies a collection using a pair of attributes:

• 'with' (the full JID with which the messages were exchanged)
• 'start' (the UTC start time of the conversation thread, which MUST be UTC and adhere to the DateTime format specified in Jabber Date and Time Profiles [5])

A friendly name for the collection MAY be specified with a 'subject' attribute. Note the Security Considerations regarding the subject attribute.

Each collection MAY contain <note/>, <to/> or <from/> elements (or <crypt/> elements - see Encryption).

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 Jabber Date and Time Profiles).

The content of each individual message MUST be encapsulated in a <to/> or <from/> element. The time in 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. The content of each <to/> or <from/> element SHOULD include a <body/> element.

Note: Other elements MAY be included, but they are NOT RECOMMENDED. To conserve bandwidth and storage space [6], elements qualified by the 'http://jabber.org/protocol/xhtml-im' namespace SHOULD NOT be included. <thread/> elements and elements qualified by the 'jabber:x:delay', 'jabber:x:event' and 'http://jabber.org/protocol/chatstates' namespaces MUST NOT be included. The server MAY be configured to return a <feature-not-implemented/> error if any <to/> or <from/> element contains anything other than a single <body/> element.

5.3 Uploading Messages to a Collection

The collection of messages and notes to be uploaded are encapsulated in the <store/> element.

Example 12. Storing messages in a collection

<iq type='set' to='montague.net' id='up1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks!'>
    <from secs='0'><body>Art thou not Romeo, and a Montague?</body></from>
    <to secs='11'><body>Neither, fair saint, if either thee dislike.</body></to>
    <from secs='14'><body>How cam'st thou hither, tell me, and wherefore?</body></from>
    <note utc='1469-07-21T03:04:35Z'>I think she might fancy me.</note>
  </store>
</iq>
    

If the collection does not exist then the server MUST create a new collection. If the collection already exists then the server MUST append the messages to the existing collection.

Note: Clients MUST take care to append each sequence of messages to the collection before the sequence becomes so large that uploading it may violate common rate limiting restrictions (in Jabber systems, often called "karma").

Example 13. Successful reply

<iq type='result' to='romeo@montague.net/orchard' id='up1'/>
    

If the server cannot service a store request because the collection is too large then it MUST return a <not-acceptable/> error:

Example 14. Unsuccessful reply

<iq type='error' to='romeo@montague.net/orchard'>
  <error code='406' type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

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 Jabber Date and Time Profiles) instead of a 'secs' attribute:

Example 15. Storing offline messages in a collection

<iq type='set' to='montague.net' id='up2'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks!'>
    <from utc='1469-07-21T00:32:29Z'><body>Art thou not Romeo, and a Montague?</body></from>
    <to secs='11'><body>Neither, fair saint, if either thee dislike.</body></to>
    <from secs='14'><body>How cam'st thou hither, tell me, and wherefore?</body></from>
  </store>
</iq>
    

5.4 Groupchat Messages

A client MAY archive messages that it receives from Multi-User Chat [7] 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:

Example 16. Storing groupchat messages in a collection

<iq type='set' to='montague.net' id='up3'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='balcony@house.capulet.com'
         start='1469-07-21T03:16:37Z'>
    <from secs='0' name='benvolio'><body>She will indite him to some supper.</body></from>
    <from secs='5' name='mercutio'><body>A bawd, a bawd, a bawd! So ho!</body></from>
    <from secs='11' name='romeo'><body>What hast thou found?</body></from>
  </store>
</iq>
    

5.5 Encryption

The examples above are not encrypted for clarity. However, clients SHOULD encrypt manually-archived collections, and the encryption of auto-archived collections (see Automated Archiving) is strongly RECOMMENDED.

Before uploading a sequence of messages to a collection, the client SHOULD encrypt and encapsulate the joined sequence of <to/>, <from/> and <note/> elements, base64 encode the resulting sequence of bytes, and wrap it inside a <crypt/> element. If a randomly generated unique public label was used to encapsulate the encrypted messages then the 'label' attribute of <crypt/> element MUST be set to that base64 encoded label.

Note: Entities MUST support the SHA-256 hash [8] and the DEM1 (with SC2/SHA-256) data encapsulation mechanism (see ISO 18033-2 at http://www.shoup.net/iso/std6.pdf, or ANSI-X9.44). Entities MAY support other hashes and algorithms (see Jabber Registrar Considerations). [9]

Clients MAY add one or more <crypt/> elements to a collection using exactly the same method as for <to/>, <from/> and <note/> elements (see Uploading Messages to a Collection). Note: a collection that contains <crypt/> elements MUST NOT contain <to/> or <from/> or <note/> elements.

When an encrypted collection is created (or when a <crypt/> element is added to an empty non-encrypted collection) four extra attributes MUST be specified for the <store/> element:

• 'dataalg' - the name of the encryption/encapsulation algorithm (see Jabber Registrar Considerations) used (with the messages encryption key - see below) to generate the content of all the <crypt/> elements in the collection
• 'key' - the encrypted (see below) and base64 encoded version of the messages encryption key used (with the messages encryption algorithm above) to generate the content of all the <crypt/> elements in the collection
• 'keyalg' - the name of the encryption/encapsulation algorithm (see Jabber Registrar Considerations) used to transform the messages encryption key into the 'key' attribute (see above)
• 'master' - the identity (fingerprint) of the private key used (with the key encryption algorithm above) to transform the messages encryption key into the 'key' attribute (see above) [10]

Note: Clients MUST support the SHA-256 hash and the RSA-KEM (with KDF2/SHA-256) key encapsulation scheme (see ISO 18033-2 at http://www.shoup.net/iso/std6.pdf, or ANSI-X9.44). [11] The client MAY support other hashes and algorithms (see Jabber Registrar Considerations). [12]

Example 17. Storing encrypted messages in a new collection

<iq type='set' to='montague.net' id='crypt1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks!'
         dataalg='DEM1-SC2-KDF2-SHA256'
         key='bfXv33i+Ybqypa4ETLyorGkVl73v67SMvzX41MPRKA5cOp9wGDMgd8SirwIDAQAB'
         keyalg='RSA-KEM-KDF2-SHA256'
         master='acc3594e844c77696f7a7ba9367ae324b6b958ad'>
    <crypt label='VROLURBVEFDb3JwU0dDL'>E5Qbvfa2gI5lBZMAHryv4g+OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ</crypt>
  </store>
</iq>
    

5.6 Updating Collection Attributes

If the client specifies a new value for the 'subject' attribute of any existing collection, or new values for the 'key', 'keyalg' or 'master' attributes of an existing encrypted collection then the server MUST update the existing values. This enables a client to change the subject of a collection, to remove any dependencies on an obsolete private key, or to change the decryption key encryption algorithm.

Note: The client MUST NOT specify new values for the 'dataalg', 'with' or 'start' attributes. The only way to change these values is to delete the collection (see Removing a Collection) and then create a new one.

Example 18. Changing the private key for a collection

<iq type='set' to='montague.net' id='private1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         key='IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2Yg'
         master='3fb37d8e817c673dfa60637351926d564ce65629'/>
</iq>
    

Example 19. Changing the subject of an encrypted collection while appending messages

<iq type='set' to='montague.net' id='subject1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks twice!'
    <crypt label='TWFuIGlzIGRpc3Rpbmd1'>dGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0aGUgY29udGlu</crypt>
  </store>
</iq>
    

<iq type='set' id='auto1'>
  <auto save='true' xmlns='http://jabber.org/protocol/archive'/>
</iq>
  

<iq type='set' id='auto2'>
  <auto save='true'
        secret='dWVkIGFuZCBpbmRlZmF0aWdhYmxl'
        dataalg='DEM1-SC2-KDF2-SHA256'
        key='bfXv33i+Ybqypa4ETLyorGkVl73v67SMvzX41MPRKA5cOp9wGDMgd8SirwIDAQAB'
        keyalg='RSA-KEM-KDF2-SHA256'
        master='acc3594e844c77696f7a7ba9367ae324b6b958ad'
        xmlns='http://jabber.org/protocol/archive'/>
</iq>
  

7.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 Jabber Date and Time Profiles). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.

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.

The client SHOULD use Result Set Management 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.

Example 22. Requesting the first page of a list with same JID

<iq type='get' to='montague.net' id='juliet1'>
  <list xmlns='http://jabber.org/protocol/archive'
        with='juliet@capulet.com'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>30</max>
    </set>
  </list>
</iq>
    

Example 23. Requesting the first page of a list with same JID between two times

<iq type='get' to='montague.net' id='period1'>
  <list xmlns='http://jabber.org/protocol/archive'
        with='juliet@capulet.com'
        start='1469-07-21T02:00:00Z'
        end='1479-07-21T04:00:00Z'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>30</max>
    </set>
  </list>
</iq>
    

Example 24. Requesting the first page of a list after a time

<iq type='get' to='montague.net' id='list1'>
  <list xmlns='http://jabber.org/protocol/archive'
        start='1469-07-21T02:00:00Z'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>30</max>
    </set>
  </list>
</iq>
    

The server MUST list the collections (empty <store/> elements including all attributes) in chronological order when responding to any request:

Example 25. Receiving the first page of a list

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='list1'>
  <list xmlns='http://jabber.org/protocol/archive'>
    <store with='juliet@capulet.com/chamber'
           start='1469-07-21T02:56:15Z'
           subject='She speaks!'
           dataalg='DEM1-SC2-KDF2-SHA256'
           key='bfXv33i+Ybqypa4ETLyorGkVl73v67SMvzX41MPRKA5cOp9wGDMgd8SirwIDAQAB'
           keyalg='RSA-KEM-KDF2-SHA256'
           master='acc3594e844c77696f7a7ba9367ae324b6b958ad'/>
    .
    [28 more collections]
    .
    <store with='balcony@house.capulet.com'
           start='1469-07-21T03:16:37Z'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>1469-07-21T02:56:15Zjuliet@capulet.com</first>
      <last>1469-07-21T03:16:37Zbalcony@house.capulet.com</last>
      <count>1372</count>
    </set>
  </list>
</iq>
    

Note: In accordance with Result Set Management, 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.

If no collections correspond to the request the server MUST return an empty <list/> element:

Example 26. Receiving an empty list

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='list1'>
  <list xmlns='http://jabber.org/protocol/archive'/>
</iq>
    

Example 27. Requesting the second page of a list

<iq type='get' to='montague.net' id='list2'>
  <list xmlns='http://jabber.org/protocol/archive'
        start='1469-07-21T02:00:00Z'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>30</max>
      <after>1469-07-21T03:16:37Zbalcony@house.capulet.com</after>
    </set>
  </list>
</iq>
    

Refer to Result Set Management to learn more about the various ways that the pages of the list may be accessed.

The 'master' attribute MAY be included to limit the list to encrypted collections whose messages decryption key was encrypted with the specified private key. This feature enables a client to find any collections that depend on an obsolete private key:

Example 28. Requesting the first page of a list with a private key ID

<iq type='get' to='montague.net' id='master1'>
  <list xmlns='http://jabber.org/protocol/archive'
        master='acc3594e844c77696f7a7ba9367ae324b6b958ad'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>30</max>
    </set>
  </list>
</iq>
    

Example 29. Receiving the first page of a list with a private key ID

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='master1'>
  <list xmlns='http://jabber.org/protocol/archive'>
    <store xmlns='http://jabber.org/protocol/archive'
           with='juliet@capulet.com/chamber'
           start='1469-07-21T02:56:15Z'
           subject='She speaks!'
           dataalg='DEM1-SC2-KDF2-SHA256'
           key='bfXv33i+Ybqypa4ETLyorGkVl73v67SMvzX41MPRKA5cOp9wGDMgd8SirwIDAQAB'
           keyalg='RSA-KEM-KDF2-SHA256'
           master='acc3594e844c77696f7a7ba9367ae324b6b958ad'/>
    .
    [29 more encrypted collections]
    .
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>1469-07-21T02:56:15Zjuliet@capulet.com</first>
      <last>1469-07-21T03:16:37Zbalcony@house.capulet.com</last>
      <count>142</count>
    </set>
  </list>
</iq>
    

7.2 Retrieving a Collection

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 Jabber Date and Time Profiles). Both attributes MUST be included to uniquely identify a collection:

The client SHOULD use Result Set Management 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.

Example 30. Requesting the first page of a collection

<iq type='get' to='montague.net' id='page1'>
  <retrieve xmlns='http://jabber.org/protocol/archive'
            with='juliet@capulet.com/chamber'
            start='1469-07-21T02:56:15Z'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>100</max>
    </set>
  </retrieve>
</iq>
    

Example 31. Receiving the first page of a collection

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='page1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks!'>
    <from secs='0'><body>Art thou not Romeo, and a Montague?</body></from>
    <to secs='11'><body>Neither, fair saint, if either thee dislike.</body></to>
    .
    [98 more messages]
    .
    <from secs='14'><body>How cam'st thou hither, tell me, and wherefore?</body></from>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>0</first>
      <last>99</last>
      <count>217</count>
    </set>
  </store>
</iq>
    

Note: In accordance with Result Set Management, 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.

If the specified collection does not exist then the server MUST return an <item-not-found/> error:

Example 32. Unsuccessful reply

<iq type='error' to='romeo@montague.net/orchard' from='montague.net' id='page1'>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the requested collection is empty the server MUST return an empty <store/> element:

Example 33. Receiving an empty collection

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='page1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-21T02:56:15Z'
         subject='She speaks!'/>
</iq>
    

Example 34. Requesting the second page of a collection

<iq type='get' to='montague.net' id='page2'>
  <retrieve xmlns='http://jabber.org/protocol/archive'
            with='juliet@capulet.com/chamber'
            start='1469-07-21T02:56:15Z'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>100</max>
      <after>99</after>
    </set>
  </retrieve>
</iq>
    

Refer to Result Set Management to learn more about the various ways that the pages of the collection may be accessed.

7.3 Removing a Collection

To request the removal of a single collection the client sends an empty <remove/> element. The 'with' (full JID) and 'start' attributes MUST be included to uniquely identify the collection.

Example 35. Removing a single collection

<iq type='set' to='montague.net'>
  <remove xmlns='http://jabber.org/protocol/archive'
          with='juliet@capulet.com/chamber'
          start='1469-07-21T02:56:15Z'/>
</iq>
    

The client may remove several collections at once. The 'start' and 'end' elements MAY be specified to indicate a date range. The 'with' attribute MAY be a full JID, bare JID or domain.

Example 36. Removing all collections with a specified bare JID between two times

<iq type='set' to='montague.net'>
  <remove xmlns='http://jabber.org/protocol/archive'
          with='juliet@capulet.com'
          start='1469-07-21T02:00:00Z'
          end='1469-07-21T04:00:00Z'/>
</iq>
    

If the 'with' attribute is omitted then collections with any JID are removed.

If the end date is in the future then then all collections after the start date are removed.

Example 37. Removing all collections after a date

<iq type='set' to='montague.net'>
  <remove xmlns='http://jabber.org/protocol/archive'
          start='1469-07-21T02:00:00Z'
          end='2038-01-01T00:00:00Z'/>
</iq>
    

If the start date is before all the collections in the archive then all collections prior to the end date are removed.

Example 38. Removing all collections before a date

<iq type='set' to='montague.net'>
  <remove xmlns='http://jabber.org/protocol/archive'
          start='0000-01-01T00:00:00Z'
          end='1469-07-21T04:00:00Z'/>
</iq>
    

Example 39. Removing all collections

<iq type='set' to='montague.net'>
  <remove xmlns='http://jabber.org/protocol/archive'/>
</iq>
    

If the specified collection (or collections) do not exist then the server MUST return an <item-not-found/> error:

Example 40. Unsuccessful reply

<iq type='error' to='romeo@montague.net/orchard'>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

    
<iq type='get' to='montague.net' id='sync1'>
  <modified xmlns='http://jabber.org/protocol/archive'>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>50</max>
      <after>1469-07-21T01:14:47Z</after>
    </set>
  </modified>
</iq>
  

<iq type='result' to='romeo@montague.net/orchard' from='montague.net' id='sync1'>
  <modified xmlns='http://jabber.org/protocol/archive'>
    <changed with='juliet@capulet.com/chamber'
           start='1469-07-21T02:56:15Z'/>
    .
    [up to 48 more collections]
    .
    <removed with='balcony@house.capulet.com'
             start='1469-07-21T03:16:37Z'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <last>1469-07-21T04:22:39Z</last>
      <count>1372</count>
    </set>
  </modified>
</iq>
  

<?xml version='1.0'?>
<archive xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com'>
  <store start='1469-07-21T02:56:15Z' subject='She speaks!'>
    <from secs='0'><body>Art thou not Romeo, and a Montague?</body></from>
    <to secs='11'><body>Neither, fair saint, if either thee dislike.</body></to>
    <from secs='14'><body>How cam'st thou hither, tell me, and wherefore?</body></from>
  </store>
</archive>
  

10.1 Time Synchronization

When creating a new collection, it is RECOMMENDED that the client synchronizes the collection start time that it sends to the server with server time. This is important since the user may subsequently retrieve the stored collection using client machines whose UTC clocks are not synchronized with the client machine that stored the collection. (i.e. Either or both of the clients' UTC clocks may be wrong.) The client can achieve this synchronization with server time by using Entity Time [17] to estimate the difference between the server and client UTC clocks.

When retrieving collections, it is RECOMMENDED that the client adjusts the start times of the collections it receives from server to be synchronized with the clock of the client machine.

10.2 Bandwidth Considerations

When uploading messages using manual archiving, a client SHOULD NOT store one message at a time on the server since this increases both bandwidth consumption and the total number of transactions. It is instead RECOMMENDED that clients store messages only when the conversation thread appears to be terminated, e.g. when the user closes the chat window. If the user reopens the window and the thread continues then the client should append the new messages to the collection when the user closes the window again.

10.3 Storage Considerations

Server implementations SHOULD give system administrators the option to disable support for both automated and manual archiving, since archived conversations can consume significant storage space.

11.1 Plain Text Subject

Since the subject of each collection will not be encrypted, the client MUST warn its human user (if any) before including 'subject' attributes on encrypted collections.

11.2 Store Headers

The client that originates a message MAY specify a 'false' value for the 'store' header (see Stanza Headers and Internet Metadata [18]). The recipient MUST NOT archive such a message or any of the information it contains.

If the sender plans to use 'store' headers it MUST use Service Discovery to determine whether or not the recipient supports them. Note: Since servers are not required to check the content of message stanzas for headers, if the recipient is using automatic archiving then it MUST indicate that it does not support 'store' headers.

If the recipient does not support 'store' headers, then the sender MUST confirm with its human user (if any) before sending such a message.

13.1 Protocol Namespaces

The Jabber Registrar [20] shall include 'http://jabber.org/protocol/archive' in its registry of protocol namespaces (see <http://www.jabber.org/registrar/namespaces.html>):

13.2 Service Discovery Features

The Jabber Registrar shall include the following features in its registry of service discovery features (see <http://www.jabber.org/registrar/disco-features.html>):

• http://jabber.org/protocol/archive#auto
• http://jabber.org/protocol/archive#encrypt
• http://jabber.org/protocol/archive#manage
• http://jabber.org/protocol/archive#manual
• http://jabber.org/protocol/archive#pref

13.3 Cryptography Scheme Names

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/archive'
    xmlns='http://jabber.org/protocol/archive'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The allowable root element for the namespace defined
      herein are:
        - archive
        - list
        - otr
        - remove
        - retrieve
        - save
        - store
    </xs:documentation>
  </xs:annotation>

  <xs:element name='archive'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='store' minOccurs='1' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='with' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='auto'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='dataalg' type='xs:string' use='optional'/>
          <xs:attribute name='key' type='xs:string' use='optional'/>
          <xs:attribute name='keyalg' type='xs:string' use='optional'/>
          <xs:attribute name='master' type='xs:string' use='optional'/>
          <xs:attribute name='save' type='xs:boolean' use='required'/>
          <xs:attribute name='secret' use='optional' type='xs:string'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='changed'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='start' type='xs:dateTime' use='required'/>
          <xs:attribute name='with' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='crypt'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='label' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='default'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='otr' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='allow'/>
                <xs:enumeration value='deny'/>
                <xs:enumeration value='require'/>
                <xs:enumeration value='try'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name='save' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='all'/>
                <xs:enumeration value='body'/>
                <xs:enumeration value='false'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name='unset' use='optional' type='xs:boolean'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='jid' use='required' type='xs:string'/>
          <xs:attribute name='otr' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='allow'/>
                <xs:enumeration value='deny'/>
                <xs:enumeration value='require'/>
                <xs:enumeration value='try'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name='save' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='all'/>
                <xs:enumeration value='body'/>
                <xs:enumeration value='false'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='list'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='store' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='end' type='xs:dateTime' use='optional'/>
      <xs:attribute name='master' type='xs:string' use='optional'/>
      <xs:attribute name='start' type='xs:dateTime' use='optional'/>
      <xs:attribute name='with' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='modified'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='changed' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='removed' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='pref'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='default' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='remove'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='end' type='xs:dateTime' use='optional'/>
          <xs:attribute name='start' type='xs:dateTime' use='required'/>
          <xs:attribute name='with' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='removed'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='start' type='xs:dateTime' use='required'/>
          <xs:attribute name='with' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='retrieve'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='start' type='xs:dateTime' use='required'/>
          <xs:attribute name='with' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='store'>
    <xs:complexType>
      <xs:choice maxOccurs='unbounded'>
        <xs:element ref='crypt'/>
        <xs:element name='from' type='messageType'/>
        <xs:element name='note' type='xs:string'/>
        <xs:element name='to' type='messageType'/>
      </xs:choice>
      <xs:attribute name='dataalg' type='xs:string' use='optional'/>
      <xs:attribute name='key' type='xs:string' use='optional'/>
      <xs:attribute name='keyalg' type='xs:string' use='optional'/>
      <xs:attribute name='master' type='xs:string' use='optional'/>
      <xs:attribute name='start' type='xs:dateTime' use='required'/>
      <xs:attribute name='subject' type='xs:string' use='optional'/>
      <xs:attribute name='with' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='messageType'>
    <xs:sequence>
      <xs:element name='body' type='xs:string' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:attribute name='secs' type='xs:nonNegativeInteger' use='required'/>
  </xs:complexType>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
  

1. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

2. JEP-0155: Chat Session Negotiation <http://www.jabber.org/jeps/jep-0155.html>.

3. If a client (or user) acts in bad faith then its contacts cannot prevent it archiving conversations.

4. JEP-0116: Encrypted Sessions <http://www.jabber.org/jeps/jep-0116.html>.

5. JEP-0082: Jabber Date and Time Profiles <http://www.jabber.org/jeps/jep-0082.html>.

6. 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).

7. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.

8. SHA-1 is broken (assuming the attacker has plenty of computing power) and many other standard hashes are not optimised for 32-bit processors (e.g. Whirlpool, SHA-384, SHA-512).

9. Future versions of this document MAY be modified to recommend other algorithms.

10. Mechanisms for the storage and retrieval of private keys are beyond the scope of this document.

11. RSA-KEM is the only required encapsulation scheme since it is NESSIE-recommended, its security is tightly proven (unlike RSA-OAEP or PKCS #1 v1.5), and it is very simple to implement.

12. Future versions of this document MAY be modified to recommend other algorithms.

13. JEP-0116: Encrypted Sessions <http://www.jabber.org/jeps/jep-0116.html>.

14. JEP-0059: Result Set Management <http://www.jabber.org/jeps/jep-0059.html>.

15. Clients that run in constrained environments may not be able to implement replication if they are prevented from accessing (sufficient) local storage.

16. Since collections should be stored in encrypted form on the server, server-side searching of the content of messages is beyond the scope of this protocol.

17. JEP-0090: Entity Time <http://www.jabber.org/jeps/jep-0090.html>.

18. JEP-0131: Stanza Headers and Internet Metadata <http://www.jabber.org/jeps/jep-0131.html>.

19. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

20. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

Version 0.7 (2006-09-08)

Version 0.6 (2006-08-18)

Version 0.5 (2006-05-03)

Version 0.4 (2005-12-21)

Version 0.3 (2005-10-21)

Version 0.2 (2005-04-18)

Version 0.1 (2004-06-04)