From 5630761df34d9f505df48dd46b76db6bc1be1cf2 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Tue, 4 Mar 2008 03:44:11 +0000 Subject: [PATCH] 0.15 git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1733 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0136.xml | 952 +++++++++++++++++++++++++++------------------------ 1 file changed, 514 insertions(+), 438 deletions(-) diff --git a/xep-0136.xml b/xep-0136.xml index 43bd893a..023125dc 100644 --- a/xep-0136.xml +++ b/xep-0136.xml @@ -15,19 +15,16 @@ Standards XMPP Core - XMPP IM XEP-0004 XEP-0030 XEP-0059 XEP-0060 - XEP-0155 - XEP-0163 W3C XML Encryption W3C XML Signature - archive + TO BE ASSIGNED &ianpaterson; Jon @@ -37,6 +34,12 @@ &stpeter; &infiniti; + + 0.15 + 2008-03-03 + psa +

Changed temporary namespace per XEP-0053 procedures; moved all encrypted-related material to dedicated section; removed text about file format; modified replication to use start attribute, not after element; added version attribute for tracking collection changes; added itemremove element to delete all preferences for a contact.

 + 0.14 2007-08-16 @@ -122,40 +125,18 @@

Initial version.

 + -

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

+

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 accessible 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 instant messaging 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. -
  2. Enable the server (at the client's request) to archive messages as they pass through the server; we call this automated archiving.
    3. +
  3. Enable the client to send individual messages or entire conversations to the server for archiving (optionally after encryption); we call this MANUAL ARCHIVING.
    4. +
  4. 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.

- - -

A client discovers whether its server supports this protocol using &xep0030;.

- - - - -]]> -

For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'http://www.xmpp.org/extensions/xep-0136.html#ns-name' &NSNOTE;, 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, and 'pref' for the Archiving Preferences feature.

- - - - ... - - - - - - ... - - -]]> +

Note: 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.

 +

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.

@@ -256,16 +237,16 @@ -

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends to its server an IQ-get containing an empty <pref/> element qualified by the 'http://www.xmpp.org/extensions/xep-0136.html#ns' namespace &NSNOTE;.

+

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends to its server an IQ-get containing an empty <pref/> element qualified by the 'urn:xmpp:tmp:archive' namespace &NSNOTE;.

- + ]]>

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

- + @@ -288,7 +269,7 @@

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

- + @@ -303,7 +284,7 @@

A client may set the default Modes:

- + @@ -315,13 +296,13 @@

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

- + - + @@ -336,7 +317,7 @@

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 &LOCALBARE; rather than a full JID &LOCALFULL;.

- + @@ -346,23 +327,34 @@ ]]> - + - + ]]>

The same error cases apply as when Setting Default Modes.

+

In order to remove all preferences for a contact, the client shall send an <itemremove/> element to the server.

+ + + + + + ]]> + + ]]> - + @@ -374,7 +366,7 @@ ]]> - + @@ -382,7 +374,7 @@ - + @@ -391,6 +383,7 @@ ]]> +

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

@@ -498,6 +491,7 @@

If a Stanza Session Negotiation agreed to enable OTR then both clients MUST ensure that the Stanza Session Negotiation messages themselves are not archived. For example, if Automated Archiving was enabled when the client received the initial Stanza 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).

 +

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:

@@ -520,8 +514,9 @@

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

If an opaque thread ID (found in the &THREAD; children of the &MESSAGE; elements whose content is stored in the collection) is associated with the conversation then it MUST be specified with a 'thread' attribute. Clients SHOULD include a &THREAD; child in each &MESSAGE; element they send that is part of a conversation they expect will be archived (see &xep0201;).

+

Upon receiving a manually-uploaded collection or creating a collection as a result of auto-archiving, the server MUST assign a version number to the collection, which MUST start at zero (0). Whenever the collection is modified, the server MUST increment the version number by one (1). The server MUST include the version number attribute whenever it sends the collection or information about the collection to the client, by including a 'version' attribute in the <chat/>, <changed/>, or <removed/> element. If the client includes a 'version' attribute in an IQ-set, the server MUST ignore it.

Note: The content of &MESSAGE; elements that have different thread IDs SHOULD be archived in separate collections. The content of &MESSAGE; elements that have the same thread IDs SHOULD be archived in the same collection. The thread attribute SHOULD NOT be set to any value other than the exact content of the &THREAD; elements. If no &THREAD; elements appeared in the conversation the <chat/> element SHOULD have no thread attribute. Implementations SHOULD use the thread attribute for cross-referencing purposes only, within the archive each collection MUST be uniquely identified by the combination of its 'with' and 'start' attributes.

-

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

+

Each collection MAY contain <note/>, <to/> or <from/> elements (or <EncryptedData/> and <EncryptedKey/> elements - see the Encryption section of this document).

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

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 depend on the user's Archiving Preferences. <to/> or <from/> elements MUST NOT be empty. Note: A server MAY be configured to return a <feature-not-implemented/> error if any <to/> or <from/> element contains anything other than &BODY; elements.

@@ -530,7 +525,7 @@

A collection of messages and notes is uploaded to the server encapsulated in a <save/> 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 collection does not exist then the server MUST create a new collection and inform the client that the collection version number is zero.

+ + + + + + ]]> +

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 an upload request because the collection is too large then it MUST return a ¬acceptable; error:

@@ -558,22 +575,33 @@ ]]> -

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.

+

If the client specifies a new value for the 'subject' attribute of any existing collection then the server MUST update the existing value and increment the collection version. 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.

- + + + ]]> + + + + + ]]> -

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 XEP-0082) instead of a 'secs' attribute. The absolute time MAY be before the start time of the collection:

+

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 XEP-0082) instead of a 'secs' attribute. The absolute time MAY be earlier than the start time of the collection:

- + @@ -589,7 +617,7 @@

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 (and, if available, bare JID) of the message sender:

- + She will invite him to some supper. @@ -604,11 +632,11 @@

Collections MAY be linked together by including a <previous/> and/or <next/> element. Each such element MUST include both a 'with' and a 'start' element to identify the other collection to which the collection is linked. For example, the <previous/> and <next/> elements in the two examples below are being used to link a groupchat between Romeo, Benvolio and Mercutio to a private chat that Romeo was having with Benvolio before they invited Mercutio to join them. Note: Collections MAY be linked in only one direction, they are not required to be double-linked in the way the examples below are.

- + - O, I am fortune's fool! + O, I am fortune's fool! Why dost thou stay? @@ -616,7 +644,7 @@ ]]> - + @@ -632,7 +660,7 @@

<previous/> and <next/> elements MAY be removed from a collection simply by uploading a <previous/> and/or <next/> element without any 'with' or 'start' attributes. Note: The server SHOULD NOT return an error if it finds that a link to be deleted does not exist.

- + @@ -647,73 +675,284 @@

A collection MUST NOT contain more than one x:data form. If a form is uploaded to a collection that already contains one then the older form element MUST be discarded. When a collection is retrieved (see Retrieving a Collection) the x:data form MUST appear as the first element in the collection after any <previous/> or <next/> elements, whatever order it was uploaded in. Upon retrieval the 'type' attribute of the form MAY be 'submit' or 'form'.

- + - http://www.xmpp.org/extensions/xep-0136.html#ns + urn:xmpp:tmp:archive 1 1 1469-07-29T12:00:00Z - O, I am fortune's fool! + O, I am fortune's fool! Why dost thou stay? ]]> -

The content of the uploaded x:data form MAY be encrypted (see Encryption).

- - - - - - - - dataKey1 - - +OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ - - - - dataKey1 - - - romeoPublicKey1fingerprint - - E5Qbvfa2gI5lBZMAHryv4g - - - +

As described in the Encryption section of this document, the content of the uploaded x:data form MAY be encrypted.

+ + + + + +

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

+
    +
  • The server MUST enable automatic archiving when each stream is opened.
    • +
  • Clients MUST NOT be allowed to disable automatic archiving.
    • +
  • Automatic archiving MUST NOT be subject to users' Archiving Preferences.
    • +
  • If the server has not received a request from a client for its user's archiving preferences (see Determining Preferences) within a few seconds of authenticating the client then the server MUST send a warning message to the client:
    • +
+ + WARNING: All messages that you send or + receive will be recorded by the server. + + ]]> +

Otherwise:

+
    +
  • Automatic archiving MUST default to disabled when each stream is opened.
    • +
  • 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 archive all active collections.
    • +
  • Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's Archiving Preferences.
    • +
  • 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.
    • +
+ + ]]> -

The x:data form MAY be removed from a collection simply by uploading an empty form. Note: The server SHOULD NOT return an error if it finds that the form to be deleted does not exist.

- - - - - - + + +

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 'message' 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 XEP-0189.

    • +
+ + + + +

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. +
  2. Retrieving a collection
    3. +
  3. Removing a collection
    4. +
+

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 &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.

+ +

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 XEP-0082). 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 rate limiting restrictions.

+ + + + 30 + + + + ]]> + + + + 30 + + + + ]]> + + + + 30 + + + + ]]> +

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

+

Note: In accordance with Result Set Management, the client MUST assume that 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:

+ + + + ]]> + + + + 30 + 1469-07-21T03:16:37Zbalcony@house.capulet.com + + + + ]]> +

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 XEP-0082). 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 rate limiting restrictions.

+ + + + 100 + + + + ]]> + + + Art thou not Romeo, and a Montague? + Neither, fair saint, if either thee dislike. + . + [98 more messages] + . + How cam'st thou hither, tell me, and wherefore? + + 0 + 99 + 217 + + + + ]]> +

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:

+ + + + 100 + + + + + + + ]]> +

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

+ + + + ]]> + + + + 100 + 99 + + + + ]]> +

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 on or 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:

+ + + + + ]]> + -

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 releases). 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 &w3xmlenc;.

-

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 &xep0189;. 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 XEP-0189 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.

- The examples above are not encrypted for clarity. However, clients SHOULD encrypt their archived collections. This section describes how to do so.

+ +

Clients SHOULD encrypt manually-archived collections (although early implementations of this protocol MAY prefer to defer encryption and decryption to later releases). 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 &w3xmlenc;.

+

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 &xep0189;. 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 XEP-0189 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.

+ - + @@ -744,39 +983,49 @@ - ]]> -

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 XEP-0189.

- - - -

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

-
    -
  • The server MUST enable automatic archiving when each stream is opened.
    • -
  • Clients MUST NOT be allowed to disable automatic archiving.
    • -
  • Automatic archiving MUST NOT be subject to users' Archiving Preferences.
    • -
  • If the server has not received a request from a client for its user's archiving preferences (see Determining Preferences) within a few seconds of authenticating the client then the server MUST send a warning message to the client:
    • -
- - WARNING: All messages that you send or - receive will be recorded by the server. - ]]> -

Otherwise:

-
    -
  • Automatic archiving MUST default to disabled when each stream is opened.
    • -
  • 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 archive all active collections.
    • -
  • Once automatic archiving is switched on then the server MUST automatically archive messages only according to the user's Archiving Preferences.
    • -
  • 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.
    • -
- - +

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 XEP-0189.

+ + + + + + + + dataKey1 + + +OGQ0SR+ysraP6LnD43m77VkIVni5c7yPeIbkFdicZ + + + + dataKey1 + + + romeoPublicKey1fingerprint + + E5Qbvfa2gI5lBZMAHryv4g + + + + + ]]> +

The x:data form MAY be removed from a collection simply by uploading an empty form. Note: The server SHOULD NOT return an error if it finds that the form to be deleted does not exist.

+ + + + + + ]]> - +

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

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 procedure 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 XEP-0189). The server MUST use them all to encrypt all the symmetric keys it generates and add these to the collection wrapped in <EncryptedKey/> elements.

@@ -784,7 +1033,7 @@ + xmlns='urn:xmpp:tmp:archive'> romeoPublicKey3fingerprint @@ -802,72 +1051,22 @@ ]]>

As soon as the server has finished archiving 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 archived).

 - -

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 'message' 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 XEP-0189.

    • -
- - - -

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. -
  2. Retrieving a collection
    3. -
  3. Removing a collection
    4. -
-

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 &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.

- -

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

- - - - 30 - - - - ]]> - - - - 30 - - - - ]]> - - - - 30 - - - - ]]> -

The server MUST list the collections (empty <chat/> 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 <chat/> element MUST be set to 'true':

+ +

If a collection contains <EncryptedData/> or <EncryptedKey/> elements then the 'crypt' attribute of the <chat/> element MUST be set to 'true':

- + + crypt='true' + version='0'/> . [28 more collections] . + start='1469-07-21T03:16:37Z' + version='4'/> 1469-07-21T02:56:15Zjuliet@capulet.com 1469-07-21T03:16:37Zbalcony@house.capulet.com @@ -876,101 +1075,12 @@ ]]> -

Note: In accordance with Result Set Management, the client MUST assume that 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:

- - - - ]]> - - - - 30 - 1469-07-21T03:16:37Zbalcony@house.capulet.com - - - - ]]> -

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

- - - - 100 - - - - ]]> - - - Art thou not Romeo, and a Montague? - Neither, fair saint, if either thee dislike. - . - [98 more messages] - . - How cam'st thou hither, tell me, and wherefore? - - 0 - 99 - 217 - - - - ]]> -

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:

- - - - 100 - - - - - - - ]]> -

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

- - - - ]]> - - - - 100 - 99 - - - - ]]> -

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.

+ +

The items in encrypted collections are typically larger than the items in an unencrypted collection, 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 rate limiting restrictions.

- @@ -982,10 +1092,11 @@

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.

- + subject='She speaks!' + version='5'> @@ -1048,7 +1159,7 @@

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.

- romeoPublicKey1fingerprint @@ -1059,94 +1170,27 @@ ]]>

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:

- - - - - - - ]]> - - - -

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:

- +

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:

+ - + romeoPublicKey1fingerprint 50 - ]]> -

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:

- +

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:

+ - + + start='1469-07-23T19:22:31Z' + version='6'> dataKey1 @@ -1174,11 +1218,11 @@ - ]]> -

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 archive it in its associated collection on the server (see Encryption):

- +

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 archive it in its associated collection on the server (see Encryption):

+ - + @@ -1203,11 +1247,11 @@ . [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:

- +

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:

+ - romeoPublicKey1fingerprint @@ -1216,60 +1260,35 @@ . [49 more delete requests] . - ]]> + ]]> + - -

This section describes how a client MAY replicate an archive locally. Clients that run in constrained environments may not be able to implement replication if they are prevented from accessing (sufficient) local storage. 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). 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.

-

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 embedded in a <modified/> element. The content of the <after/> element SHOULD be a UTC time (see XEP-0082) 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).

- + + +

A client discovers whether its server supports this protocol using &xep0030;.

+ - - - 50 - 1469-07-21T01:14:47Z - - + + ]]> -

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 XEP-0082) that the last collection on the page was modified.

- - - - . - [up to 48 more collections] - . - - - 1469-07-21T04:22:39Z - 1372 - - +

For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'urn:xmpp:tmp:archive:name' &NSNOTE;, 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, and 'pref' for the Archiving Preferences feature.

+ + + + ... + + + + + + ... + ]]> -

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

- - -

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 <chat/> elements may be stored in an archive file.

- - - - Art thou not Romeo, and a Montague? - Neither, fair saint, if either thee dislike. - How cam'st thou hither, tell me, and wherefore? - - - ]]> +

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 archived collection using client machines whose UTC clocks are not synchronized with the client machine that uploaded 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 &xep0202; to estimate the difference between the server and client UTC clocks.

@@ -1281,21 +1300,62 @@

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.

 + +

This section describes how a client can replicate an archive locally. Clients that run in constrained environments may not be able to implement replication if they are prevented from accessing (sufficient) local storage. 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). 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.

+

The client can "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 embedded in a <modified/> element. The <modified/> element MUST include a 'start' attribute that specifies a UTC datetime (see XEP-0082) that it has previously received from the server. 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).

+ + + + 50 + + + + ]]> +

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 'start' attribute 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 XEP-0082) that the last collection on the page was modified.

+ + + + . + [up to 48 more collections] + . + + + 1469-07-21T04:22:39Z + 1372 + + + + ]]> +

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

+ + -

Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "http://www.xmpp.org/extensions/xep-0136.html#ns" &NSNOTE; during stream setup (via the <feature/> element, which MUST NOT contain a <required/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include a <default/> child).

+

Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "urn:xmpp:tmp:archive" &NSNOTE; during stream setup (via the <feature/> element, which MUST NOT contain a <required/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include a <default/> child).

+ ]]> + ]]> + -

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 'logging' field defined in XEP-0155).

+

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 'logging' field defined in &xep0155;).

If a server deployment enables automatic archiving by default, then it MUST return a stream feature containing an empty <default/> element (see the Stream Feature section of this document).

 @@ -1307,28 +1367,30 @@

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

 +

No interaction with &IANA; is required as a result of this document.

 + -

Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0155.html#ns"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.

+

Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:archive"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;. The namespace "urn:xmpp:archive" is requested, and is thought to be unique per the XMPP Registrar's requirements.

 -

The XMPP Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;), where the string "http://www.xmpp.org/extensions/xep-0136.html#ns" shall be replaced with the URN issued by the XMPP Registrar:

+

The XMPP Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;), where the string "urn:xmpp:tmp:archive" shall be replaced with the URN issued by the XMPP Registrar:

    -
  • http://www.xmpp.org/extensions/xep-0136.html#ns-auto
    • -
  • http://www.xmpp.org/extensions/xep-0136.html#ns-encrypt
    • -
  • http://www.xmpp.org/extensions/xep-0136.html#ns-manage
    • -
  • http://www.xmpp.org/extensions/xep-0136.html#ns-manual
    • -
  • http://www.xmpp.org/extensions/xep-0136.html#ns-pref
    • +
  • urn:xmpp:tmp:archive:auto
    • +
  • urn:xmpp:tmp:archive:encrypt
    • +
  • urn:xmpp:tmp:archive:manage
    • +
  • urn:xmpp:tmp:archive:manual
    • +
  • urn:xmpp:tmp:archive:pref
 -

&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Message Archiving, where the FORM_TYPE "http://www.xmpp.org/extensions/xep-0136.html#ns" shall be replaced with the URN issued by the XMPP Registrar:

+

&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Message Archiving, where the FORM_TYPE "urn:xmpp:tmp:archive" shall be replaced with the URN issued by the XMPP Registrar:

- http://www.xmpp.org/extensions/xep-0136.html#ns + urn:xmpp:tmp:archive XEP-0136 Attributes of a message collection stored using Message Archiving - + + @@ -1368,6 +1431,7 @@ - auto - chat - delete + - itemremove - keys - list - modified @@ -1403,6 +1467,7 @@ + @@ -1422,6 +1487,7 @@ + @@ -1577,6 +1643,7 @@ + @@ -1601,6 +1668,14 @@ + + + + + + + + @@ -1620,6 +1695,7 @@ +