Applications Telematics project 12/13 This document is a draft for the official specification of the Buschtrommel protocol. Buschtrommel is used to find and transfer files between clients in the same network domain without the need for a central server.

This document specifies the Buschtrommel protocol, which is used for ad-hoc file transfer between peers in the same network domain. This specification defines package formats and required client behaviour to enable such file transfers between conforming, well-behaved clients. This document describes the mechanisms required for completion of the following tasks: peer discovery file announcement file transfer The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

Buschtrommel is focused on scenarios where the set of shared files is changed frequently. Files are announced in a short-termed fashion. The fast announcement of new clients and files is one of the main focuses. The protocol features can be roughly split into four tasks: announcements of peers exploration of offered files updates of offered files file transfers

Buschtrommel uses the following multicast addresses to address all participating peers: 239.255.0.113 for IPv4 ff05::7171 for IPv6 All UDP packets sent SHALL have a destination port of 4747 set. In order to participate in the network a client must listen on this port. Messages sent using UDP MUST NOT exceed 512 octets length. Messages are strings encoded as UTF-8. Messages contain several fields which are seperated by a field separator. In addition each message is terminated by a message separator. field seperator: ASCII control character 31 (Unit Separator, U+001F) message seperator: ASCII control character 30 (Record Separator, U+001E) In this document, "|" is used to visualize a field separator and "\" is used to visualize a message separator. Integers are represented in their decimal form, encoded as UTF-8 strings. SHA-1 hashes MUST be encoded in uppercase and without leading "0x", e. g. "440AA37400EEAE2E7f4d54CECE14E547A57B189B". All control messages are of the following format:

Type|Field1|Field2|[...]|Fieldn\

The "Type" field identifies the message type while all remaining fields carry information as of the message type specification. Fields MUST NOT contain any of the field or message separator characters. The "Type" field MUST be encoded in uppercase.

A peer MAY send a "Hi" message at any time to inform other peers of its presence and to request a reply from all peers in form of a "Yo" message. A "Hi" message SHOULD be sent to the multicast address of all participating peers immediately after joining the network. A "Hi" message is sent using UDP and contains the following fields in the the given order: The "Type" field, set to "HI". A "Port" field containing an integer identifying a valid TCP port that the peer sending the message uses for Buschtrommel TCP communication. The peer MUST listen for incoming connections from other peers on this port. Note that this number is also encoded as an UTF-8 string. An "Alias" field as an human-readable name that is to be displayed by a client for the peer sending the message. The field may be empty, but MUST NOT be omitted. Fields of a "Hi" message:

Type|Port|Alias\

A client SHOULD only send as many "Hi" messages as are required for its operation.

"Yo" messages are sent as replies to "Hi" messages. Every "Hi" message SHOULD be replied to with a "Yo" message. "Yo" messages are sent either directly to the unicast address of the sender of the "Hi" message that is being replied to or to the multicast address of all participating peers. A "Yo" message is sent using UDP and has its "Type" field set to "YO". All other fields are identical to those of a "Hi" message. Fields of a "Yo" message:

Type|Port|Alias\

Clients MAY use "Yo" messages they receive to update their internal state concerning the availability of other peers.

"Bye" messages are used to inform all network participants that a peer is going to leave the network. They are sent using UDP and contain only a "Type" field set to "BYE". Fields of a "Bye" message:

Type\

Clients SHOULD send a "Bye" message to all participating peers before leaving the network. Clients receiving a "Bye" message SHOULD assume that the sending peer as well as all files previously offered for transfer by this peer are no longer available. Note that "Bye" messages are unreliable and a client might leave the network without a "Bye" message reaching participating peers. The "Bye" message SHOULD be sent to the multicast address of all participating peers.

File Announcement Messages are used to inform other clients about files offered for transfer by oneself. A File Announcement Message is contains the following fields in the following order: The Type field, set to "FILE". A Hash field, containing a uppercase hexadecimal representation of the SHA-1 hash of the file. A TTL field, indicating the expected remaining time that this file will be made available for transfer in seconds. A value of -1 SHALL be used to indicate an indefinite amount of time. A value of 0 may be used to indicate that a file is no longer available for transfer. The integer must be in the range of a 64-bit signed integer datatype. A Length field, indicating the length of the file offered in octets A Display Name field, containing a human-readable name for the file. All Unicode characters (expect those excluded above) may be used. A directory structure MAY be encoded in the value of this member. If this is the case, the '/' character (U+002F) MUST be used as a path separator. A Meta Information field, containing additional information about a file. The information encoded in this field SHOULD be human-readable.

A "Get Filelist" Message is a message which has its Type field set to "GET FILELIST". This message type has no other fields. To request a complete announcement of all files offered for transfer by a peer, a client may open a connection to the other peer using the peers's announced TCP port and send a "Get Filelist" Message. The other peer MUST reply with exactly one File Announcement Message for each file offered for transfer. After all messages have been sent, the other peer MUST close the connection.

A peer may at any time send a File Announcement Message encapsulated in a single UDP packet to the multicast address of all participating peers. Other peers SHOULD use these messages to update their internal state concerning the availability of files for transfer from other peers. This mechanism SHOULD be used to announce if a file will no longer be available for transfer, e.g. if it has been deleted or the peer is about to leave the network.

To request the transfer of a file, a client may open a connection to the peer offering the file using the peer's announced TCP port an send a "Get File" Message. "Get File" messages are used to request the transfer of a file from another peer. A "Get File" message contains the following fields in the following order: The Type field, set to "GET FILE". A Hash field, set to the SHA-1 hash in uppercase hexadecimal representation of the requested file. A client SHOULD request only files that have been announced as available for transfer from that host. An Offset field, indicating the number of octets from the beginning of the file that the sending host should skip. This value MUST be in the range of a 64-bit unsigned integer datatype. A Length field, indicating the number of octets of the file that the receiving host wishes to receive from the offset onward. This value MUST be in the range of a 64-bit unsigned integer datatype.

The peer receiving the "Get File" message MUST reply with a File Transfer Response message. If appropriate according to the status communicated in the File Transfer Response Message, it MUST then send the requested data and close the connection. The Length and Offset fields of the "Get File" message MUST be respected. File Transfer Response Messages are used to confirm or indicate an error concerning a request for transfer using a "Get File" message. A File Transfer Response Message contains the following fields in the following order: The Type field, set to "File Transfer Response". A Status Code field, indicating if the file request can be served. Valid values are "OK" if the sending peer is ready to send the file, "TRY AGAIN LATER" if the file cannot currently be served but the problem is expected to be resolved in the future or "NEVER TRY AGAIN" if the file cannot currently be served and the problem is not expected to be resolved in the future (e.g. if the file does not exist). An Expected Transfer Volume field, indicating the number of octets of the file that the peer expects to send. This MAY be less than the amount requested in the "Get File" message.

Harvard University

1350 Mass. Ave. Cambridge MA 02138 - +1 617 495 3864 sob@harvard.edu

General keyword In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Note that the force of these words is modified by the requirement level of the document in which they are used.

Participating Peer: A computer participating in the file sharing network.