From 146da3440cd7000a3faee3c5db9715ac6d819b2d Mon Sep 17 00:00:00 2001 From: Mathijs van Gorcum Date: Thu, 14 Nov 2019 23:06:10 +0100 Subject: [PATCH 1/7] Create 2354-streaming-file-transfer.md --- proposals/2354-streaming-file-transfer.md | 133 ++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 proposals/2354-streaming-file-transfer.md diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md new file mode 100644 index 00000000..f55a5ee3 --- /dev/null +++ b/proposals/2354-streaming-file-transfer.md @@ -0,0 +1,133 @@ +# MSC2354 - Device to device streaming file transfers + +File transfer in matrix currently works by uploading a file to the server, which is then distributed over +the participating servers in the room, and is available through an HTTP get request to everyone who knows +the URL. By nescesity this has a maximum filesize and also results in a more or less permanent availablity +of said file. For larger files, and/or files that should only be sent point to point it may be desirable +to be able to send from device to device. As matrix already implements WebRTC signalling for voip, this +functionality can be replicated for streaming file transfers from device to device. It can even be possible +to send files not between devices of two matrix users, but two matrix devices owned by the same user. For +this we can use the webrtc datachannel. + + +## Proposal + +To allow the device to device streaming data tranfser we propose to add events mirroring setting up a +WebRTC VoIP session. +To start a file transfer a user first selects the file to be transferred, after which the sending client +sends an `m.d2dfile.invite` event with: + +``` +{ + "content": { + "transfer_id": "12345", + "lifetime": 60000, + "filename": "example.doc", + "info": { + "mimetype": "application/msword", + "size": 46144 + }, + "offer": { + "sdp": "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]", + "type": "offer" + }, + "version": 0 + }, + "event_id": "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@example:example.org", + "type": "m.d2dfile.invite", + + "unsigned": { + "age": 1234 + } +} +``` + +This triggers other devices in the room to alert the user about the offered transfer, displaying the filename, filetype and filesize. + +In order to establish an RTCDataChannel, the sending device can gather candidates. This is done following the spec detailing how to find a turnserver by sending an authenticated get request to `https://example.org/_matrix/client/r0/voip/turnServer`. Following the same course as used for setting up a VoIP call, this returns the address of the turnserver and a username and password. This turnserver can then be used to find the peer to peer candidates and/or a relay. Otherwise the external (possibly local) ip address can be used to create a candidate. + +These candidates are then sent using: +`m.d2dfile.candidates` with: +``` +{ + "content": { + "transfer_id": "12345", + "candidates": [ + { + "candidate": "candidate:863018703 1 tcp 2122260223 10.9.64.156 43670 typ host generation 0", + "sdpMLineIndex": 0, + "sdpMid": "0" + } + ], + "version": 0 + }, + "event_id": "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@example:example.org", + "type": "m.d2dfile.candidates", + "unsigned": { + "age": 1234 + } +} +``` + +If a device accepts the filetransfer the device in turn sends an `m.d2dfile.answer` event, containing: + +``` +{ + "content": { + "answer": { + "sdp": "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]", + "type": "answer" + }, + "transfer_id": "12345", + "lifetime": 60000, + "version": 0 + }, + "event_id": "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@example:example.org", + "type": "m.d2dfile.answer", + "unsigned": { + "age": 1234 + } +} +``` +The accepting device also sends a `m.d2dfile.candidates` in order to establish the data connection. + +To cancel a filetransfer or reject an offer the `m.d2dfile.cancel` event is sent, as follows: + +``` +{ + "content": { + "transfer_id": "12345", + "version": 0 + }, + "event_id": "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@example:example.org", + "type": "m.d2dfile.cancel", + "unsigned": { + "age": 1234 + } +} +``` + +## Potential issues +It's tempting to want to use this for device to device transfer in public rooms, but an evil homeserver could hijack the webrtc session by pretending to be a device for the intended recipient (if that user has an account on the evil server). As such this should be limited to private rooms. +Otherwise the matrix logic is quite simple here, basically following the same flow as 1:1 VoIP calls, however: most guides (including the synapse github how-to) advice to disable TCP relays in the turnserver, which may be unwanted for file transfers. + +While this proposal focusses on streaming file transfer, a webrtc datachannel could be used for any generic data transfer, for the use of any other application, such as games for instance. If such application is wanted, the d2dfile event type may be a poorly chosen name. For this proposal other uses for a webrtc datachannel is deemed out of scope. + +## Alternatives +The current way of sending files is a valid alternative, the biggest upside of adding this proposal is that this allows for streaming file transfer outside of matrix and is thus not limited in filesize and negates the need for the matrix server to host any of the files. +Since filetransfer over matrix isn't unique with the device to device transfer, and implementation of filetransfers over webrtc is probably not trivial, this feature could be marked as optional. + +## Security considerations +Using RTCDataChannel to transfer files could be abused to send malware without having the possibility of checking for this in between on the serverside. This could be mitigated similarly to how dinsinc does this, by sending the file to a virus scanning server first, but that negates (some of) the advantage of streaming filetransfers. From cd5daf735a7775dc9bfa68d62cb707ff913024c0 Mon Sep 17 00:00:00 2001 From: mvgorcum Date: Thu, 14 Nov 2019 23:16:47 +0100 Subject: [PATCH 2/7] wrap lines --- proposals/2354-streaming-file-transfer.md | 25 ++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index f55a5ee3..612daaa8 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -47,7 +47,13 @@ sends an `m.d2dfile.invite` event with: This triggers other devices in the room to alert the user about the offered transfer, displaying the filename, filetype and filesize. -In order to establish an RTCDataChannel, the sending device can gather candidates. This is done following the spec detailing how to find a turnserver by sending an authenticated get request to `https://example.org/_matrix/client/r0/voip/turnServer`. Following the same course as used for setting up a VoIP call, this returns the address of the turnserver and a username and password. This turnserver can then be used to find the peer to peer candidates and/or a relay. Otherwise the external (possibly local) ip address can be used to create a candidate. +In order to establish an RTCDataChannel, the sending device can gather candidates. +This is done following the spec detailing how to find a turnserver by sending an +authenticated get request to `https://example.org/_matrix/client/r0/voip/turnServer`. +Following the same course as used for setting up a VoIP call, this returns +the address of the turnserver and a username and password. This turnserver can then be used +to find the peer to peer candidates and/or a relay. Otherwise the external (possibly local) +ip address can be used to create a candidate. These candidates are then sent using: `m.d2dfile.candidates` with: @@ -120,10 +126,19 @@ To cancel a filetransfer or reject an offer the `m.d2dfile.cancel` event is sent ``` ## Potential issues -It's tempting to want to use this for device to device transfer in public rooms, but an evil homeserver could hijack the webrtc session by pretending to be a device for the intended recipient (if that user has an account on the evil server). As such this should be limited to private rooms. -Otherwise the matrix logic is quite simple here, basically following the same flow as 1:1 VoIP calls, however: most guides (including the synapse github how-to) advice to disable TCP relays in the turnserver, which may be unwanted for file transfers. - -While this proposal focusses on streaming file transfer, a webrtc datachannel could be used for any generic data transfer, for the use of any other application, such as games for instance. If such application is wanted, the d2dfile event type may be a poorly chosen name. For this proposal other uses for a webrtc datachannel is deemed out of scope. +It's tempting to want to use this for device to device transfer in public rooms, +but an evil homeserver could hijack the webrtc session by pretending to be a device +for the intended recipient (if that user has an account on the evil server). As such this +should be limited to private rooms. +Otherwise the matrix logic is quite simple here, basically following the same flow as 1:1 VoIP calls, +however: most guides (including the synapse github how-to) advice to disable TCP relays in the turnserver, +which may be unwanted for file transfers. + +While this proposal focusses on streaming file transfer, +a webrtc datachannel could be used for any generic data transfer, +for the use of any other application, such as games for instance. +If such application is wanted, the d2dfile event type may be a poorly chosen name. +For this proposal other uses for a webrtc datachannel is deemed out of scope. ## Alternatives The current way of sending files is a valid alternative, the biggest upside of adding this proposal is that this allows for streaming file transfer outside of matrix and is thus not limited in filesize and negates the need for the matrix server to host any of the files. From 85a7c9830ec1636a53e1d1a846804c1e69c048c2 Mon Sep 17 00:00:00 2001 From: mvgorcum Date: Thu, 14 Nov 2019 23:17:54 +0100 Subject: [PATCH 3/7] wrap all lines --- proposals/2354-streaming-file-transfer.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index 612daaa8..3bd47194 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -141,8 +141,17 @@ If such application is wanted, the d2dfile event type may be a poorly chosen nam For this proposal other uses for a webrtc datachannel is deemed out of scope. ## Alternatives -The current way of sending files is a valid alternative, the biggest upside of adding this proposal is that this allows for streaming file transfer outside of matrix and is thus not limited in filesize and negates the need for the matrix server to host any of the files. -Since filetransfer over matrix isn't unique with the device to device transfer, and implementation of filetransfers over webrtc is probably not trivial, this feature could be marked as optional. +The current way of sending files is a valid alternative, +the biggest upside of adding this proposal is that this allows for +streaming file transfer outside of matrix and is thus not limited in filesize +and negates the need for the matrix server to host any of the files. +Since filetransfer over matrix isn't unique with the device to device transfer, +and implementation of filetransfers over webrtc is probably not trivial, +this feature could be marked as optional. ## Security considerations -Using RTCDataChannel to transfer files could be abused to send malware without having the possibility of checking for this in between on the serverside. This could be mitigated similarly to how dinsinc does this, by sending the file to a virus scanning server first, but that negates (some of) the advantage of streaming filetransfers. +Using RTCDataChannel to transfer files could be abused to send malware +without having the possibility of checking for this in between on the serverside. +This could be mitigated similarly to how dinsinc does this, +by sending the file to a virus scanning server first, +but that negates (some of) the advantage of streaming filetransfers. From 3920aa042e5b44b0d5408fa3ef669cf749767ce7 Mon Sep 17 00:00:00 2001 From: Mathijs van Gorcum Date: Fri, 15 Nov 2019 09:14:19 +0100 Subject: [PATCH 4/7] add link to voip spec, add potential issues --- proposals/2354-streaming-file-transfer.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index 3bd47194..24ece286 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -4,7 +4,8 @@ File transfer in matrix currently works by uploading a file to the server, which the participating servers in the room, and is available through an HTTP get request to everyone who knows the URL. By nescesity this has a maximum filesize and also results in a more or less permanent availablity of said file. For larger files, and/or files that should only be sent point to point it may be desirable -to be able to send from device to device. As matrix already implements WebRTC signalling for voip, this +to be able to send from device to device. As matrix already implements +[WebRTC signalling for voip](https://matrix.org/docs/spec/client_server/r0.6.0#voice-over-ip), this functionality can be replicated for streaming file transfers from device to device. It can even be possible to send files not between devices of two matrix users, but two matrix devices owned by the same user. For this we can use the webrtc datachannel. @@ -13,7 +14,8 @@ this we can use the webrtc datachannel. ## Proposal To allow the device to device streaming data tranfser we propose to add events mirroring setting up a -WebRTC VoIP session. +WebRTC VoIP session. + To start a file transfer a user first selects the file to be transferred, after which the sending client sends an `m.d2dfile.invite` event with: @@ -134,6 +136,11 @@ Otherwise the matrix logic is quite simple here, basically following the same fl however: most guides (including the synapse github how-to) advice to disable TCP relays in the turnserver, which may be unwanted for file transfers. +Both sender and reciever need to be online simultaniously for this mode of file transfer +to work, which is unexpected in the context of the existing matrix file transfer. + +This file transfer will only send the file once, from one device to another. + While this proposal focusses on streaming file transfer, a webrtc datachannel could be used for any generic data transfer, for the use of any other application, such as games for instance. @@ -152,6 +159,6 @@ this feature could be marked as optional. ## Security considerations Using RTCDataChannel to transfer files could be abused to send malware without having the possibility of checking for this in between on the serverside. -This could be mitigated similarly to how dinsinc does this, +This could be mitigated similarly to how DINUM does this, by sending the file to a virus scanning server first, but that negates (some of) the advantage of streaming filetransfers. From dd09f5bf084c60e8f99a1910f952c25be1bf2acb Mon Sep 17 00:00:00 2001 From: Mathijs van Gorcum Date: Fri, 26 Feb 2021 23:05:48 +0100 Subject: [PATCH 5/7] Update proposals/2354-streaming-file-transfer.md Co-authored-by: Jonathan de Jong --- proposals/2354-streaming-file-transfer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index 24ece286..b17949b1 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -3,7 +3,7 @@ File transfer in matrix currently works by uploading a file to the server, which is then distributed over the participating servers in the room, and is available through an HTTP get request to everyone who knows the URL. By nescesity this has a maximum filesize and also results in a more or less permanent availablity -of said file. For larger files, and/or files that should only be sent point to point it may be desirable +of said file. For larger files, and/or files that should only be sent from point-to-point, it may be desirable to be able to send from device to device. As matrix already implements [WebRTC signalling for voip](https://matrix.org/docs/spec/client_server/r0.6.0#voice-over-ip), this functionality can be replicated for streaming file transfers from device to device. It can even be possible From b64f3e2204ef1c7f15458ec17cb79933e94c2c71 Mon Sep 17 00:00:00 2001 From: Mathijs van Gorcum Date: Fri, 26 Feb 2021 23:06:11 +0100 Subject: [PATCH 6/7] Update proposals/2354-streaming-file-transfer.md Co-authored-by: Jonathan de Jong --- proposals/2354-streaming-file-transfer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index b17949b1..efdd9ca6 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -2,7 +2,7 @@ File transfer in matrix currently works by uploading a file to the server, which is then distributed over the participating servers in the room, and is available through an HTTP get request to everyone who knows -the URL. By nescesity this has a maximum filesize and also results in a more or less permanent availablity +the URL. By necessity this has a maximum filesize and also results in a more or less permanent availability of said file. For larger files, and/or files that should only be sent from point-to-point, it may be desirable to be able to send from device to device. As matrix already implements [WebRTC signalling for voip](https://matrix.org/docs/spec/client_server/r0.6.0#voice-over-ip), this From 648f5507e62d9fce4442fdf28f34714ee29a7a04 Mon Sep 17 00:00:00 2001 From: Mathijs van Gorcum Date: Tue, 16 Mar 2021 01:01:23 +0100 Subject: [PATCH 7/7] Update proposals/2354-streaming-file-transfer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Erkin Alp Güney --- proposals/2354-streaming-file-transfer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2354-streaming-file-transfer.md b/proposals/2354-streaming-file-transfer.md index efdd9ca6..f017f163 100644 --- a/proposals/2354-streaming-file-transfer.md +++ b/proposals/2354-streaming-file-transfer.md @@ -136,7 +136,7 @@ Otherwise the matrix logic is quite simple here, basically following the same fl however: most guides (including the synapse github how-to) advice to disable TCP relays in the turnserver, which may be unwanted for file transfers. -Both sender and reciever need to be online simultaniously for this mode of file transfer +Both sender and reciever need to be online simultaneously for this mode of file transfer to work, which is unexpected in the context of the existing matrix file transfer. This file transfer will only send the file once, from one device to another.