-
Notifications
You must be signed in to change notification settings - Fork 118
/
xep-0447.xml
423 lines (418 loc) · 27.5 KB
/
xep-0447.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Stateless file sharing</title>
<abstract>This specification describes a protocol for stateless asynchronous file sharing with integrity and transport flexibility. It allows clients to provide a good interoperable user experience in combination with Carbons and MAM.</abstract>
&LEGALNOTICE;
<number>0447</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0446</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>sfs</shortname>
&larma;
<revision>
<version>0.3.1</version>
<date>2024-01-01</date>
<initials>lmw</initials>
<remark>Fix example for multiple files.</remark>
</revision>
<revision>
<version>0.3.0</version>
<date>2023-06-24</date>
<initials>lmw</initials>
<remark>Describe how to use for multiple files, with body text, without any source in original message and compatibility with various current deployed protocols.</remark>
</revision>
<revision>
<version>0.2.0</version>
<date>2022-08-03</date>
<initials>lmw</initials>
<remark>Add disposition attribute to signal when inlining is desired.</remark>
</revision>
<revision>
<version>0.1.2</version>
<date>2022-02-10</date>
<initials>egp</initials>
<remark>Replace the ProtoXEP reference with a reference to the published XEP.</remark>
</revision>
<revision>
<version>0.1.1</version>
<date>2020-12-30</date>
<initials>ps</initials>
<remark>Fixed typo in example.</remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2020-11-24</date>
<initials>XEP Editor (jsc)</initials>
<remark>Accepted by vote of Council on 2020-11-18.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2020-11-10</date>
<initials>lmw</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
This is a reiteration on &xep0385; with some significant changes:
</p>
<ul>
<li>No focus on media, generic for every file type.</li>
<li>Body can be used for fallback.</li>
<li>Using &xep0446;.</li>
<li>Using XML for structured data instead of URIs when possible, adding further extensibility (like providing proper means of sharing encrypted files on http servers).</li>
<li>Not relying on underspecified usage of &xep0372;.</li>
</ul>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<ul>
<li>Do not require any server components for easier deployment</li>
<li>Should work and enable a good UX in multi-user chats like &xep0045; and &xep0369;</li>
<li>Should work great together with conversation synchronization protocols like &xep0280; and &xep0313;</li>
<li>Reuse existing protocols for the actual transport of the data, i.e. &xep0234; or &xep0363;</li>
<li>Guarantee file integrity</li>
<li>Enable aggresive caching</li>
<li>Provide users with metadata, e.g. file size, file type or thumbnail, to help them decide whether or not they want to load the file</li>
<li>Support referring to third party hosting services</li>
<li>Backwards compatibility with existing protocols</li>
</ul>
</section1>
<section1 topic='Basic use cases' anchor='basic'>
<section2 topic='Sharing a file' anchor='file-sharing'>
<p>
To share a file, a user sends a message stanza including <tt><file-sharing/></tt> to the inteded recipient contact or group.
The <tt><file-sharing/></tt> element MAY have a <tt>disposition</tt> attribute with a value of either <tt>attachment</tt> or <tt>inline</tt> and MAY have an <tt>id</tt> attribute.
The <tt><file-sharing/></tt> element includes a <tt><file/></tt> metadata element as described in &xep0446; and MAY include a <tt><sources/></tt> element.
The <tt><sources/></tt> element provides one or multiple sources that the receiving client may use to obtain the file.
</p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<file xmlns='urn:xmpp:file:metadata:0'>
<media-type>image/jpeg</media-type>
<name>summit.jpg</name>
<size>3032449</size>
<width>4096</width>
<height>2160</height>
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<desc>Photo from the summit.</desc>
<thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</file>
<sources>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' />
<jinglepub xmlns='urn:xmpp:jinglepub:1' from='romeo@montague.lit/resource' id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5' />
</jinglepub>
</sources>
</file-sharing>
</message>]]></example>
<p>
It is RECOMMENDED that the file metadata specifies name, media-type, size and one or multiple hash elements as described in &xep0300;.
The hash elements provide end-to-end file integrity and allow efficient caching and flexible retrieval methods.
</p>
<p>
The message MAY include a suitable fallback body.
When doing so, an appropriate &xep0428; <tt><fallback/></tt> indicator with <tt>for</tt> set to <tt>urn:xmpp:sfs:0</tt> MUST be added.
The fallback body MUST NOT include any information that is not also represented in <tt><file-sharing/></tt>.
If the <tt><sources/></tt> element includes an <tt><url-data/></tt> element that can be represented as a single URL, adding a &xep0066; x-oob reference is RECOMMENDED for compatibility.
</p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit with fallback'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<!-- ... -->
</file-sharing>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</url></x>
</message>]]></example>
<p>If the message has an empty body, it is RECOMMENDED to add a message processing hint, see &xep0334;, to indicate the message to be stored in message stores like &xep0313;.</p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit without fallback'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<!-- ... -->
</file-sharing>
<store xmlns='urn:xmpp:hints' />
</message>]]></example>
</section2>
<section2 topic='Receiving a file' anchor='file-receive'>
<p>
On receive of a message including a <tt><file-sharing/></tt> 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.
</p>
<p>
If the file is not available locally, the file can be obtained by one of the sources listed in the <tt><sources/></tt> element.
If further sources have been attached (as described in <link url="#attach-source">Attaching a source</link>), the receiving entity may also try to obtain the file from any of those.
If no <tt><sources/></tt> element is included with the message containing the <tt><file-sharing/></tt> element, the receiving entity SHOULD consider the file transfer pending and expect an attached source later.
</p>
<p>
The receiving entity SHOULD NOT fetch the file without prior user interaction if the <tt>disposition</tt> attribute is set to <tt>attachment</tt>.
The receiving entity MAY fetch the file without prior user interaction otherwise, but when doing so, user's privacy, security (see <link url="#security">Security Considerations</link>) and network constraints should be considered.
</p>
<p>
When the source is an <tt><url-data/></tt> element as described in &xep0103;, the receiving entity MAY obtain the file by downloading it from the specified URL.
If the URL uses HTTP or HTTPS and additional HTTP request information as specified in &xep0104; is provided, the receiving entity SHOULD use such information when obtaining the file.
When sending and receiving files using <tt><url-data/></tt>, it is RECOMMENDED to prefer secure protocols (e.g. HTTPS, FTPS).
Please read <link url="#security">security considerations</link> when implementing support for insecure URLs.
</p>
<p>
When the source is a <tt><jingle-pub/></tt> element as described in &xep0358;, the receiving entity MAY obtain the file using the protocol described in &xep0358;.
If a <tt><hash/></tt> is provided, the receiving entity MAY obtain the file by requesting it as described in &xep0234;.
</p>
<p>
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.
</p>
<p>
The intended method to provide or display a file to the user depends on the <tt>disposition</tt> attribute, <tt><media-type/></tt> and file type support of the receiving entity:
</p>
<ul>
<li>If the <tt>disposition</tt> attribute is set to <tt>attachment</tt>, no <tt><media-type/></tt> is provided or the <tt><media-type/></tt> indicates that the file can not be displayed inline, i.e. when the media type is <tt>application/octet-stream</tt>, the receiving entity SHOULD NOT display the file inline and instead offer to download it or save it on the user's file system.</li>
<li>If the <tt>disposition</tt> attribute is set to <tt>inline</tt>, the receiving entity SHOULD attempt to display the file inline. When displaying the file inline fails, the receiving entity SHOULD indicate to the user that the file was meant to be displayed inline but that the file type was not supported for inline display and offer to open the file using an external viewer or to download the file or save it to the user's file system instead.</li>
<li>If no <tt>disposition</tt> attribute is set and the <tt><media-type/></tt> of the shared file indicates that it can be displayed inline, the receiving entity MAY display the file inline. When displaying the file inline fails, the receiving entity SHOULD NOT display any error and instead offer to open the file using an external viewer or to download the file or safe it to the user's file system.</li>
</ul>
</section2>
<section2 topic='Attaching a source' anchor='attach-source'>
<p class='box'>TODO: The following section relies on &xep0367;, however other methods to attach information to another message like the recently proposed &xep0422; might be suitable here as well. This is to be clarified before advancing to Draft.</p>
<p>
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.
</p>
<p>
The entity MUST NOT announce itself as an additional source before verifying that <em>all</em> hashes provided match the hash of the file.
If no hashes are provided, the entity SHOULD NOT announce itself as an additional source.
</p>
<p>
The attaching itself is performed by sending a message including a <tt><sources></tt> element with further sources using the protocol described in &xep0367;.
If the <tt><file-sharing/></tt> element to attach to had an <tt>id</tt> attribute, the <tt><sources></tt> element MUST also have an <tt>id</tt> attribute with the same value.
</p>
<p>Depending on the lifetime of the newly attached source, it may be useful to add a message processing hint, see &xep0334;, to indicate the message to be stored in message stores like &xep0313;.</p>
<example caption='romeo@montague.lit/resource2 attaches itself as an additional source for the file'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource2'>
<attach-to id='sharing-a-file' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0'>
<jinglepub xmlns='urn:xmpp:jinglepub:1' from='romeo@montague.lit/resource2' id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5' />
</jinglepub>
</sources>
<store xmlns='urn:xmpp:hints' />
</message>]]></example>
<p>
If the file was originally shared without a <tt><sources/></tt> element, the sending entity SHOULD attach a file source at a later point.
For example, the sending entity may send a message with a <tt><file-sharing/></tt> element without a <tt><sources/></tt> element, when it starts uploading a file to the server (using &xep0363;) and then attach the http source as soon as the upload is finished.
</p>
<p>
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 &xep0428; <tt><fallback/></tt> indicator with <tt>for</tt> set to <tt>urn:xmpp:sfs:0</tt> MUST be added.
The fallback body MUST NOT include any information that is not also represented in <tt><sources/></tt>.
If the <tt><sources/></tt> element includes an <tt><url-data/></tt> element that can be represented as a single URL, adding a &xep0066; x-oob reference is RECOMMENDED for compatibility.
</p>
<example caption='Sharing a file and attaching the primary source for the file later, including a fallback body.'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline' id='file-sharing-id'>
<file xmlns='urn:xmpp:file:metadata:0'>
<media-type>image/jpeg</media-type>
<name>summit.jpg</name>
<size>3032449</size>
<width>4096</width>
<height>2160</height>
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<desc>Photo from the summit.</desc>
<thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</file>
</file-sharing>
</message>
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource'>
<attach-to id='sharing-a-file' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0' id='file-sharing-id'>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' />
</sources>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</url></x>
</message>]]></example>
</section2>
</section1>
<section1 topic='Advanced use cases' anchor='advanced'>
<section2 topic='Sharing a file with additional body' anchor='body'>
<p>
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 <tt><file-sharing/></tt> element.
</p>
<p>
If a <tt><file-sharing/></tt> message includes a textual body, it MAY also include a fallback in that body, that MUST be annotated using an appropriate &xep0428; <tt><fallback/></tt> indicator with <tt>for</tt> set to <tt>urn:xmpp:sfs:0</tt>.
However, in this case it is RECOMMENDED to use a source attaching message with a fallback body. This allows to send messages in a way that is still understood well by legacy clients.
</p>
<example caption='Sharing a file with additional body and attaching a source with fallback'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<body>Summit was great, check out this cool photo of everyone.</body>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<file xmlns='urn:xmpp:file:metadata:0'>
<media-type>image/jpeg</media-type>
<name>summit.jpg</name>
<size>3032449</size>
<width>4096</width>
<height>2160</height>
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<desc>Photo from the summit.</desc>
<thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</file>
</file-sharing>
</message>
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='adding-the-source'>
<attach-to id='sharing-a-file' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0'>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' />
</sources>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</url></x>
</message>]]></example>
</section2>
<section2 topic='Sharing multiple files' anchor='multi-file'>
<p>
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 <tt><file-sharing/></tt> elements in a single message.
It MUST add an <tt>id</tt> attribute with differing values to each of these <tt><file-sharing/></tt> elements.
</p>
<p>
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.
</p>
<example caption='Sharing multiple files and attaching sources with fallback'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-files'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline' id='photo1.jpg'>
<file xmlns='urn:xmpp:file:metadata:0'>
<name>photo1.jpg</name>
</file>
</file-sharing>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline' id='photo2.jpg'>
<file xmlns='urn:xmpp:file:metadata:0'>
<name>photo2.jpg</name>
</file>
</file-sharing>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline' id='photo3.jpg'>
<file xmlns='urn:xmpp:file:metadata:0'>
<name>photo3.jpg</name>
</file>
</file-sharing>
</message>
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='adding-photo1'>
<attach-to id='sharing-files' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0' id='photo1.jpg'>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo1.jpg' />
</sources>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo1.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo1.jpg</url></x>
</message>
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='adding-photo2'>
<attach-to id='sharing-files' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0' id='photo2.jpg'>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo2.jpg' />
</sources>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo2.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo2.jpg</url></x>
</message>
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='adding-photo3'>
<attach-to id='sharing-files' xmlns='urn:xmpp:message-attaching:1'/>
<sources xmlns='urn:xmpp:sfs:0' id='photo3.jpg'>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo3.jpg' />
</sources>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo3.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/photo3.jpg</url></x>
</message>]]></example>
</section2>
<section2 topic='Compatibility with Stateless Inline Media Sharing' anchor='sims'>
<p>
When sharing media, the sending entity may want to be compatible with &xep0385; as far as applicable.
To do so, the &xep0385; <tt><media-sharing/></tt> element can be added inside an &xep0372; <tt><reference xmlns='urn:xmpp:reference:0' type='data'></tt> element in the same message that would also include the textual legacy fallback and &xep0066; x-oob reference.
</p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit in full compatibility mode'><![CDATA[<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<file xmlns='urn:xmpp:file:metadata:0'>
<media-type>image/jpeg</media-type>
<name>summit.jpg</name>
<size>3032449</size>
<width>4096</width>
<height>2160</height>
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<desc>Photo from the summit.</desc>
<thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</file>
<sources>
<url-data xmlns='http://jabber.org/protocol/url-data' target='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' />
<jinglepub xmlns='urn:xmpp:jinglepub:1' from='romeo@montague.lit/resource' id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5' />
</jinglepub>
</sources>
</file-sharing>
<reference xmlns='urn:xmpp:reference:0' type='data'>
<media-sharing xmlns='urn:xmpp:sims:1'>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<media-type>image/jpeg</media-type>
<name>summit.jpg</name>
<size>3032449</size>
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<thumbnail xmlns='urn:xmpp:thumbs:1' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</file>
<sources>
<reference uri='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' type='data' xmlns='urn:xmpp:reference:0' />
</sources>
</media-sharing>
</reference>
<fallback xmlns='urn:xmpp:fallback:0' for='urn:xmpp:sfs:0'><body/></fallback>
<body>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body>
<x xmlns='jabber:x:oob'><url>https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</url></x>
</message>]]></example>
</section2>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
<p>Entities that support displaying moving images inline SHOULD have an option to turn this functionality off and display a still image instead.</p>
<p>Entities that support displaying files inline SHOULD have an option to turn this functionality off entirely.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>
If a <tt><hash/></tt> using any supported algorithm is provided, the receiving client SHOULD verify that the <tt><hash/></tt> of the announced file matches the obained file before presenting it to the user.
If no <tt><hash/></tt> is provided or the <tt><hash/></tt> 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 <tt><hash/></tt> is provided or the <tt><hash/></tt> elements provided use unsupported algorithms, receiving clients MUST ignore any sources that use unsecure protocols (e.g. HTTP without TLS).
</p>
<p>
For most methods of transferring a file proposed through the <tt><sources/></tt> 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.
</p>
<p>
The security considerations of &xep0446; apply.
</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>The ®ISTRAR; includes 'urn:xmpp:sfs:0' in its registry of protocol namespaces (see &NAMESPACES;).</p>
<ul>
<li>urn:xmpp:sfs:0</li>
</ul>
</section2>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to the authors of &xep0385; which heavily inspired this XEP.</p>
<p>Thanks to Jérôme Poisson and others for their valuable feedback.</p>
</section1>
</xep>