<p>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 <linkurl='#auto'>Automated Archiving</link> feature, "encrypt" for the <em>server-side</em> encryption feature (see <linkurl='#auto'>Automated Archiving</link>), "manage" for the <linkurl='#manage'>Archive Management</link> feature, "manual" for the <linkurl='#manual'>Manual Archiving</link> feature, or "pref" for the <linkurl='#pref'>Archiving Preferences</link> feature.</p>
<examplecaption='Server Service Discovery response'>
<section2topic='Setting Modes for a Contact'anchor='pref-jid'>
<p>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 (&BAREJID;).</p>
<examplecaption='Client Sets Modes for a Contact'><![CDATA[
<p>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 <cite>Jabber Date and Time Profiles</cite>) instead of a 'secs' attribute. The absolute time MAY be before the start time of the collection:</p>
<examplecaption='Storing offline messages in a collection'><![CDATA[
<p>A client MAY archive messages that it receives from &xep0045; 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:</p>
<examplecaption='Storing groupchat messages in a collection'><![CDATA[
<iqtype='set'to='montague.net'id='up3'>
<iqtype='set' id='up3'>
<storexmlns='http://jabber.org/protocol/archive'
with='balcony@house.capulet.com'
start='1469-07-21T03:16:37Z'>
@ -368,7 +372,7 @@
<section2topic='Changing the Subject of a Collection'anchor='crypt'>
<p>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 <linkurl='#manage-remove'>Removing a Collection</link>) and then create a new one.</p>
<examplecaption='Changing the subject of a collection without appending messages'><![CDATA[
<iqtype='set'to='montague.net'id='subject1'>
<iqtype='set' id='subject1'>
<storexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com/chamber'
start='1469-07-21T02:56:15Z'
@ -386,7 +390,7 @@
<p>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.</p>
<p>Note: A collection that contains <EncryptedData/> or <EncryptedKey/> elements MUST NOT contain <to/> or <from/> or <note/> elements.</p>
<examplecaption='Storing encrypted messages and keys in a collection'><![CDATA[
<p>A client MAY enable or disable automatic archiving for messages sent over its stream. Automatic archiving MUST default to disabled for each new stream that is opened, unless administrator policies <em>require</em> that every message is logged automatically (see <linkurl='#security'>Security Considerations</link>). Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's general <linkurl='#pref'>Archiving Preferences</link>.</p>
<p>Note: Both parties to an ESession (see &xep0116;) MUST either disable archiving or use an archiving method other than automatic, since ESession decryption keys are short-lived - making it impossible to decrypt automatically archived messages.</p>
<p>If server administration policies <em>require</em> that every message is logged automatically (see <linkurl='#security'>Security Considerations</link>) then:</p>
<ul>
<li>The server MUST enable automatic archiving when each stream is opened.</li>
<li>Clients MUST NOT be allowed to disable automatic archiving.</li>
<li>Automatic archiving MUST NOT be subject to users' <linkurl='#pref'>Archiving Preferences</link>.</li>
<li>If the server has not received a request from a client for its user's archiving preferences (see <linkurl='#pref-determine'>Determining Preferences</link>) within a few seconds of authenticating the client then the server MUST send a warning message to the client:</li>
</ul>
<examplecaption='Server warns user of a legacy client about compulsory archiving'><![CDATA[
<messageto='juliet@capulet.com/chamber'>
<body>WARNING: All messages that you send or
receive will be recorded by the server.</body>
</message>
]]></example>
<p>Otherwise:</p>
<ul>
<li>Automatic archiving MUST default to disabled when each stream is opened.</li>
<li>A client MAY enable or disable automatic archiving for messages sent over its stream at any time. Note: If the client switches off all auto-archiving then the server MUST close and store all active collections.</li>
<li>Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's <linkurl='#pref'>Archiving Preferences</link>.</li>
<li>Note: Both parties to an ESession (see &xep0116;) SHOULD either disable archiving or use an archiving method other than automatic, since ESession decryption keys are short-lived - making it impossible to decrypt automatically archived messages.</li>
</ul>
<examplecaption='Client enables auto archiving'><![CDATA[
<p>If the client switches off all auto-archiving then the server MUST close and store all active collections.</p>
</section2>
<section2topic='Enabling Auto-Archiving with Encryption'anchor='auto-crypt'>
<p>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).</p>
@ -480,7 +501,7 @@
<p>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.</p>
<p>The client SHOULD use <cite>Result Set Management</cite> 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.</p>
<examplecaption='Requesting the first page of a list with same JID'><![CDATA[
<iqtype='get'to='montague.net'id='juliet1'>
<iqtype='get' id='juliet1'>
<listxmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com'>
<setxmlns='http://jabber.org/protocol/rsm'>
@ -490,7 +511,7 @@
</iq>
]]></example>
<examplecaption='Requesting the first page of a list with same JID between two times'><![CDATA[
<iqtype='get'to='montague.net'id='period1'>
<iqtype='get' id='period1'>
<listxmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com'
start='1469-07-21T02:00:00Z'
@ -502,7 +523,7 @@
</iq>
]]></example>
<examplecaption='Requesting the first page of a list after a time'><![CDATA[
<iqtype='get'to='montague.net'id='list1'>
<iqtype='get' id='list1'>
<listxmlns='http://jabber.org/protocol/archive'
start='1469-07-21T02:00:00Z'>
<setxmlns='http://jabber.org/protocol/rsm'>
@ -513,7 +534,7 @@
]]></example>
<p>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':</p>
<examplecaption='Receiving the first page of a list'><![CDATA[
<p>Note: In accordance with <cite>Result Set Management</cite>, 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.</p>
<p>If no collections correspond to the request the server MUST return an empty <list/> element:</p>
<examplecaption='Receiving an empty list'><![CDATA[
<examplecaption='Requesting the second page of a list'><![CDATA[
<iqtype='get'to='montague.net'id='list2'>
<iqtype='get' id='list2'>
<listxmlns='http://jabber.org/protocol/archive'
start='1469-07-21T02:00:00Z'>
<setxmlns='http://jabber.org/protocol/rsm'>
@ -556,7 +577,7 @@
<p>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 <cite>Jabber Date and Time Profiles</cite>). Both attributes MUST be included to uniquely identify a collection:</p>
<p>The client SHOULD use <cite>Result Set Management</cite> 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.</p>
<examplecaption='Requesting the first page of a collection'><![CDATA[
<p>Note: In accordance with <cite>Result Set Management</cite>, 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.</p>
<p>If the specified collection does not exist then the server MUST return an ¬found; error:</p>
<p>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.</p>
<examplecaption='Requesting the first page of an encrypted collection with all versions of keys'><![CDATA[
<p>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.</p>
<examplecaption='Receiving the first page of an encrypted collection'><![CDATA[
<p>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.</p>
<examplecaption='Requesting the first page of an encrypted collection with specified version of keys'><![CDATA[
<section2topic='Removing a Collection'anchor='manage-remove'>
<p>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.</p>
<examplecaption='Removing a single collection'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove1'>
<removexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com/chamber'
start='1469-07-21T02:56:15Z'/>
@ -721,7 +749,7 @@
]]></example>
<p>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.</p>
<examplecaption='Removing all collections with a specified bare JID between two times'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove2'>
<removexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com'
start='1469-07-21T02:00:00Z'
@ -731,7 +759,7 @@
<p>If the 'with' attribute is omitted then collections with any JID are removed.</p>
<p>If the end date is in the future then then all collections after the start date are removed.</p>
<examplecaption='Removing all collections after a date'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove3'>
<removexmlns='http://jabber.org/protocol/archive'
start='1469-07-21T02:00:00Z'
end='2038-01-01T00:00:00Z'/>
@ -739,34 +767,37 @@
]]></example>
<p>If the start date is before all the collections in the archive then all collections prior to the end date are removed.</p>
<examplecaption='Removing all collections before a date'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove4'>
<removexmlns='http://jabber.org/protocol/archive'
start='0000-01-01T00:00:00Z'
end='1469-07-21T04:00:00Z'/>
</iq>
]]></example>
<examplecaption='Removing all collections'><![CDATA[
<p>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 <linkurl='#auto'>Automated Archiving</link>) are removed.</p>
<examplecaption='Removing a collection being recorded by the server'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove6'>
<removexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com/chamber'
open='true'/>
</iq>
]]></example>
<examplecaption='Removing all collections being recorded by the server'><![CDATA[
<iqtype='set'to='montague.net'>
<iqtype='set'id='remove7'>
<removexmlns='http://jabber.org/protocol/archive'
open='true'/>
</iq>
]]></example>
<p>If the specified collection (or collections) do not exist then the server MUST return an ¬found; error:</p>
<p>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.</p>
<p>The client first requests a list of the affected <EncryptedKey/> elements from all collections by sending a <keys/> element to the server:</p>
<examplecaption='Requesting the first page of a list of keys'><![CDATA[
<p>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:</p>
<examplecaption='Receiving the first page of a list of keys'><![CDATA[
<p>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 <linkurl='#crypt'>Encryption</link>):</p>
<examplecaption='Storing encrypted keys in a collection'><![CDATA[
<iqtype='set'to='montague.net'id='crypt1'>
<iqtype='set' id='crypt1'>
<storexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com/chamber'
start='1469-07-23T19:22:31Z'>
@ -850,8 +881,8 @@
.
]]></example>
<p>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:</p>
<examplecaption='Requesting the first page of a list of keys'><![CDATA[
<iqtype='get'to='montague.net'id='pubkey1'>
<examplecaption='Deleting key(s) from a collection'><![CDATA[
<iqtype='get'id='delete1'>
<deletexmlns='http://jabber.org/protocol/archive'
with='juliet@capulet.com/chamber'
start='1469-07-23T19:22:31Z'>
@ -869,7 +900,7 @@
<p>The client MUST request each page of the list using the <cite>Result Set Management</cite> protocol embeded in a <modified/> element. The content of the <after/> element SHOULD be a UTC time (see <cite>Jabber Date and Time Profiles</cite>) 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).</p>
<examplecaption='Requesting a page of modifications'>
<p>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 <em>after</em> 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 <cite>Jabber Date and Time Profiles</cite>) that the last collection on the page was modified.</p>
<examplecaption='Receiving a page of modifications'><![CDATA[