XEP-0136: Message Archiving

This document defines mechanisms and preferences for the archiving and retrieval of XMPP messages.


NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the JSF standards process.


XEP Information

Status: Proposed
Type: Standards Track
Number: 0136
Version: 0.11
Last Updated: 2006-11-06
Publishing Organization: Jabber Software Foundation
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-0030, XEP-0059, XEP-0060, XEP-0155, XEP-0163, W3C XML Encryption, W3C XML Signature
Supersedes: None
Superseded By: None
Short Name: archive
Wiki Page: <http://wiki.jabber.org/index.php/Message Archiving (XEP-0136)>

Author Information

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

Justin Karneges

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

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Table of Contents

1. Introduction
2. Determining Server Support
3. Archiving Preferences
3.1. Introducton
3.2. Determining Preferences
3.3. Setting Default Modes
3.4. Setting Modes for a Contact
3.5. Setting Archiving Method Preferences
4. Off The Record
4.1. OTR Negotiation
4.2. Notes
5. Manual Archiving
5.1. Introduction
5.2. Collections
5.3. Uploading Messages to a Collection
5.4. Offline Messages
5.5. Groupchat Messages
5.6. Changing the Subject of a Collection
6. Encryption
7. Automated Archiving
7.1. Toggling Auto-Archiving
7.2. Enabling Auto-Archiving with Encryption
7.3. Not-Implemented Responses
8. Archive Management
8.1. Retrieving a List of Collections
8.2. Retrieving a Collection
8.3. Removing a Collection
9. Replacing EncryptedKey Elements
10. Replication
11. File Format
12. Implementation Notes
12.1. Time Synchronization
12.2. Bandwidth Considerations
12.3. Storage Considerations
13. Security Considerations
13.1. Automatic Archiving Defaulting to On
13.2. Plain Text Subject
13.3. Store Headers
14. IANA Considerations
15. XMPP Registrar Considerations
15.1. Protocol Namespaces
15.2. Service Discovery Features
16. XML Schemas
Notes
Revision History


1. Introduction

Many XMPP clients implement some form of client-side message archiving. However, it is not always convenient or even possible to archive messages locally, e.g., because it is easier to keep all archives in one universally accessable place (not scattered around on multiple computers or devices) or because the client operates in a web browser or resides on a mobile device that does not have sufficient local storage for message archiving. In addition, server-side archiving makes it possible to offer new services such as integration of IM and email. Therefore it is beneficial to define methods for server-side archiving of XMPP messages.

There are two main approaches to this problem:

  1. Enable the client to send individual messages or entire conversations to the server for archiving (optionally after encryption); we call this manual archiving.
  2. Enable the server (at the client's request) to archive messages as they pass through the server; we call this automated archiving.

So that client and server developers can refer to one specification, both approaches are defined in this document. In addition, this document defines common methods for retrieving and managing archived messages.

Complying with XMPP Core, the server MUST respond to all <iq/> element of type 'get' or 'set'. However, most successful responses have been omitted from this document in the interest of conciseness.

2. Determining Server Support

A client discovers whether its server supports this protocol using Service Discovery [1].

Example 1. Client Service Discovery request

    
<iq type='get' id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'http://jabber.org/protocol/archive#name', where 'name' is 'auto' for the Automated Archiving feature, 'encrypt' for the server-side encryption feature (see Automated Archiving), 'manage' for the Archive Management feature, 'manual' for the Manual Archiving feature, or 'pref' for the Archiving Preferences feature.

Example 2. Server Service Discovery response

    
<iq type='result' to='romeo@montague.net/orchard' id='disco1'>
  <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. Archiving Preferences

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 file archiving, or automatic or manual archiving to a server), it SHOULD adhere to its user's archiving preferences. However, a client MAY maintain a set of preferences in a local file which takes precedence over the preferences stored on the server for both local archiving and manual archiving.

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 Preferences

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends an empty <pref/> element to its server:

Example 3. Client Requests Archiving Preferences

<iq type='get' id='pref1'>
  <pref xmlns='http://jabber.org/protocol/archive'/>
</iq>
    

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

Each <default/> or <item/> 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 <default/> or <item/> element in the response whose 'save' attribute is not set to 'false' is RECOMMENDED to also include an 'expire' attribute which indicates how many seconds after messages are archived that the server SHOULD delete them.

Each <default/> or <item/> element in the response MUST include an 'otr' attribute, whose value MAY be 'require', 'prefer', 'approve', 'concede', 'oppose' or 'forbid'. The client MUST be guided by the specified 'otr' attribute value when negotiating (see Chat Session Negotiation [2]) whether or not all messages exchanged with a contact will be Off The Record. Note: If the OTR Mode is 'require' then the Save Mode MUST be 'false'.

The server MUST also include <method/> elements that reflect the user's preferences for each of the possible archiving methods. There MUST be at least three such elements for local file archiving (type 'local'), automatic archiving by the user's server (type 'auto'), and manual archiving to a server (type 'manual'). The 'use' attribute of each <method/> element MUST be set to 'prefer', 'concede' or 'forbid' - indicating which archiving methods the user's clients SHOULD, MAY (if it does not support any preferred method) or MUST NOT use.

The server MUST also include an <auto/> element reflecting the current Automated Archiving settings for this stream.

Example 4. Server Returns Preferences

<iq type='result' id='pref1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='body' otr='concede' expire='31536000'/>
    <item jid='romeo@montague.net' save='false' otr='require'/>
    <item jid='benvolio@montague.net' save='all' expire='630720000' otr='forbid'/>
    <method type='auto' use='forbid'/>
    <method type='local' use='concede'/>
    <method type='manual' use='prefer'/>
    <auto save='false'/>
  </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 Preferences

<iq type='result' id='pref1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='concede' unset='true'/>
    <method type='auto' use='concede'/>
    <method type='local' use='concede'/>
    <method type='manual' use='concede'/>
    <auto save='false'/>
  </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). Note: changes to the <auto/> element MUST NOT be replicated in this way.

3.3 Setting Default Modes

A client may set the default Modes:

Example 6. Client Sets Default Modes

<iq type='set' id='pref2'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='prefer'/>
  </pref>
</iq>
    

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

Example 7. Server Acknowledges Change

<iq type='result' id='pref2' 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='push1' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <default save='false' otr='prefer'/>
  </pref>
</iq>

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

The server MAY be configured to return a <feature-not-implemented/> error in the following cases:

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' id='pref3'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <item jid='romeo@montague.net' save='body' expire='604800' otr='concede'/>
  </pref>
</iq>
    

Example 10. Server Acknowleges Change

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

Example 11. Server Pushes New Modes

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

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

The same error cases apply as when Setting Default Modes.

3.5 Setting Archiving Method Preferences

Example 12. Client Sets Method Preferences

<iq type='set' id='pref4'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <method type='auto' use='concede'/>
    <method type='local' use='forbid'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>
    

Example 13. Server Acknowleges Change

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

Example 14. Server Pushes New Method Preferences

<iq type='set' id='push5' to='juliet@capulet.com/chamber'>
  <pref xmlns='http://jabber.org/protocol/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@capulet.com/pda'>
  <pref xmlns='http://jabber.org/protocol/archive'>
    <method type='auto' use='concede'/>
    <method type='local' use='forbid'/>
    <method type='manual' use='prefer'/>
  </pref>
</iq>
    

4. Off The Record

A user will sometimes exchange messages with contacts who prefer that their conversations are not archived by either party.

4.1 OTR Negotiation

Any client that archives messages SHOULD support Chat Session Negotiation 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 Archiving Preferences.

Note: A client MUST NOT propose or agree to enable OTR unless it has confirmed that its server will allow it to switch off Automated Archiving.

Table 1: OTR options offered when client initiates a chat negotiation

OTR Archive Preference Offered options*
require true***
prefer true,false
approve true,false
concede false,true**
oppose false,true**
forbid false**

* In order of preference, the first value is the default

** Alternatively, the client MAY decide not to initiate an OTR negotiation and to save messages (until the contact initiates a negotiation).

*** If the client receives no response it MUST NOT send any messages to the contact.

Note: When negotiating a chat session the client MUST include the <required/> element inside the 'otr' <field/> 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' <field/> element set to 'false'.

Table 2: OTR state selected when client responds to each of the four possible offers

OTR Archive Preference true true,false* false,true* false
require true true true fail**
prefer true true true false
approve true true false false
concede true true false false
oppose true false false false
forbid fail** false false false

* The first value is the default.

** The client MUST NOT send any messages to the contact.

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 required, then the client MUST refuse the request. It MAY then send its own Chat Session Negotiation request with an 'otr' field.

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

4.2 Notes

If a Chat Session Negotiation agreed to enable OTR then the clients MUST NOT allow messages sent in either direction to be archived in any way (including Manual Archiving and Automated Archiving). [3]

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 Automated Archiving 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 Removing a Collection for a description of how to remove the messages currently being recorded by the server).

5. Manual Archiving

5.1 Introduction

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

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

5.2 Collections

A "collection" is 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).

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

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 <EncryptedData/> and <EncryptedKey/> 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 whole seconds of the message relative to the previous message in the collection (or, for the first message, relative to the start of the collection) SHOULD be specified with a 'secs' attribute. Note: When deciding whether to round up or down to a number of whole seconds, entities MUST ensure that the sum of the 'secs' attribute and the 'secs' attributes of the preceeding messages will accurately reflect the absolute time of the message. (e.g., if a sequence of messages occur at exactly 0.51-second intervals then the 'secs' attributes should generally alternate between '0' or '1'.)

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 15. Storing messages in a collection

<iq type='set' 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 16. 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 17. Unsuccessful reply

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

5.4 Offline Messages

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. The absolute time MAY be before the start time of the collection:

Example 18. Storing offline messages in a collection

<iq type='set' 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.5 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 19. Storing groupchat messages in a collection

<iq type='set' 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.6 Changing the Subject of a Collection

If the client specifies a new value for the 'subject' attribute of any existing collection then the server MUST update the existing value. Note: The client cannot specify new values for the '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 20. Changing the subject of a collection without appending messages

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

6. Encryption

The examples above are not encrypted for clarity. However, clients SHOULD encrypt manually-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later versions). Servers MUST support the manual-archiving of encrypted collections.

Before uploading a sequence of messages to a collection, the client SHOULD select a symmetric data encryption algorithm, generate a suitable random encryption key, give the key a unique (for the user) name, encrypt the symmetric key with one of the user's public keys, and wrap the result inside one or more <EncryptedKey/> elements, as specified in XML Encryption [8].

To ensure that all its user's clients will be able to decrypt the collection, the client SHOULD create one <EncryptedKey/> element for each of its user's public keys that are being published using Public Key Publishing [9]. However, the client MUST NOT create an <EncryptedKey/> element for any public key until it has confirmed that it belongs to the user. Note: The fact that a public key is being published using Public Key Publishing is not sufficient proof of ownership, since the user's server may have been compromised at some stage. The method of confirmation is beyond the scope of this document.

The client SHOULD use the symmetric key to encrypt the joined sequence of <to/>, <from/> and <note/> elements, base64 encode the resulting sequence of bytes, and wrap it inside an <EncryptedData/> element, as described in XML Encryption.

Clients may add one or more <EncryptedData/> or <EncryptedKey/> elements to a collection using exactly the same method as for <to/>, <from/> and <note/> elements (see Uploading Messages to a Collection). One collection may contain <EncryptedData/> elements encrypted with different symmetric keys.

When appending <EncryptedData/> elements to a collection, the client MAY reuse a symmetric KEY that has already been uploaded to the collection. In this case the client SHOULD NOT resend <EncryptedKey/> elements.

Note: A collection that contains <EncryptedData/> or <EncryptedKey/> elements MUST NOT contain <to/> or <from/> or <note/> elements.

Example 21. Storing encrypted messages and keys in a collection

<iq type='set' id='crypt1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-23T19:22:31Z'
         subject='She speaks!'>
    <EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'
                   Type='http://www.w3.org/2001/04/xmlenc#Content'>
      <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc'/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>dataKey1</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>+OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ</CipherValue></CipherData>
    </EncryptedData>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey1</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey1fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey1</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey2fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
  </store>
</iq>
  

The <CipherData/> child of each <EncryptedData/> element contains the base64-encoded symmetric-encrypted messages. The <EncryptionMethod/> and <KeyInfo/> children specify the symmetric encryption algorithm and the name of the symmetric key used to encrypt the messages.

The <CarriedKeyName/> child of each <EncryptedKey/> element contains the name of the symmetric key it contains. The name is referenced by the <KeyName/> child of the <KeyInfo/> child of an <EncryptedData/> element. The <CipherData/> child of each <EncryptedKey/> element contains the base64-encoded public-key-encrypted symmetric key. The <EncryptionMethod/> and <KeyInfo/> children specify the public key encryption algorithm and the name of the public key used to encrypt the symmetric key. The name of the public key MAY refer to the name in the <KeyName/> child of one of the <KeyInfo/> elements that are being published using Public Key Publishing.

7. Automated Archiving

7.1 Toggling Auto-Archiving

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

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

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

Otherwise:

Example 23. Client enables auto archiving

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

7.2 Enabling Auto-Archiving with Encryption

Servers (and clients) SHOULD support the encryption (and decryption) of automatically-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later versions).

Whenever the client enables auto-archiving it SHOULD set the optional 'encrypt' attribute to 'true'. After receiving such a request, if the server supports encryption (see Determining Server Support), it MUST encrypt all the messages that it archives automatically (including any message collections that are currently being recorded) by following exactly the same proceedure as clients use when manually archiving collections (see Encryption).

The client MAY also specify one or more public keys (in addition to any public keys that the user may be publishing using Public Key Publishing). The server MUST use them all to encrypt all the symmetric keys it generates and add these to the collection wrapped in <EncryptedKey/> elements.

Example 24. Client enables auto archiving with encryption

<iq type='set' id='auto2'>
  <auto save='true'
        encrypt='true'
        xmlns='http://jabber.org/protocol/archive'>
    <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
      <KeyValue>
        <KeyName>romeoPublicKey3fingerprint</KeyName>
        <RSAKeyValue>
          <Modulus>xA7SEU+e0yQH5rm9kbCDN9o3aPIo7HbP7tX6WOocLZAtNfyxSZDU16ksL6W
            jubafOqNEpcwR3RdFsT7bCqnXPBe5ELh5u4VEy19MzxkXRgrMvavzyBpVRgBUwUlV
            5foK5hhmbktQhyNdy/6LpQRhDUDsTvK+g9Ucj47es9AQJ3U=
          </Modulus>
          <Exponent>AQAB</Exponent>
        </RSAKeyValue>
      </KeyValue>
    </KeyInfo>
  </auto>
</iq>
    

As soon as the server has finished storing a collection, it MUST securely destroy all copies of the symmetric key it used to encrypt the messages. Note: If the security of the server is compromised, then only the collections being recorded during the attack will be revealed (i.e. only those messages that would have been compromised even if they had not been stored).

7.3 Not-Implemented Responses

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

8. Archive Management

Manually uploaded and automatically saved collections are managed in the same way. There are three main areas of functionality related to archive management:

  1. Retrieving a list of collections
  2. Retrieving a collection
  3. Removing a collection

Requirements and protocol flows for each of these use cases are defined below. The protocols to retrieve a list of collections and an indivdual collection both make extensive use of Result Set Management [11]. Clients and servers SHOULD support all the features defined in that protocol.

8.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 25. Requesting the first page of a list with same JID

<iq type='get' 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 26. Requesting the first page of a list with same JID between two times

<iq type='get' 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 27. Requesting the first page of a list after a time

<iq type='get' 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. If the collection contains <EncryptedData/> or <EncryptedKey/> elements then the 'crypt' attribute of the <store/> element MUST be set to 'true':

Example 28. Receiving the first page of a list

<iq type='result' to='romeo@montague.net/orchard' id='list1'>
  <list xmlns='http://jabber.org/protocol/archive'>
    <store with='juliet@capulet.com/chamber'
           start='1469-07-21T02:56:15Z'
           subject='She speaks!'
           crypt='true'/>
    .
    [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 29. Receiving an empty list

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

Example 30. Requesting the second page of a list

<iq type='get' 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.

8.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 31. Requesting the first page of a collection

<iq type='get' 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 32. Receiving the first page of a collection

<iq type='result' to='romeo@montague.net/orchard' 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 33. Unsuccessful reply

<iq type='error' to='romeo@montague.net/orchard' 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>
  <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 34. Receiving an empty collection

<iq type='result' to='romeo@montague.net/orchard' 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 35. Requesting the second page of a collection

<iq type='get' 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>
    

The items in encrypted collections are typically larger - since each <EncryptedData/> element typically contains many messages. So the client SHOULD take even more care not to request a page of <EncryptedData/> elements that is so big it might exceed karma limits.

Example 36. Requesting the first page of an encrypted collection with all versions of keys

<iq type='get' id='page1'>
  <retrieve xmlns='http://jabber.org/protocol/archive'
            with='juliet@capulet.com/chamber'
            start='1469-07-23T19:22:31Z'
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>5</max>
    </set>
  </retrieve>
</iq>
    

In addition to the requested <EncryptedData/> elements, the server MUST return all the <EncryptedKey/> elements that it possesses for the user whose symmetric key name (wrapped in its <CarriedKeyName/> child) is referenced by the <KeyName/> child of the <KeyInfo/> child of any of the <EncryptedData/> elements in the returned page.

Example 37. Receiving the first page of an encrypted collection

<iq type='result' to='romeo@montague.net/orchard' id='page1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-23T19:22:31Z'
         subject='She speaks!'>
    <EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'
                   Type='http://www.w3.org/2001/04/xmlenc#Content'>
      <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc'/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>dataKey1</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>+OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ</CipherValue></CipherData>
    </EncryptedData>
    .
    [3 more <EncryptedData/> elements]
    .
    <EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'
                   Type='http://www.w3.org/2001/04/xmlenc#Content'>
      <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc'/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>dataKey2</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>+OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ</CipherValue></CipherData>
    </EncryptedData>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey1</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey1fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey1</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey2fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey2</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey1fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey2</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey2fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>0</first>
      <last>4</last>
      <count>7</count>
    </set>
  </store>
</iq>
    

The client MAY limit the number of <EncryptedKey/> elements that it receives by specifying the name of one or more public keys for which it holds the associated private keys. The name of each public key MUST be wrapped in a <KeyName/> element.

Example 38. Requesting the first page of an encrypted collection with specified version of keys

<iq type='get' id='page1'>
  <retrieve xmlns='http://jabber.org/protocol/archive'
            with='juliet@capulet.com/chamber'
            start='1469-07-23T19:22:31Z'>
    <KeyName xmlns='http://www.w3.org/2000/09/xmldsig#'>romeoPublicKey1fingerprint</KeyName>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>1</max>
    </set>
  </retrieve>
</iq>
    

If the request includes one or more <KeyName/> elements then the server MUST only return those <EncryptedKey/> elements whose public key name (wrapped in the <KeyName/> child of the <KeyInfo/> child) is specified in the request.

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

8.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 39. Removing a single collection

<iq type='set' id='remove1'>
  <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 40. Removing all collections with a specified bare JID between two times

<iq type='set' id='remove2'>
  <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 41. Removing all collections after a date

<iq type='set' id='remove3'>
  <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 42. Removing all collections before a date

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

Example 43. Removing all collections

<iq type='set' id='remove5'>
  <remove xmlns='http://jabber.org/protocol/archive'/>
</iq>
    

If the value of the optional 'open' attribute is set to 'true' then only collections that are currently being recorded automatically by the server (see Automated Archiving) are removed.

Example 44. Removing a collection being recorded by the server

<iq type='set' id='remove6'>
  <remove xmlns='http://jabber.org/protocol/archive'
          with='juliet@capulet.com/chamber'
          open='true'/>
</iq>
    

Example 45. Removing all collections being recorded by the server

<iq type='set' id='remove7'>
  <remove xmlns='http://jabber.org/protocol/archive'
          open='true'/>
</iq>
    

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

Example 46. Unsuccessful reply

<iq type='error' to='romeo@montague.net/orchard' id='remove1'>
  <remove xmlns='http://jabber.org/protocol/archive'
          with='juliet@capulet.com/chamber'
          start='1469-07-21T02:56:15Z'/>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

9. Replacing EncryptedKey Elements

If a private key becomes obsolete or compromised then it may be necessary for a client to replace all <EncryptedKey/> elements that contain symmetric keys encrypted with the public key that is associated with the obsolete private key.

The client first requests a list of the affected <EncryptedKey/> elements from all collections by sending a <keys/> element to the server:

Example 47. Requesting the first page of a list of keys

<iq type='get' id='pubkey1'>
  <keys xmlns='http://jabber.org/protocol/archive'>
    <KeyName xmlns='http://www.w3.org/2000/09/xmldsig#'>romeoPublicKey1fingerprint</KeyName>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <max>50</max>
    </set>
  </keys>
</iq>
  

The server MUST return only <EncryptedKey/> elements whose symmetric encryption key is encrypted with the obsolete public key specified in the <KeyName/> child of the request:

Example 48. Receiving the first page of a list of keys

<iq type='result' to='romeo@montague.net/orchard' id='pubkey1'>
  <keys xmlns='http://jabber.org/protocol/archive'>
    <store with='juliet@capulet.com/chamber'
           start='1469-07-23T19:22:31Z'>
      <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
        <CarriedKeyName>dataKey1</CarriedKeyName>
        <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
          <KeyName>romeoPublicKey1fingerprint</KeyName>
        </KeyInfo>
        <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
      </EncryptedKey>
      <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
        <CarriedKeyName>dataKey2</CarriedKeyName>
        <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
          <KeyName>romeoPublicKey1fingerprint</KeyName>
        </KeyInfo>
        <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
      </EncryptedKey>
    </store>
    .
    [49 more sets of collection keys]
    .
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>1469-07-23T19:22:31Zjuliet@capulet.com</first>
      <last>1469-08-03T13:24:06Zbalcony@house.capulet.com</last>
      <count>3810</count>
    </set>
  </keys>
</iq>
  

The client decrypts each symmetric key with the obsolete private key and encrypts it again with the new public key. The client then wraps each symmetric key in an <EncryptedKey/> element and asks the server to store it in its associated collection on the server (see Encryption):

Example 49. Storing encrypted keys in a collection

<iq type='set' id='crypt1'>
  <store xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-23T19:22:31Z'>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey1</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey2fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
    <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#'>
      <CarriedKeyName>dataKey2</CarriedKeyName>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <KeyInfo xmlns='http://www.w3.org/2000/09/xmldsig#'>
        <KeyName>romeoPublicKey2fingerprint</KeyName>
      </KeyInfo>
      <CipherData><CipherValue>E5Qbvfa2gI5lBZMAHryv4g</CipherValue></CipherData>
    </EncryptedKey>
  </store>
</iq>
.
[49 more sets of collection keys]
.
  

Finally, the client asks the server to delete from each collection all <EncryptedKey/> elements whose symmetric encryption key is encrypted with the obsolete public key:

Example 50. Deleting key(s) from a collection

<iq type='get' id='delete1'>
  <delete xmlns='http://jabber.org/protocol/archive'
         with='juliet@capulet.com/chamber'
         start='1469-07-23T19:22:31Z'>
    <KeyName xmlns='http://www.w3.org/2000/09/xmldsig#'>romeoPublicKey1fingerprint</KeyName>
  </delete>
</iq>
.
[49 more delete requests]
.
  

10. Replication

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

The client MAY 'synchronize' its local copy of the archive with the 'master' archive on the server at any time. The first step is to request the list of collections that the server has changed (created, modified or removed) in its master archive since the last update to the client's copy of the archive.

The client MUST request each page of the list using the Result Set Management protocol embeded in a <modified/> element. The content of the <after/> element SHOULD be a UTC time (see Jabber Date and Time Profiles) that it has previously received from the server (see below). When synchronizing for the first time, the client MAY choose a suitable time for the first page request (e.g. 1970-01-01T00:00:00Z).

Example 51. Requesting a page of modifications

    
<iq type='get' 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>
  

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 <after/> element then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include only 'with' and 'start' attribues. The server MUST set the content of the <last/> element to the UTC time (see Jabber Date and Time Profiles) that the last collection on the page was modified.

Example 52. Receiving a page of modifications

<iq type='result' to='romeo@montague.net/orchard' 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>
  

Note: The server should remember the 'with' and 'start' attribues and the time of removal of all deleted collections. If this 'state' cannot be maintained indefinitely, then unless all the user's clients replicate before the server deletes its memory of a removal then it will not be reflected in all the local copies of the archive.

Note: Along with its copy of the archive the client SHOULD store the most recent <last/> time that it received from the server. The next time it synchronizes with the server it SHOULD specify that time when requesting the first result set page (see above).

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

11. File Format

Note the file format specified in this section is likely to be deprecated once a standards-based format has been published in a separate specification.

So that clients can share archived messages, this document specifies a common format for storage on disk (similar to email formats like mbox and Maildir). The file format uses the same XML constructs as the protocol. Each file may contain messages exchanged with a single JID. Any number of items may be stored in an archive file.

Example 53. Example file

<?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>
  

12. Implementation Notes

12.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 [14] 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.

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

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

13. Security Considerations

13.1 Automatic Archiving Defaulting to On

If automatic archiving defaults to enabled then that creates serious privacy issues for users of legacy clients that do not support this protocol, and (more seriously) for those contacts who they unwittingly mislead by agreeing to disable logging (via the 'otr' field defined in XEP-0155).

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

13.3 Store Headers

The client that originates a message MAY specify a 'false' value for the 'store' header (see Stanza Headers and Internet Metadata [15]). 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.

14. IANA Considerations

No interaction with the Internet Assigned Numbers Authority (IANA) [16] is required as a result of this document.

15. XMPP Registrar Considerations

15.1 Protocol Namespaces

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

15.2 Service Discovery Features

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

16. XML Schemas

<?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 elements for the namespace defined
      herein are:
        - archive
        - auto
        - delete
        - keys
        - list
        - modified
        - pref
        - remove
        - retrieve
        - 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:sequence>
        <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='encrypt' type='xs:boolean' use='optional'/>
      <xs:attribute name='save' type='xs:boolean' use='required'/>
    </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='default'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='expire' type='xs:nonNegativeInteger' use='optional'/>
          <xs:attribute name='otr' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='approve'/>
                <xs:enumeration value='concede'/>
                <xs:enumeration value='forbid'/>
                <xs:enumeration value='oppose'/>
                <xs:enumeration value='prefer'/>
                <xs:enumeration value='require'/>
              </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='delete'>
    <xs:complexType>
      <xs:sequence>
        <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='start' type='xs:dateTime' use='required'/>
      <xs:attribute name='with' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='expire' type='xs:nonNegativeInteger' use='optional'/>
          <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='approve'/>
                <xs:enumeration value='concede'/>
                <xs:enumeration value='forbid'/>
                <xs:enumeration value='oppose'/>
                <xs:enumeration value='prefer'/>
                <xs:enumeration value='require'/>
              </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='keys'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='store' minOccurs='0' maxOccurs='unbounded'/>
        <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='list'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='store' minOccurs='0' maxOccurs='unbounded'/>
        <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='end' type='xs:dateTime' 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='method'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='type' type='xs:string' use='required'/>
          <xs:attribute name='use' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='concede'/>
                <xs:enumeration value='forbid'/>
                <xs:enumeration value='prefer'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
    </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:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='note'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='utc' type='xs:dateTime' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='pref'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='auto' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='default' minOccurs='0' maxOccurs='1'/>
        <xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='method' 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='open' use='optional' type='xs:boolean'/>
          <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:sequence>
        <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='start' type='xs:dateTime' use='required'/>
      <xs:attribute name='with' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='store'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element name='from' type='messageType'/>
        <xs:element ref='note'/>
        <xs:element name='to' type='messageType'/>
        <xs:any processContents='lax' namespace='##other'/>
      </xs:choice>
      <xs:attribute name='crypt' use='optional' type='xs:boolean'/>
      <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' minOccurs='0' maxOccurs='1'/>
      <xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:attribute name='secs' type='xs:nonNegativeInteger' use='optional'/>
    <xs:attribute name='utc' type='xs:dateTime' use='optional'/>
  </xs:complexType>

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

</xs:schema>
  


Notes

1. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.

2. XEP-0155: Chat Session Negotiation <http://www.xmpp.org/extensions/xep-0155.html>.

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

4. XEP-0116: Encrypted Sessions <http://www.xmpp.org/extensions/xep-0116.html>.

5. XEP-0082: Jabber Date and Time Profiles <http://www.xmpp.org/extensions/xep-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. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

8. XML Encryption Syntax and Processing <http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/>.

9. XEP-0189: Public Key Publishing <http://www.xmpp.org/extensions/xep-0189.html>.

10. XEP-0116: Encrypted Sessions <http://www.xmpp.org/extensions/xep-0116.html>.

11. XEP-0059: Result Set Management <http://www.xmpp.org/extensions/xep-0059.html>.

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

13. Since collections SHOULD be stored on the server in a form that it cannot decrypt, server-side searching of the content of messages is beyond the scope of this protocol.

14. XEP-0090: Entity Time <http://www.xmpp.org/extensions/xep-0090.html>.

15. XEP-0131: Stanza Headers and Internet Metadata <http://www.xmpp.org/extensions/xep-0131.html>.

16. 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/>.

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


Revision History

Version 0.11 (2006-11-06)

Added more otr attribute values and clarified their meanings, changed the names of the use attribute values

(ip)

Version 0.10 (2006-10-11)

Added auto-archiving warning for legacy clients; corrected examples

(ip)

Version 0.9 (2006-10-02)

Added method child elements and expire attribute to pref element

(ip)

Version 0.8 (2006-09-29)

Server generates encryption secrets for auto-archiving; specified use of W3C XML Encryption standard; enabled replacement of keys encrypted with an obsolete public key; enabled removal of open collections

(ip)

Version 0.7 (2006-09-08)

Added preferences, results set management and notes; reinstated encryption and replication; simplified auto-archiving and off-the-record (with XEP-0155); many minor changes

(ip)

Version 0.6 (2006-08-18)

Added unset value for save attribute and added service attribute on default element; added source attribute on record element; specified that services should (not must) support save mode for particular contacts.

(jp/psa)

Version 0.5 (2006-05-03)

Integrated text from server-side archiving proposal; added partial support to collection retrieval; harmonized XML formats and namespaces; defined XMPP Registrar considerations and XML schema.

(psa/jp/jk)

Version 0.4 (2005-12-21)

Added Replication and Searching section, partial attribute; minor improvements

(ip)

Version 0.3 (2005-10-21)

Added more examples to Removing Collections

(ip)

Version 0.2 (2005-04-18)

Complete rewrite.

(ip)

Version 0.1 (2004-06-04)

Initial version.

(jk)


END