Skip to content

Changes

Page history
Update jinglefiletransfer authored by Daniel Brötzmann's avatar Daniel Brötzmann
Hide whitespace changes
Inline Side-by-side
development/jinglefiletransfer.markdown
View page @ d749be08
# Jingle File Transfer
[Jingle](https://xmpp.org/extensions/xep-0166.html) is a new protocol for negotiating data channels between XMPP entities. These include but are not limited to audio/video and other data transfer such as file data. Gajim now supports audio/video and file transfer over jingle as well. Depending on the peer, Gajim will try negotiating a jingle file transfer session first, or, if the peer does not support jingle, fall back to [SI file transfer](https://xmpp.org/extensions/xep-0096.html). [Jingle (XEP-0166)](https://xmpp.org/extensions/xep-0166.html) is a new protocol for negotiating data channels between XMPP entities. These include but are not limited to audio/video and other data transfer such as file data. Gajim now supports audio/video and file transfer over jingle as well. Depending on the peer, Gajim will try negotiating a jingle file transfer session first, or, if the peer does not support jingle, fall back to [SI File Transfer (XEP-0096)](https://xmpp.org/extensions/xep-0096.html).
## Implementation ## Implementation
Gajim's jingle currently supports [socks5 transport method](https://xmpp.org/extensions/xep-0260.html), the transmission might be routed through a proxy. Gajim has a very modularized implementation of socks5 transport dedicated to file transfer, once the session has been negotiated, the client (as in the file transfer, the client is the one who is receiving the file) tries to connect to all candidates that it knows, while the server listens on the file transfer port. After the connection is established, the reading, writing to file process is automatically managed by socks5 transport implementation. So this part is actually quite straight forward, attention should be paid to various callbacks and routines as previous implementation assumes SI file transfer to be the only way to transfer a file. (eg. callbacks for user accepting a file in the GUI needs to distinguish between a jingle file transfer and a SI file transfer and then send appropriate session-accept message). Gajim's jingle currently supports [Socks5 Transport Method (XEP-0260)](https://xmpp.org/extensions/xep-0260.html), the transmission might be routed through a proxy. Gajim has a very modularized implementation of socks5 transport dedicated to file transfer, once the session has been negotiated, the client (as in the file transfer, the client is the one who is receiving the file) tries to connect to all candidates that it knows, while the server listens on the file transfer port. After the connection is established, the reading, writing to file process is automatically managed by socks5 transport implementation. So this part is actually quite straight forward, attention should be paid to various callbacks and routines as previous implementation assumes SI file transfer to be the only way to transfer a file. (For example callbacks for user accepting a file in the GUI needs to distinguish between a jingle file transfer and a SI file transfer and then send appropriate session-accept message.)
In order to manage file transfer session in the jingle session stack, a new JingleFileTransfer content class is implemented to generate and manage file transfer sessions. It essentially manages the information of the file being transferred and the state of jingle session, generates appropriate xml stanza, and properly handle certain stanza arrival events. The original jingle implementation ignored iq-result stanza so it was not able to dispatch that event to lower applications, but in order to avoid certain race conditions, certain actions should not be taken until Gajim knows that the peer has received the message and supposedly taken certain actions. (eg. connection to peer (server) for file transfer should not commence until the session-accept stanza is confirmed, otherwise we get a connection refused error etc.). This situation is now avoided by letting the session collect IDs of interested stanzas, iq-result confirmation to those stanzas will be dispatched when received. This adds complexity in terms of both implementation and developer book-keeping, but we don't want to really dispatch every iq-result stanza because that may cause efficiency issues. In order to manage file transfer session in the jingle session stack, a new JingleFileTransfer content class is implemented to generate and manage file transfer sessions. It essentially manages the information of the file being transferred and the state of jingle session, generates appropriate xml stanza, and properly handle certain stanza arrival events. The original jingle implementation ignored iq-result stanza so it was not able to dispatch that event to lower applications, but in order to avoid certain race conditions, certain actions should not be taken until Gajim knows that the peer has received the message and supposedly taken certain actions. (eg. connection to peer (server) for file transfer should not commence until the session-accept stanza is confirmed, otherwise we get a connection refused error etc.). This situation is now avoided by letting the session collect IDs of interested stanzas, iq-result confirmation to those stanzas will be dispatched when received. This adds complexity in terms of both implementation and developer book-keeping, but we don't want to really dispatch every iq-result stanza because that may cause efficiency issues.
## XTLS ## XTLS
Security has always been a concern for instant messaging applications. Among numerous encryption schemes, SSL/TLS has been the most popular one. [jingle XTLS](https://xmpp.org/extensions/inbox/jingle-xtls.html) is an effort to bring TLS to jingle sessions. The key element added is a security node indicating the initiator's wish to use TLS enabled channels. If the peer does not support jingle-xtls, it is simply ignored and session-accept is sent without such a node. This tells the initiator that the peer does not support jingle-xtls and lets the initiator decide either to end session or to continue without session encryption. As far as Gajim is concerned, it falls back to jingle file transfer without XTLS and continues the session. OpenSSL(PyOpenSSL) has an excellent implementation of TLS protocols that wraps around the common socket object. This is easily incorporated into an existing network application. Note however, read/write operations on the TLS socket object might throw exceptions indicating that the peer wants a rehandshake, and this might happen anytime during the session. When this happens, the application is supposed to do the same I/O that triggered the exception and the read/write should succeed. Gajim also asks for peer certificate before the actual connection happens, and session-acceptance won't be sent until we receive the peer's certificate. This is simply implemented by checking if a the ID of a certain reply to key-request correspond to a pending file transfer session. Security has always been a concern for instant messaging applications. Among numerous encryption schemes, SSL/TLS has been the most popular one. [Jingle XTLS](https://xmpp.org/extensions/inbox/jingle-xtls.html) is an effort to bring TLS to jingle sessions. The key element added is a security node indicating the initiator's wish to use TLS enabled channels. If the peer does not support jingle-xtls, it is simply ignored and session-accept is sent without such a node. This tells the initiator that the peer does not support jingle-xtls and lets the initiator decide either to end session or to continue without session encryption. As far as Gajim is concerned, it falls back to jingle file transfer without XTLS and continues the session. OpenSSL(PyOpenSSL) has an excellent implementation of TLS protocols that wraps around the common socket object. This is easily incorporated into an existing network application. Note however, read/write operations on the TLS socket object might throw exceptions indicating that the peer wants a rehandshake, and this might happen anytime during the session. When this happens, the application is supposed to do the same I/O that triggered the exception and the read/write should succeed. Gajim also asks for peer certificate before the actual connection happens, and session-acceptance won't be sent until we receive the peer's certificate. This is simply implemented by checking if a the ID of a certain reply to key-request correspond to a pending file transfer session.
## Appendix ## Appendix
[xep-0116 jingle](https://xmpp.org/extensions/xep-0166.html) [XEP-0116 jingle](https://xmpp.org/extensions/xep-0166.html)
[xep-0234 jingle file transfer](https://xmpp.org/extensions/xep-0234.html) [XEP-0234 jingle file transfer](https://xmpp.org/extensions/xep-0234.html)
[xep-0260 Jingle SOCKS5 Bytestreams Transport Method](https://xmpp.org/extensions/xep-0260.html) [XEP-0260 Jingle SOCKS5 Bytestreams Transport Method](https://xmpp.org/extensions/xep-0260.html)
[xep-0261 Jingle In-Band Bytestreams Transport Method](https://xmpp.org/extensions/xep-0261.html) [XEP-0261 Jingle In-Band Bytestreams Transport Method](https://xmpp.org/extensions/xep-0261.html)
[xep-0065 SOCKS5 Bytestreams](https://xmpp.org/extensions/xep-0065.html) [XEP-0065 SOCKS5 Bytestreams](https://xmpp.org/extensions/xep-0065.html)
[xep-0047 In-Band Bytestreams](https://xmpp.org/extensions/xep-0047.html) [XEP-0047 In-Band Bytestreams](https://xmpp.org/extensions/xep-0047.html)
[Jingle XTLS](https://xmpp.org/extensions/inbox/jingle-xtls.html)
[End-to-End Encryption XTLS](https://tools.ietf.org/html/draft-meyer-xmpp-e2e-encryption-02) [End-to-End Encryption XTLS](https://tools.ietf.org/html/draft-meyer-xmpp-e2e-encryption-02)