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.

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:

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

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", "allow" or "never" - 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.

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

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.

A client may set the default Modes:

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

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

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

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

The same error cases apply as when Setting Default Modes.

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:

• Messages are encrypted using evanscent keys, as in &jep0116;
• 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".

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:

• '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 &jep0082;)

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

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

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

If the server cannot service a store request because the collection is too large then it MUST return a ¬acceptable; error:

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:

A client MAY archive messages that it receives from &jep0045; 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:

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.

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 require that every message is logged automatically (see Security Considerations). Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's general Archiving Preferences.

Note: Both parties to an ESession (see &jep0116;) 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.

If the client switches off all auto-archiving then the server MUST close and store all active collections.

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.

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

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

• If the client is trying to enable automatic archiving, but the server does not allow the saving of full message stanza content, and the user has specified the 'all' Save Mode in one of its Archiving Preferences.

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

• If the client is trying to enable encryption, but the server does not support encryption or the user did not specify a public key and is not publishing any keys using Public Key Publishing.

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.

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':

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:

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

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.

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 ¬found; error:

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

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.

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.

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.

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.

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.

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.

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.

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

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.

If the specified collection (or collections) do not exist then the server MUST return an ¬found; error:

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 &jep0090; 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.

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.

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.

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

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.

The client that originates a message MAY specify a 'false' value for the 'store' header (see &jep0131;). 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.

The ®ISTRAR; shall include 'http://jabber.org/protocol/archive' in its registry of protocol namespaces (see &NAMESPACES;):

The Jabber Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;):

• 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