File Transfer

%ents; ]>

File Transfer A protocol for transferring a file between two Jabber IDs. &LEGALNOTICE; 0052 Retracted Standards Track Standards JIG XMPP Core, XMPP IM, JEP-0004, JEP-0020, JEP-0030 None JEP-0095, JEP-0096 N/A Thomas Muldowney temas@box5.net temas@jabber.org Matthew Miller linuxwolf@outer-planes.net linuxwolf@outer-planes.net Justin Karneges justin@affinix.com justin@andbit.net 0.2 2003-09-30 psa At the request of the authors, the status of this JEP has been changed to Retracted since it has been superseded by JEP-0095 and JEP-0096. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations. 0.1 2002-12-03 tjm Initial version, based on original JEP-0052 revision 0.1.

This document describes the http://www.jabber.org/protocol/filexfer namespace, which is used for offering and transferring files from one Jabber ID to another. It tries to expand the basic method (iq:oob) that currently exists to allow for numerous stream methods, and more detailed file information before accepting an offer. This JEP only describes the negotiation method and suggests how streams could link back to the negotiated information.

This JEP covers one use case of sending a file to another user. Future JEPs may enhance this to include searching and offering.

Primary Flow:

Determine if the receiver supports FT through disco/browse. [E1]
Sender sends meta-data and available methods to receiver
Receiver sends the accepted method to Sender and any range/offset information. [E2],[E3]
Sender and Receiver establish the negotiated method[E4]
Sender sends data as described by method
After the stream closes the Receiver notifies the Sender of completion. [E5]
END

Errors Conditions:

User does not support filetransfer. END
Receiver rejects send. END
Receiver does not have any methods shared with the sender. END
The stream is unable to be started. END
The Receiver notifies sender of an error transferring. END

In order to send a file, the sender must first tell the receiver a little bit about the file to make sure they will accept it. At the same time they list the stream methods they support in the order they wish to use them. This is done by sending the information in the http://www.jabber.org/protocol/filexfer namespace.

<iq type='set' id='ft_1' to='recvr@jabber.org/Home'> <file xmlns='http://www.jabber.org/protocol/filexfer' action='offer' id='a0' name='myfile.txt' size='1024' mime-type='text/plain'> <feature xmlns='http://jabber.org/protocol/feature-neg'> <x xmlns='jabber:x:data'> <field var='file-transfer-method' type='list-single'> <option><value>jabber:iq:oob</value></option> </field> </x> </feature> </file> </iq>

That is the basic request, a more complete requeset with range support is shown below.

<iq type='set' id='ft_1' to='recvr@jabber.org/Home'> <file xmlns='http://www.jabber.org/protocol/filexfer' action='offer' id='a0' name='myfile.txt' size='1024' mime-type='text/plain' date='20020412T00:00:00' hash='23e4ad6b63343b33a333c334'> <desc>A cool file</desc> <range/> <feature xmlns='http://jabber.org/protocol/feature-neg'> <x xmlns='jabber:x:data'> <field var='file-transfer-method' type='list-single'> <option><value>jobs</value></option> <option><value>dtcp</value></option> <option><value>jabber:iq:oob</value></option> <option><value>ibb</value></option> </field> </x> </feature> </file> </iq>

If a receiver decides to accept an offered file they request it from the sending with an <iq/> type result. The receiver sends back the id of the file being sent, the method they wish to use, and the range they wish to download (if the sender announced support). When range support is being used the receiver MUST specify the length and MAY specify a beginning offset with the acceptance.

<iq type='result' id='ft_req_1' to='sender@jabber.org/res'> <file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'> <feature xmlns='http://jabber.org/protocol/feature-neg'> <x xmlns='jabber:x:data'> <field var='file-transfer-method'> <option><value>jabber:iq:oob</value></option> </field'> </x> </feature> </file> </iq> <iq type='result' id='ft_req_q' to='sender@jabber.org/res'> <file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'> <range offset='100' length='500' /> <x xmlns='jabber:x:data'> <field var='file-transfer-method'> <option><value>jobs</value></option> </field> </x> </feature> </file> </iq>

If the receiver decides to not accept the file they SHOULD send back an error 403 to the sender.

<iq type='error' id='ft_1' to='sender@jabber.org/res'> <error code='403'>Offer Declined</error> </iq>

If the receiver does not support any of the offered stream methods they SHOULD send back an error 406 to the sender.

<iq type='error' id='ft_1' to='sender@jabber.org/res'> <error code='406'>No Acceptable Methods</error> </iq>

At this point the sender will setup the stream method and begin to transfer data. The stream itself can use the file transfer namespace to tie the meta-data to the actual data sent, this is illustrated below using iq:oob.

<iq type='set' id='ft_oob_1' to='recvr@jabber.org/Home'> <file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='start'/> <query xmlns='jabber:iq:oob'> <url>http://www.jabber.org/file.txt</url> <desc>Here is the file</desc> </query> </iq>

If the receiver is unable to start the negotiated stream for any reason they should send an <error/> with a 502 code to the sender.

<iq type='error' id='ft_oob_e_1' to='sender@jabber.org/res'> <file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/> <error code='502'>Unable to Start Stream</error> </iq>

Once the data has been transferred the receiver SHOULD send the sender a notification that the transfer completed. This is done by sending an <iq/> type set with the file id and a completed action.

If the transfer does not complete, for any reason after the meta-data negotiation, the party that has the error SHOULD send an error 500 and the file id to the other party.

<iq type='error' id='ft_1' to='sender@jabber.org/res'> <error code='500'>File Transfer Failed</error> <file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/> </iq>

By staying in just the realm of negotiating the meta-data to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the meta-data to the actual data transfer, to help accomodate this the stream may use the <file/> with an action of start and the correct id. The <file/> could be transported in the stream negotiations, or along side it. Although this spec does not mandate any specific methods to new stream authors, it does provide the syntax for the currently existing "iq:oob" system.

For an "iq:oob" transfer to be related to it's meta-data, a <file/> is transported along side the <query/>. The id used on the <file/> is the id for the meta-data of the actual data that is being sent. The action on the <file/> is "start". An example of this can be found in the Basic Usage section.






    mime-type CDATA   #OPTIONAL
    date      CDATA   #OPTIONAL
    hash      CDATA   #OPTIONAL

    ]]>

The <file/> element is the "workhorse" element. This element is used to convey meta-data and report file transfer actions. This elemnt contains attributes for file meta-data and actions, and MAY contain a <desc/>, a <range/>, and zero or more <feature xmlns='jabber:iq:negotiate'/>JEP-0020: "Feature Negotiation" -- http://www.jabber.org/jeps/jep-0020.html elements.

The "id" attribute specifies the identifier for this particular file transfer. This attribute MUST be present at all times. There are no value requirements other than it MUST be unique between the sender and receiver.

The "action" attribute specifies the action to undertake with the given file. This attribute SHOULD be present in most cases. If not present, the value "offer" is implied. The value of "action" MUST be one of the following:

Value	Description
complete	The file transfer is complete.
get	The file transfer should start.
offer	The file transfer is offered (meta-data MUST be present)
start	The file transfer is starting.
error	The file transfer has failed. The outlying error tag has more information.

The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.

The "size" attribute specifies the file size, in bytes. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.

The "mime-type" attribute specifies the MIME-type for the file. This attribute SHOULD be present if the action is "offer", otherwise it SHOULD NOT be present. The value of this attribute MUST follow the specification for MIME-types from RFC-2046RFC 2046: "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -- http://www.ietf.org/rfc/rfc2046.txt.

The "date" attribute specifies the file date. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST follow the specification for ISO 8601 date/time formatsISO 8601: "[Summary of the] International Standard Date and Time Notation" -- http://www.cl.cam.ac.uk/~mgk25/iso-time.html.

The "hash" attribute specifies the hash of the file contents. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST be an SHA1 hash of the file contents.

The <desc/> element contains a human-readable description of the file. This element has no attributes, and contains character data content.

The <range/> element describes range information for a partial transfer. This element has attributes to define the range length and range offset. This element contains no content.

The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. The value of this attribute MUST be an integer value and MUST be less than or equal to the (size + offset) of the file.

The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. If this attribute is not present, a value of 0 is implied. The value of this attribute MUST be an integer, MUST NOT be less than 0, and MUST be less than (size - length).

There are three main error conditions in file transfer. Following are the conditions, error codes and descriptions:

Declining Transfer (403): During the meta-data negotiation the receiver may decline the transfer by sending the 403 error. The <error/> CDATA MAY contain a descriptive reason why, but is not necessary.
No Available Methods (406): When the sender presents the available stream methods, and the receiver can not use any of them, they send a 406 error. The <error/> CDATA is not important.
Transfer Failed (500): If the file transfer fails for any reason after negotiation, the error generator SHOULD send a 500 error to the other party. This is the only error message that both the sender and reciever may send. The <error/> CDATA MAY contain information about the failure.
Unable to Start Stream (502): When the receiver is unable to start the negotiated stream method they send a 502 error to the sender. The <error/> CDATA is not important.

Data integrity can be checked with the sha1 of the file that is sent. This could be attacked via a man in the middle attack, but much more embarrasing things could result from that than a bad file. The wire integrity is left to the stream method.

The mime-type attribute on <file/> is a valid MIME type as controlled by the IANA.

The "http://jabber.org/protocol/filexfer" is the only namespace that needs to be registered with the JANA.