First draft.
This is a reiteration on Stateless Inline Media Sharing (XEP-0385)
To share a file, a user sends a message stanza including <file-sharing/> to the inteded recipient contact or group.
The <file-sharing/> element MAY have a disposition attribute with a value of either attachment or inline and MAY have an id attribute.
The <file-sharing/> element includes a <file/> metadata element as described in File metadata element (XEP-0446)
It is RECOMMENDED that the file metadata specifies name, media-type, size and one or multiple hash elements as described in Use of Cryptographic Hash Functions in XMPP (XEP-0300)
The message MAY include a suitable fallback body.
When doing so, an appropriate Fallback Indication (XEP-0428)
If the message has an empty body, it is RECOMMENDED to add a message processing hint, see Message Processing Hints (XEP-0334)
On receive of a message including a <file-sharing/> element, the receiving entity SHOULD lookup in a local storage, whether the file with any of the proivded hashes has already been retrieved and is available. In that case no transfer needs to be initated and the cached file can be used instead.
If the file is not available locally, the file can be obtained by one of the sources listed in the <sources/> element. If further sources have been attached (as described in Attaching a source), the receiving entity may also try to obtain the file from any of those. If no <sources/> element is included with the message containing the <file-sharing/> element, the receiving entity SHOULD consider the file transfer pending and expect an attached source later.
The receiving entity SHOULD NOT fetch the file without prior user interaction if the disposition attribute is set to attachment. The receiving entity MAY fetch the file without prior user interaction otherwise, but when doing so, user's privacy, security (see Security Considerations) and network constraints should be considered.
When the source is an <url-data/> element as described in URL Address Information (XEP-0103)
When the source is a <jingle-pub/> element as described in Publishing Available Jingle Sessions (XEP-0358)
If sources of any other type are provided, clients MAY attempt to obtain the files from such sources. The details of obtaining such file are out of scope of this document.
The intended method to provide or display a file to the user depends on the disposition attribute, <media-type/> and file type support of the receiving entity:
TODO: The following section relies on Message Attaching (XEP-0367)
After a user shared a file using one entity and another entity in the conversation obtained it, found it in its local storage or knows a remote location that provides the same file, that entity MAY announce that the file is now available with an additional source. This increases availability of the file in case the sender goes offline before all the intended recipients were able to fetch the file. It also allows for peer-to-peer file distribution in group chats.
The entity MUST NOT announce itself as an additional source before verifying that all hashes provided match the hash of the file. If no hashes are provided, the entity SHOULD NOT announce itself as an additional source.
The attaching itself is performed by sending a message including a <sources> element with further sources using the protocol described in Message Attaching (XEP-0367)
Depending on the lifetime of the newly attached source, it may be useful to add a message processing hint, see Message Processing Hints (XEP-0334)
If the file was originally shared without a <sources/> element, the sending entity SHOULD attach a file source at a later point.
For example, the sending entity may send a message with a <file-sharing/> element without a <sources/> element, when it starts uploading a file to the server (using HTTP File Upload (XEP-0363)
If the file was originally shared without a suitable fallback body, e.g. because the file was not yet uploaded at the time, the source attaching message MAY include a suitable fallback body.
When doing so, an appropriate Fallback Indication (XEP-0428)
When sharing files, the sending entity MAY want to include an additional textual message with the file share. To do so, the sending entity SHOULD add such textual message in the body of the message that contains the <file-sharing/> element.
If a <file-sharing/> message includes a textual body, it MAY also include a fallback in that body, that MUST be annotated using an appropriate Fallback Indication (XEP-0428)
When sharing files, the sending entity MAY want to share multiple files within a single message. To do so, the sending entity SHOULD add multiple <file-sharing/> elements in a single message. It MUST add an id attribute with differing values to each of these <file-sharing/> elements.
When sharing multiple files, it is RECOMMENDED to attach the sources of each file in an individual message. When doing so, it is RECOMMENDED to include appropriate fallbacks to the source attaching messages. This allows to send multiple files in a way that is still understood well by legacy clients.
When sharing media, the sending entity may want to be compatible with Stateless Inline Media Sharing (XEP-0385)
Entities that support displaying moving images inline SHOULD have an option to turn this functionality off and display a still image instead.
Entities that support displaying files inline SHOULD have an option to turn this functionality off entirely.
If a <hash/> using any supported algorithm is provided, the receiving client SHOULD verify that the <hash/> of the announced file matches the obained file before presenting it to the user. If no <hash/> is provided or the <hash/> elements provided use unsupported algorithms, receiving clients MUST ignore any attached sources from other senders and only obtain the file from the sources announced by the original sender. If no <hash/> is provided or the <hash/> elements provided use unsupported algorithms, receiving clients MUST ignore any sources that use unsecure protocols (e.g. HTTP without TLS).
For most methods of transferring a file proposed through the <sources/> element, obtaining files requires revealing private information like IP addresses to the sending user or third-parties. Sources that do not require revealing private information to untrusted entities SHOULD be preferred by receiving entitites. Receiving entities SHOULD ask users for confirmation before obtaining a file, if doing so would require revealing private information to untrusted entities. If the protocol that is used when obtaining the file is not secure (e.g. HTTP without TLS), this SHOULD be considered as if the protocol reveals private information.
The security considerations of File metadata element (XEP-0446)
This document requires no interaction with the Internet Assigned Numbers Authority (IANA)
The XMPP Registrar
Thanks to the authors of Stateless Inline Media Sharing (XEP-0385)
Thanks to Jérôme Poisson and others for their valuable feedback.