diff --git a/doc/rfc1350.txt b/doc/rfc1350.txt new file mode 100644 index 0000000..e00113b --- /dev/null +++ b/doc/rfc1350.txt @@ -0,0 +1,619 @@ + + + + + + +Network Working Group K. Sollins +Request For Comments: 1350 MIT +STD: 33 July 1992 +Obsoletes: RFC 783 + + + THE TFTP PROTOCOL (REVISION 2) + +Status of this Memo + + This RFC specifies an IAB standards track protocol for the Internet + community, and requests discussion and suggestions for improvements. + Please refer to the current edition of the "IAB Official Protocol + Standards" for the standardization state and status of this protocol. + Distribution of this memo is unlimited. + +Summary + + TFTP is a very simple protocol used to transfer files. It is from + this that its name comes, Trivial File Transfer Protocol or TFTP. + Each nonterminal packet is acknowledged separately. This document + describes the protocol and its types of packets. The document also + explains the reasons behind some of the design decisions. + +Acknowlegements + + The protocol was originally designed by Noel Chiappa, and was + redesigned by him, Bob Baldwin and Dave Clark, with comments from + Steve Szymanski. The current revision of the document includes + modifications stemming from discussions with and suggestions from + Larry Allen, Noel Chiappa, Dave Clark, Geoff Cooper, Mike Greenwald, + Liza Martin, David Reed, Craig Milo Rogers (of USC-ISI), Kathy + Yellick, and the author. The acknowledgement and retransmission + scheme was inspired by TCP, and the error mechanism was suggested by + PARC's EFTP abort message. + + The May, 1992 revision to fix the "Sorcerer's Apprentice" protocol + bug [4] and other minor document problems was done by Noel Chiappa. + + This research was supported by the Advanced Research Projects Agency + of the Department of Defense and was monitored by the Office of Naval + Research under contract number N00014-75-C-0661. + +1. Purpose + + TFTP is a simple protocol to transfer files, and therefore was named + the Trivial File Transfer Protocol or TFTP. It has been implemented + on top of the Internet User Datagram protocol (UDP or Datagram) [2] + + + +Sollins [Page 1] + +RFC 1350 TFTP Revision 2 July 1992 + + + so it may be used to move files between machines on different + networks implementing UDP. (This should not exclude the possibility + of implementing TFTP on top of other datagram protocols.) It is + designed to be small and easy to implement. Therefore, it lacks most + of the features of a regular FTP. The only thing it can do is read + and write files (or mail) from/to a remote server. It cannot list + directories, and currently has no provisions for user authentication. + In common with other Internet protocols, it passes 8 bit bytes of + data. + + Three modes of transfer are currently supported: netascii (This is + ascii as defined in "USA Standard Code for Information Interchange" + [1] with the modifications specified in "Telnet Protocol + Specification" [3].) Note that it is 8 bit ascii. The term + "netascii" will be used throughout this document to mean this + particular version of ascii.); octet (This replaces the "binary" mode + of previous versions of this document.) raw 8 bit bytes; mail, + netascii characters sent to a user rather than a file. (The mail + mode is obsolete and should not be implemented or used.) Additional + modes can be defined by pairs of cooperating hosts. + + Reference [4] (section 4.2) should be consulted for further valuable + directives and suggestions on TFTP. + +2. Overview of the Protocol + + Any transfer begins with a request to read or write a file, which + also serves to request a connection. If the server grants the + request, the connection is opened and the file is sent in fixed + length blocks of 512 bytes. Each data packet contains one block of + data, and must be acknowledged by an acknowledgment packet before the + next packet can be sent. A data packet of less than 512 bytes + signals termination of a transfer. If a packet gets lost in the + network, the intended recipient will timeout and may retransmit his + last packet (which may be data or an acknowledgment), thus causing + the sender of the lost packet to retransmit that lost packet. The + sender has to keep just one packet on hand for retransmission, since + the lock step acknowledgment guarantees that all older packets have + been received. Notice that both machines involved in a transfer are + considered senders and receivers. One sends data and receives + acknowledgments, the other sends acknowledgments and receives data. + + Most errors cause termination of the connection. An error is + signalled by sending an error packet. This packet is not + acknowledged, and not retransmitted (i.e., a TFTP server or user may + terminate after sending an error message), so the other end of the + connection may not get it. Therefore timeouts are used to detect + such a termination when the error packet has been lost. Errors are + + + +Sollins [Page 2] + +RFC 1350 TFTP Revision 2 July 1992 + + + caused by three types of events: not being able to satisfy the + request (e.g., file not found, access violation, or no such user), + receiving a packet which cannot be explained by a delay or + duplication in the network (e.g., an incorrectly formed packet), and + losing access to a necessary resource (e.g., disk full or access + denied during a transfer). + + TFTP recognizes only one error condition that does not cause + termination, the source port of a received packet being incorrect. + In this case, an error packet is sent to the originating host. + + This protocol is very restrictive, in order to simplify + implementation. For example, the fixed length blocks make allocation + straight forward, and the lock step acknowledgement provides flow + control and eliminates the need to reorder incoming data packets. + +3. Relation to other Protocols + + As mentioned TFTP is designed to be implemented on top of the + Datagram protocol (UDP). Since Datagram is implemented on the + Internet protocol, packets will have an Internet header, a Datagram + header, and a TFTP header. Additionally, the packets may have a + header (LNI, ARPA header, etc.) to allow them through the local + transport medium. As shown in Figure 3-1, the order of the contents + of a packet will be: local medium header, if used, Internet header, + Datagram header, TFTP header, followed by the remainder of the TFTP + packet. (This may or may not be data depending on the type of packet + as specified in the TFTP header.) TFTP does not specify any of the + values in the Internet header. On the other hand, the source and + destination port fields of the Datagram header (its format is given + in the appendix) are used by TFTP and the length field reflects the + size of the TFTP packet. The transfer identifiers (TID's) used by + TFTP are passed to the Datagram layer to be used as ports; therefore + they must be between 0 and 65,535. The initialization of TID's is + discussed in the section on initial connection protocol. + + The TFTP header consists of a 2 byte opcode field which indicates + the packet's type (e.g., DATA, ERROR, etc.) These opcodes and the + formats of the various types of packets are discussed further in the + section on TFTP packets. + + + + + + + + + + + +Sollins [Page 3] + +RFC 1350 TFTP Revision 2 July 1992 + + + --------------------------------------------------- + | Local Medium | Internet | Datagram | TFTP | + --------------------------------------------------- + + Figure 3-1: Order of Headers + + +4. Initial Connection Protocol + + A transfer is established by sending a request (WRQ to write onto a + foreign file system, or RRQ to read from it), and receiving a + positive reply, an acknowledgment packet for write, or the first data + packet for read. In general an acknowledgment packet will contain + the block number of the data packet being acknowledged. Each data + packet has associated with it a block number; block numbers are + consecutive and begin with one. Since the positive response to a + write request is an acknowledgment packet, in this special case the + block number will be zero. (Normally, since an acknowledgment packet + is acknowledging a data packet, the acknowledgment packet will + contain the block number of the data packet being acknowledged.) If + the reply is an error packet, then the request has been denied. + + In order to create a connection, each end of the connection chooses a + TID for itself, to be used for the duration of that connection. The + TID's chosen for a connection should be randomly chosen, so that the + probability that the same number is chosen twice in immediate + succession is very low. Every packet has associated with it the two + TID's of the ends of the connection, the source TID and the + destination TID. These TID's are handed to the supporting UDP (or + other datagram protocol) as the source and destination ports. A + requesting host chooses its source TID as described above, and sends + its initial request to the known TID 69 decimal (105 octal) on the + serving host. The response to the request, under normal operation, + uses a TID chosen by the server as its source TID and the TID chosen + for the previous message by the requestor as its destination TID. + The two chosen TID's are then used for the remainder of the transfer. + + As an example, the following shows the steps used to establish a + connection to write a file. Note that WRQ, ACK, and DATA are the + names of the write request, acknowledgment, and data types of packets + respectively. The appendix contains a similar example for reading a + file. + + + + + + + + + +Sollins [Page 4] + +RFC 1350 TFTP Revision 2 July 1992 + + + 1. Host A sends a "WRQ" to host B with source= A's TID, + destination= 69. + + 2. Host B sends a "ACK" (with block number= 0) to host A with + source= B's TID, destination= A's TID. + + At this point the connection has been established and the first data + packet can be sent by Host A with a sequence number of 1. In the + next step, and in all succeeding steps, the hosts should make sure + that the source TID matches the value that was agreed on in steps 1 + and 2. If a source TID does not match, the packet should be + discarded as erroneously sent from somewhere else. An error packet + should be sent to the source of the incorrect packet, while not + disturbing the transfer. This can be done only if the TFTP in fact + receives a packet with an incorrect TID. If the supporting protocols + do not allow it, this particular error condition will not arise. + + The following example demonstrates a correct operation of the + protocol in which the above situation can occur. Host A sends a + request to host B. Somewhere in the network, the request packet is + duplicated, and as a result two acknowledgments are returned to host + A, with different TID's chosen on host B in response to the two + requests. When the first response arrives, host A continues the + connection. When the second response to the request arrives, it + should be rejected, but there is no reason to terminate the first + connection. Therefore, if different TID's are chosen for the two + connections on host B and host A checks the source TID's of the + messages it receives, the first connection can be maintained while + the second is rejected by returning an error packet. + +5. TFTP Packets + + TFTP supports five types of packets, all of which have been mentioned + above: + + opcode operation + 1 Read request (RRQ) + 2 Write request (WRQ) + 3 Data (DATA) + 4 Acknowledgment (ACK) + 5 Error (ERROR) + + The TFTP header of a packet contains the opcode associated with + that packet. + + + + + + + +Sollins [Page 5] + +RFC 1350 TFTP Revision 2 July 1992 + + + 2 bytes string 1 byte string 1 byte + ------------------------------------------------ + | Opcode | Filename | 0 | Mode | 0 | + ------------------------------------------------ + + Figure 5-1: RRQ/WRQ packet + + + RRQ and WRQ packets (opcodes 1 and 2 respectively) have the format + shown in Figure 5-1. The file name is a sequence of bytes in + netascii terminated by a zero byte. The mode field contains the + string "netascii", "octet", or "mail" (or any combination of upper + and lower case, such as "NETASCII", NetAscii", etc.) in netascii + indicating the three modes defined in the protocol. A host which + receives netascii mode data must translate the data to its own + format. Octet mode is used to transfer a file that is in the 8-bit + format of the machine from which the file is being transferred. It + is assumed that each type of machine has a single 8-bit format that + is more common, and that that format is chosen. For example, on a + DEC-20, a 36 bit machine, this is four 8-bit bytes to a word with + four bits of breakage. If a host receives a octet file and then + returns it, the returned file must be identical to the original. + Mail mode uses the name of a mail recipient in place of a file and + must begin with a WRQ. Otherwise it is identical to netascii mode. + The mail recipient string should be of the form "username" or + "username@hostname". If the second form is used, it allows the + option of mail forwarding by a relay computer. + + The discussion above assumes that both the sender and recipient are + operating in the same mode, but there is no reason that this has to + be the case. For example, one might build a storage server. There + is no reason that such a machine needs to translate netascii into its + own form of text. Rather, the sender might send files in netascii, + but the storage server might simply store them without translation in + 8-bit format. Another such situation is a problem that currently + exists on DEC-20 systems. Neither netascii nor octet accesses all + the bits in a word. One might create a special mode for such a + machine which read all the bits in a word, but in which the receiver + stored the information in 8-bit format. When such a file is + retrieved from the storage site, it must be restored to its original + form to be useful, so the reverse mode must also be implemented. The + user site will have to remember some information to achieve this. In + both of these examples, the request packets would specify octet mode + to the foreign host, but the local host would be in some other mode. + No such machine or application specific modes have been specified in + TFTP, but one would be compatible with this specification. + + It is also possible to define other modes for cooperating pairs of + + + +Sollins [Page 6] + +RFC 1350 TFTP Revision 2 July 1992 + + + hosts, although this must be done with care. There is no requirement + that any other hosts implement these. There is no central authority + that will define these modes or assign them names. + + + 2 bytes 2 bytes n bytes + ---------------------------------- + | Opcode | Block # | Data | + ---------------------------------- + + Figure 5-2: DATA packet + + + Data is actually transferred in DATA packets depicted in Figure 5-2. + DATA packets (opcode = 3) have a block number and data field. The + block numbers on data packets begin with one and increase by one for + each new block of data. This restriction allows the program to use a + single number to discriminate between new packets and duplicates. + The data field is from zero to 512 bytes long. If it is 512 bytes + long, the block is not the last block of data; if it is from zero to + 511 bytes long, it signals the end of the transfer. (See the section + on Normal Termination for details.) + + All packets other than duplicate ACK's and those used for + termination are acknowledged unless a timeout occurs [4]. Sending a + DATA packet is an acknowledgment for the first ACK packet of the + previous DATA packet. The WRQ and DATA packets are acknowledged by + ACK or ERROR packets, while RRQ + + + 2 bytes 2 bytes + --------------------- + | Opcode | Block # | + --------------------- + + Figure 5-3: ACK packet + + + and ACK packets are acknowledged by DATA or ERROR packets. Figure + 5-3 depicts an ACK packet; the opcode is 4. The block number in + an ACK echoes the block number of the DATA packet being + acknowledged. A WRQ is acknowledged with an ACK packet having a + block number of zero. + + + + + + + + +Sollins [Page 7] + +RFC 1350 TFTP Revision 2 July 1992 + + + 2 bytes 2 bytes string 1 byte + ----------------------------------------- + | Opcode | ErrorCode | ErrMsg | 0 | + ----------------------------------------- + + Figure 5-4: ERROR packet + + + An ERROR packet (opcode 5) takes the form depicted in Figure 5-4. An + ERROR packet can be the acknowledgment of any other type of packet. + The error code is an integer indicating the nature of the error. A + table of values and meanings is given in the appendix. (Note that + several error codes have been added to this version of this + document.) The error message is intended for human consumption, and + should be in netascii. Like all other strings, it is terminated with + a zero byte. + +6. Normal Termination + + The end of a transfer is marked by a DATA packet that contains + between 0 and 511 bytes of data (i.e., Datagram length < 516). This + packet is acknowledged by an ACK packet like all other DATA packets. + The host acknowledging the final DATA packet may terminate its side + of the connection on sending the final ACK. On the other hand, + dallying is encouraged. This means that the host sending the final + ACK will wait for a while before terminating in order to retransmit + the final ACK if it has been lost. The acknowledger will know that + the ACK has been lost if it receives the final DATA packet again. + The host sending the last DATA must retransmit it until the packet is + acknowledged or the sending host times out. If the response is an + ACK, the transmission was completed successfully. If the sender of + the data times out and is not prepared to retransmit any more, the + transfer may still have been completed successfully, after which the + acknowledger or network may have experienced a problem. It is also + possible in this case that the transfer was unsuccessful. In any + case, the connection has been closed. + +7. Premature Termination + + If a request can not be granted, or some error occurs during the + transfer, then an ERROR packet (opcode 5) is sent. This is only a + courtesy since it will not be retransmitted or acknowledged, so it + may never be received. Timeouts must also be used to detect errors. + + + + + + + + +Sollins [Page 8] + +RFC 1350 TFTP Revision 2 July 1992 + + +I. Appendix + +Order of Headers + + 2 bytes + ---------------------------------------------------------- + | Local Medium | Internet | Datagram | TFTP Opcode | + ---------------------------------------------------------- + +TFTP Formats + + Type Op # Format without header + + 2 bytes string 1 byte string 1 byte + ----------------------------------------------- + RRQ/ | 01/02 | Filename | 0 | Mode | 0 | + WRQ ----------------------------------------------- + 2 bytes 2 bytes n bytes + --------------------------------- + DATA | 03 | Block # | Data | + --------------------------------- + 2 bytes 2 bytes + ------------------- + ACK | 04 | Block # | + -------------------- + 2 bytes 2 bytes string 1 byte + ---------------------------------------- + ERROR | 05 | ErrorCode | ErrMsg | 0 | + ---------------------------------------- + +Initial Connection Protocol for reading a file + + 1. Host A sends a "RRQ" to host B with source= A's TID, + destination= 69. + + 2. Host B sends a "DATA" (with block number= 1) to host A with + source= B's TID, destination= A's TID. + + + + + + + + + + + + + + +Sollins [Page 9] + +RFC 1350 TFTP Revision 2 July 1992 + + +Error Codes + + Value Meaning + + 0 Not defined, see error message (if any). + 1 File not found. + 2 Access violation. + 3 Disk full or allocation exceeded. + 4 Illegal TFTP operation. + 5 Unknown transfer ID. + 6 File already exists. + 7 No such user. + +Internet User Datagram Header [2] + + (This has been included only for convenience. TFTP need not be + implemented on top of the Internet User Datagram Protocol.) + + Format + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source Port | Destination Port | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | Checksum | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + + Values of Fields + + + Source Port Picked by originator of packet. + + Dest. Port Picked by destination machine (69 for RRQ or WRQ). + + Length Number of bytes in UDP packet, including UDP header. + + Checksum Reference 2 describes rules for computing checksum. + (The implementor of this should be sure that the + correct algorithm is used here.) + Field contains zero if unused. + + Note: TFTP passes transfer identifiers (TID's) to the Internet User + Datagram protocol to be used as the source and destination ports. + + + + + + +Sollins [Page 10] + +RFC 1350 TFTP Revision 2 July 1992 + + +References + + [1] USA Standard Code for Information Interchange, USASI X3.4-1968. + + [2] Postel, J., "User Datagram Protocol," RFC 768, USC/Information + Sciences Institute, 28 August 1980. + + [3] Postel, J., "Telnet Protocol Specification," RFC 764, + USC/Information Sciences Institute, June, 1980. + + [4] Braden, R., Editor, "Requirements for Internet Hosts -- + Application and Support", RFC 1123, USC/Information Sciences + Institute, October 1989. + +Security Considerations + + Since TFTP includes no login or access control mechanisms, care must + be taken in the rights granted to a TFTP server process so as not to + violate the security of the server hosts file system. TFTP is often + installed with controls such that only files that have public read + access are available via TFTP and writing files via TFTP is + disallowed. + +Author's Address + + Karen R. Sollins + Massachusetts Institute of Technology + Laboratory for Computer Science + 545 Technology Square + Cambridge, MA 02139-1986 + + Phone: (617) 253-6006 + + EMail: SOLLINS@LCS.MIT.EDU + + + + + + + + + + + + + + + + + +Sollins [Page 11] + \ No newline at end of file diff --git a/doc/rfc1783.txt b/doc/rfc1783.txt new file mode 100644 index 0000000..167ff19 --- /dev/null +++ b/doc/rfc1783.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group G. Malkin +Request for Comments: 1783 Xylogics, Inc. +Updates: 1350 A. Harkin +Category: Standards Track Hewlett Packard Co. + March 1995 + + + TFTP Blocksize Option + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The Trivial File Transfer Protocol [1] is a simple, lock-step, file + transfer protocol which allows a client to get or put a file onto a + remote host. One of its primary uses is the booting of diskless + nodes on a Local Area Network. TFTP is used because it is very + simple to implement in a small node's limited ROM space. However, + the choice of a 512-byte blocksize is not the most efficient for use + on a LAN whose MTU may 1500 bytes or greater. + + This document describes a TFTP option which allows the client and + server to negotiate a blocksize more applicable to the network + medium. The TFTP Option Extension mechanism is described in [2]. + +Blocksize Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the blocksize option as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | blksize| 0 | #octets| 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + + + +Malkin & Harkin [Page 1] + +RFC 1783 TFTP Blocksize Option March 1995 + + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + blksize + The Blocksize option, "blksize" (case insensitive). This is a + NULL-terminated field. + + #octets + The number of octets in a block, specified in ASCII. Valid + values range between "8" and "65464" octets, inclusive. This + is a NULL-terminated field. + + For example: + + +-------+--------+---+--------+---+--------+---+--------+---+ + | 1 | foobar | 0 | binary | 0 | blksize| 0 | 1432 | 0 | + +-------+--------+---+--------+---+--------+---+--------+---+ + + is a Read Request, for the file named "foobar", in binary transfer + mode, with a block size of 1432 bytes (Ethernet MTU, less the UDP and + IP header lengths). + + If the server is willing to accept the blocksize option, it sends an + Option Acknowledgment (OACK) to the client. The specified value must + be less than or equal to the value specified by the client. The + client must then either use the size specified in the OACK, or send + an ERROR packet, with error code 8, to terminate the transfer. + + The rules for determining the final packet are unchanged from [1]. + The reception of a data packet with a data length less than the + negotiated blocksize is the final packet. If the blocksize is + greater than the size of the packet, the first packet is the final + packet. If amount of data to be transfered is an integral multiple + of the blocksize, an extra data packet containing no data is sent to + end the transfer. + + + + + + + + + + + + + + + +Malkin & Harkin [Page 2] + +RFC 1783 TFTP Blocksize Option March 1995 + + +Proof of Concept + + Performance tests were run on the prototype implementation using a + variety of block sizes. The tests were run on a lightly loaded + Ethernet, between two HP-UX 9000, in "octet" mode, on 2.25MB files. + The average (5x) transfer times for paths with (g-time) and without + (n-time) a intermediate gateway are graphed as follows: + + | + 37 + g + | + 35 + + | + 33 + + | + 31 + + | + 29 + + | + 27 + + | g blocksize n-time g-time + 25 + --------- ------ ------ + s | n 512 23.85 37.05 + e 23 + g 1024 16.15 25.65 + c | 1432 13.70 23.10 + o 21 + 2048 10.90 16.90 + n | 4096 6.85 9.65 + d 19 + 8192 4.90 6.15 + s | + 17 + g + | n + 15 + + | n + 13 + + | + 11 + n + | g + 9 + + | + 7 + n + | g + 5 + n + " + 0 +------+------+--+---+------+------+--- + 512 1K | 2K 4K 8K + 1432 + blocksize (bytes) + + + + +Malkin & Harkin [Page 3] + +RFC 1783 TFTP Blocksize Option March 1995 + + + The comparisons between transfer times (without a gateway) between + the standard 512-byte blocksize and the negotiated blocksizes are: + + 1024 2x -32% + 1432 2.8x -42% + 2048 4x -54% + 4096 8x -71% + 8192 16x -80% + + As was anticipated, the transfer time decreases with an increase in + blocksize. The reason for the reduction in time is the reduction in + the number of packets sent. For example, by increasing the blocksize + from 512 bytes to 1024 bytes, not only are the number of data packets + halved, but the number of acknowledgement packets is also halved + (along with the number of times the data transmitter must wait for an + ACK). A secondary effect is the efficiency gained by reducing the + per-packet framing and processing overhead. + + Of course, if the blocksize exceeds the path MTU, IP fragmentation + and reassembly will begin to add more overhead. This will be more + noticable the greater the number of gateways in the path. + +Security Considerations + + Security issues are not discussed in this memo. + +References + + [1] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + MIT, July 1992. + + [2] Malkin, G., and A. Harkin, "TFTP Option Extension", RFC 1782, + Xylogics, Inc., Hewlett Packard Co., March 1995. + + + + + + + + + + + + + + + + + + +Malkin & Harkin [Page 4] + +RFC 1783 TFTP Blocksize Option March 1995 + + +Authors' Addresses + + Gary Scott Malkin + Xylogics, Inc. + 53 Third Avenue + Burlington, MA 01803 + + Phone: (617) 272-8140 + EMail: gmalkin@xylogics.com + + + Art Harkin + Internet Services Project + Information Networks Division + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin [Page 5] + diff --git a/doc/rfc1784.txt b/doc/rfc1784.txt new file mode 100644 index 0000000..11b80f6 --- /dev/null +++ b/doc/rfc1784.txt @@ -0,0 +1,227 @@ + + + + + + +Network Working Group G. Malkin +Request for Comments: 1784 Xylogics, Inc. +Updates: 1350 A. Harkin +Category: Standards Track Hewlett Packard Co. + March 1995 + + + TFTP Timeout Interval and Transfer Size Options + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The Trivial File Transfer Protocol [1] is a simple, lock-step, file + transfer protocol which allows a client to get or put a file onto a + remote host. + + This document describes two TFTP options. The first allows the client + and server to negotiate the Timeout Interval. The second allows the + side receiving the file to determine the ultimate size of the + transfer before it begins. The TFTP Option Extension mechanism is + described in [2]. + + This document assumes that the reader is familiar with the + terminology and notation of both [1] and [2]. + +Timeout Interval Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the timeout option as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | timeout| 0 | #secs | 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + + +Malkin & Harkin [Page 1] + +RFC 1784 TFTP Options March 1995 + + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + timeout + The Timeout Interval option, "timeout" (case insensitive). + This is a NULL-terminated field. + + #secs + The number of seconds to wait before retransmitting, specified + in ASCII. Valid values range between "1" and "255" octets, + inclusive. This is a NULL-terminated field. + + For example: + + +-------+--------+---+--------+---+--------+---+--------+---+ + | 1 | foobar | 0 | binary | 0 | timeout| 0 | 1 | 0 | + +-------+--------+---+--------+---+--------+---+--------+---+ + + is a Read Request, for the file named "foobar", in binary transfer + mode, with a timeout interval of 1 second. + + If the server is willing to accept the timeout option, it sends an + Option Acknowledgment (OACK) to the client. The specified timeout + value must match the value specified by the client. + +Transfer Size Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the tsize option as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | tsize | 0 | size | 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + + + +Malkin & Harkin [Page 2] + +RFC 1784 TFTP Options March 1995 + + + tsize + The Transfer Size option, "tsize" (case insensitive). This is + a NULL-terminated field. + + size + The size of the file to be transfered, specified as a + NULL-terminated ASCII string. + + For example: + + +-------+--------+---+--------+---+--------+---+--------+---+ + | 2 | foobar | 0 | binary | 0 | tsize | 0 | 673312 | 0 | + +-------+--------+---+--------+---+--------+---+--------+---+ + + is a Write Request, with the 673312-octet file named "foobar", in + binary transfer mode. + + In Read Request packets, a size of "0" is specified in the request + and the size of the file, in octets, is returned in the OACK. If the + file is too large for the client to handle, it may abort the transfer + with an Error packet (error code 3). In Write Request packets, the + size of the file, in octets, is specified in the request and echoed + back in the OACK. If the file is too large for the server to handle, + it may abort the transfer with an Error packet (error code 3). + +Security Considerations + + Security issues are not discussed in this memo. + +References + + [1] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + MIT, July 1992. + + [2] Malkin, G., and A. Harkin, "TFTP Option Extension", RFC 1782, + Xylogics, Inc., Hewlett Packard Co., March 1995. + + + + + + + + + + + + + + + +Malkin & Harkin [Page 3] + +RFC 1784 TFTP Options March 1995 + + +Authors' Addresses + + Gary Scott Malkin + Xylogics, Inc. + 53 Third Avenue + Burlington, MA 01803 + + Phone: (617) 272-8140 + EMail: gmalkin@xylogics.com + + + Art Harkin + Internet Services Project + Information Networks Division + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin [Page 4] + diff --git a/doc/rfc1785.txt b/doc/rfc1785.txt new file mode 100644 index 0000000..a91c3f3 --- /dev/null +++ b/doc/rfc1785.txt @@ -0,0 +1,115 @@ + + + + + + +Network Working Group G. Malkin +Request for Comments: 1785 Xylogics, Inc. +Updates: 1350 A. Harkin +Category: Informational Hewlett Packard Co. + March 1995 + + + TFTP Option Negotiation Analysis + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +Abstract + + The TFTP option negotiation mechanism, proposed in [1], is a + backward-compatible extension to the TFTP protocol, defined in [2]. + It allows file transfer options to be negotiated prior to the + transfer using a mechanism which is consistent with TFTP's Request + Packet format. The mechanism is kept simple by enforcing a request- + respond-acknowledge sequence, similar to the lock-step approach taken + by TFTP itself. + + This document was written to allay concerns that the presence of + options in a TFTP Request packet might cause pathological behavior on + servers which do not support TFTP option negotiation. + +Test Results + + A TFTP client, modified to send TFTP options, was tested against five + unmodified servers: + + DEC DEC 3000/400 alpha OSF1 V3.0 + SGI IP17 mips IRIX 5.2 + SUN sun4c sparc SunOS 5.1 + IBM RS/6000 Model 320 AIX 3.4 + SUN sun4m SunOS 4.1.3 + + In each case, the servers ignored the option information in the + Request packet and the transfer proceeded as though no option + negotiation had been attempted. In addition, the standard BSD4.3 + source for TFTPD, the starting point for many implementations, was + examined. The code clearly ignores any extraneous information in + Request packets. + + From these results and examinations, it is clear that the TFTP option + + + +Malkin & Harkin [Page 1] + +RFC 1785 TFTP Option Negotiation Analysis March 1995 + + + negotiation mechanism is fully backward-compatible with unmodified + TFTP servers. + +Security Considerations + + Security issues are not discussed in this memo. + +References + + [1] Malkin, G., and A. Harkin, "TFTP Option Extension", RFC 1782, + Xylogics, Inc., Hewlett Packard Co., March 1995. + + [2] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + MIT, July 1992. + +Related Documents + + Malkin, G., and A. Harkin, "TFTP Blocksize Option", RFC 1783, + Xylogics, Inc., Hewlett Packard Co., March 1995. + + Malkin, G., and A. Harkin, "TFTP Timeout Interval and Transfer Size + Options", RFC 1784, Xylogics, Inc., Hewlett Packard Co., March + 1995. + +Authors' Addresses + + Gary Scott Malkin + Xylogics, Inc. + 53 Third Avenue + Burlington, MA 01803 + + Phone: (617) 272-8140 + EMail: gmalkin@xylogics.com + + + Art Harkin + Internet Services Project + Information Networks Division + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + + + + + +Malkin & Harkin [Page 2] + diff --git a/doc/rfc2347.txt b/doc/rfc2347.txt new file mode 100644 index 0000000..dbc0f8c --- /dev/null +++ b/doc/rfc2347.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group G. Malkin +Request for Commments: 2347 Bay Networks +Updates: 1350 A. Harkin +Obsoletes: 1782 Hewlett Packard Co. +Category: Standards Track May 1998 + + + TFTP Option Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + The Trivial File Transfer Protocol [1] is a simple, lock-step, file + transfer protocol which allows a client to get or put a file onto a + remote host. This document describes a simple extension to TFTP to + allow option negotiation prior to the file transfer. + +Introduction + + The option negotiation mechanism proposed in this document is a + backward-compatible extension to the TFTP protocol. It allows file + transfer options to be negotiated prior to the transfer using a + mechanism which is consistent with TFTP's Request Packet format. The + mechanism is kept simple by enforcing a request-respond-acknowledge + sequence, similar to the lock-step approach taken by TFTP itself. + + While the option negotiation mechanism is general purpose, in that + many types of options may be negotiated, it was created to support + the Blocksize option defined in [2]. Additional options are defined + in [3]. + +Packet Formats + + TFTP options are appended to the Read Request and Write Request + packets. A new type of TFTP packet, the Option Acknowledgment + (OACK), is used to acknowledge a client's option negotiation request. + A new error code, 8, is hereby defined to indicate that a transfer + + + +Malkin & Harkin Standards Track [Page 1] + +RFC 2347 TFTP Option Extension May 1998 + + + should be terminated due to option negotiation. + + Options are appended to a TFTP Read Request or Write Request packet + as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+--> + | opc |filename| 0 | mode | 0 | opt1 | 0 | value1 | 0 | < + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+--> + + >-------+---+---~~---+---+ + < optN | 0 | valueN | 0 | + >-------+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + opt1 + The first option, in case-insensitive ASCII (e.g., blksize). + This is a NULL-terminated field. + + value1 + The value associated with the first option, in case- + insensitive ASCII. This is a NULL-terminated field. + + optN, valueN + The final option/value pair. Each NULL-terminated field is + specified in case-insensitive ASCII. + + The options and values are all NULL-terminated, in keeping with the + original request format. If multiple options are to be negotiated, + they are appended to each other. The order in which options are + specified is not significant. The maximum size of a request packet + is 512 octets. + + The OACK packet has the following format: + + + + + + + +Malkin & Harkin Standards Track [Page 2] + +RFC 2347 TFTP Option Extension May 1998 + + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc | opt1 | 0 | value1 | 0 | optN | 0 | valueN | 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains a 6, for Option Acknowledgment. + + opt1 + The first option acknowledgment, copied from the original + request. + + value1 + The acknowledged value associated with the first option. If + and how this value may differ from the original request is + detailed in the specification for the option. + + optN, valueN + The final option/value acknowledgment pair. + +Negotiation Protocol + + The client appends options at the end of the Read Request or Write + request packet, as shown above. Any number of options may be + specified; however, an option may only be specified once. The order + of the options is not significant. + + If the server supports option negotiation, and it recognizes one or + more of the options specified in the request packet, the server may + respond with an Options Acknowledgment (OACK). Each option the + server recognizes, and accepts the value for, is included in the + OACK. Some options may allow alternate values to be proposed, but + this is an option specific feature. The server must not include in + the OACK any option which had not been specifically requested by the + client; that is, only the client may initiate option negotiation. + Options which the server does not support should be omitted from the + OACK; they should not cause an ERROR packet to be generated. If the + value of a supported option is invalid, the specification for that + option will indicate whether the server should simply omit the option + from the OACK, respond with an alternate value, or send an ERROR + packet, with error code 8, to terminate the transfer. + + An option not acknowledged by the server must be ignored by the + client and server as if it were never requested. If multiple options + were requested, the client must use those options which were + acknowledged by the server and must not use those options which were + not acknowledged by the server. + + + + + +Malkin & Harkin Standards Track [Page 3] + +RFC 2347 TFTP Option Extension May 1998 + + + When the client appends options to the end of a Read Request packet, + three possible responses may be returned by the server: + + OACK - acknowledge of Read Request and the options; + + DATA - acknowledge of Read Request, but not the options; + + ERROR - the request has been denied. + + When the client appends options to the end of a Write Request packet, + three possible responses may be returned by the server: + + OACK - acknowledge of Write Request and the options; + + ACK - acknowledge of Write Request, but not the options; + + ERROR - the request has been denied. + + If a server implementation does not support option negotiation, it + will likely ignore any options appended to the client's request. In + this case, the server will return a DATA packet for a Read Request + and an ACK packet for a Write Request establishing normal TFTP data + transfer. In the event that a server returns an error for a request + which carries an option, the client may attempt to repeat the request + without appending any options. This implementation option would + handle servers which consider extraneous data in the request packet + to be erroneous. + + Depending on the original transfer request there are two ways for a + client to confirm acceptance of a server's OACK. If the transfer was + initiated with a Read Request, then an ACK (with the data block + number set to 0) is sent by the client to confirm the values in the + server's OACK packet. If the transfer was initiated with a Write + Request, then the client begins the transfer with the first DATA + packet, using the negotiated values. If the client rejects the OACK, + then it sends an ERROR packet, with error code 8, to the server and + the transfer is terminated. + + Once a client acknowledges an OACK, with an appropriate non-error + response, that client has agreed to use only the options and values + returned by the server. Remember that the server cannot request an + option; it can only respond to them. If the client receives an OACK + containing an unrequested option, it should respond with an ERROR + packet, with error code 8, and terminate the transfer. + + + + + + + +Malkin & Harkin Standards Track [Page 4] + +RFC 2347 TFTP Option Extension May 1998 + + +Examples + + Read Request + + client server + ------------------------------------------------------- + |1|foofile|0|octet|0|blksize|0|1432|0| --> RRQ + <-- |6|blksize|0|1432|0| OACK + |4|0| --> ACK + <-- |3|1| 1432 octets of data | DATA + |4|1| --> ACK + <-- |3|2| 1432 octets of data | DATA + |4|2| --> ACK + <-- |3|3|<1432 octets of data | DATA + |4|3| --> ACK + + Write Request + + client server + ------------------------------------------------------- + |2|barfile|0|octet|0|blksize|0|2048|0| --> RRQ + <-- |6|blksize|0|2048|0| OACK + |3|1| 2048 octets of data | --> DATA + <-- |4|1| ACK + |3|2| 2048 octets of data | --> DATA + <-- |4|2| ACK + |3|3|<2048 octets of data | --> DATA + <-- |4|3| ACK + +Security Considerations + + The basic TFTP protocol has no security mechanism. This is why it + has no rename, delete, or file overwrite capabilities. This document + does not add any security to TFTP; however, the specified extensions + do not add any additional security risks. + +References + + [1] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + October 1992. + + [2] Malkin, G., and A. Harkin, "TFTP Blocksize Option", RFC 2348, + May 1998. + + [3] Malkin, G., and A. Harkin, "TFTP Timeout Interval and Transfer + Size Options", RFC 2349, May 1998. + + + + + +Malkin & Harkin Standards Track [Page 5] + +RFC 2347 TFTP Option Extension May 1998 + + +Authors' Addresses + + Gary Scott Malkin + Bay Networks + 8 Federal Street + Billerica, MA 01821 + + Phone: (978) 916-4237 + EMail: gmalkin@baynetworks.com + + + Art Harkin + Internet Services Project + Information Networks Division + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin Standards Track [Page 6] + +RFC 2347 TFTP Option Extension May 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin Standards Track [Page 7] + diff --git a/doc/rfc2348.txt b/doc/rfc2348.txt new file mode 100644 index 0000000..b38c56d --- /dev/null +++ b/doc/rfc2348.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group G. Malkin +Request for Commments: 2348 Bay Networks +Updates: 1350 A. Harkin +Obsoletes: 1783 Hewlett Packard Co. +Category: Standards Track May 1998 + + + TFTP Blocksize Option + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + The Trivial File Transfer Protocol [1] is a simple, lock-step, file + transfer protocol which allows a client to get or put a file onto a + remote host. One of its primary uses is the booting of diskless + nodes on a Local Area Network. TFTP is used because it is very + simple to implement in a small node's limited ROM space. However, + the choice of a 512-octet blocksize is not the most efficient for use + on a LAN whose MTU may 1500 octets or greater. + + This document describes a TFTP option which allows the client and + server to negotiate a blocksize more applicable to the network + medium. The TFTP Option Extension mechanism is described in [2]. + +Blocksize Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the blocksize option as follows. Note that all fields except "opc" + are NULL-terminated. + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | blksize| 0 | #octets| 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + + +Malkin & Harkin Standards Track [Page 1] + +RFC 2348 TFTP Blocksize Option May 1998 + + + filename + The name of the file to be read or written, as defined in [1]. + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. + + blksize + The Blocksize option, "blksize" (case in-sensitive). + + #octets + The number of octets in a block, specified in ASCII. Valid + values range between "8" and "65464" octets, inclusive. The + blocksize refers to the number of data octets; it does not + include the four octets of TFTP header. + + For example: + + +-------+--------+---+--------+---+--------+---+--------+---+ + | 1 | foobar | 0 | octet | 0 | blksize| 0 | 1428 | 0 | + +-------+--------+---+--------+---+--------+---+--------+---+ + + is a Read Request, for the file named "foobar", in octet (binary) + transfer mode, with a block size of 1428 octets (Ethernet MTU, less + the TFTP, UDP and IP header lengths). + + If the server is willing to accept the blocksize option, it sends an + Option Acknowledgment (OACK) to the client. The specified value must + be less than or equal to the value specified by the client. The + client must then either use the size specified in the OACK, or send + an ERROR packet, with error code 8, to terminate the transfer. + + The rules for determining the final packet are unchanged from [1]. + The reception of a data packet with a data length less than the + negotiated blocksize is the final packet. If the blocksize is + greater than the amount of data to be transfered, the first packet is + the final packet. If the amount of data to be transfered is an + integral multiple of the blocksize, an extra data packet containing + no data is sent to end the transfer. + +Proof of Concept + + Performance tests were run on the prototype implementation using a + variety of block sizes. The tests were run on a lightly loaded + Ethernet, between two HP-UX 9000, in "octet" mode, on 2.25MB files. + The average (5x) transfer times for paths with (g-time) and without + (n-time) a intermediate gateway are graphed as follows: + + + + +Malkin & Harkin Standards Track [Page 2] + +RFC 2348 TFTP Blocksize Option May 1998 + + + | + 37 + g + | + 35 + + | + 33 + + | + 31 + + | + 29 + + | + 27 + + | g blocksize n-time g-time + 25 + --------- ------ ------ + s | n 512 23.85 37.05 + e 23 + g 1024 16.15 25.65 + c | 1428 13.70 23.10 + o 21 + 2048 10.90 16.90 + n | 4096 6.85 9.65 + d 19 + 8192 4.90 6.15 + s | + 17 + g + | n + 15 + + | n + 13 + + | + 11 + n + | g + 9 + + | + 7 + n + | g + 5 + n + " + 0 +------+------+--+---+------+------+--- + 512 1K | 2K 4K 8K + 1428 + blocksize (octets) + + The comparisons between transfer times (without a gateway) between + the standard 512-octet blocksize and the negotiated blocksizes are: + + 1024 2x -32% + 1428 2.8x -42% + 2048 4x -54% + 4096 8x -71% + 8192 16x -80% + + + +Malkin & Harkin Standards Track [Page 3] + +RFC 2348 TFTP Blocksize Option May 1998 + + + As was anticipated, the transfer time decreases with an increase in + blocksize. The reason for the reduction in time is the reduction in + the number of packets sent. For example, by increasing the blocksize + from 512 octets to 1024 octets, not only are the number of data + packets halved, but the number of acknowledgement packets is also + halved (along with the number of times the data transmitter must wait + for an ACK). A secondary effect is the efficiency gained by reducing + the per-packet framing and processing overhead. + + Of course, if the blocksize exceeds the path MTU, IP fragmentation + and reassembly will begin to add more overhead. This will be more + noticable the greater the number of gateways in the path. + +Security Considerations + + The basic TFTP protocol has no security mechanism. This is why it + has no rename, delete, or file overwrite capabilities. This document + does not add any security to TFTP; however, the specified extensions + do not add any additional security risks. + +References + + [1] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + October 1992. + + [2] Malkin, G., and A. Harkin, "TFTP Option Extension", RFC 2347, + May 1998. + +Authors' Addresses + + Gary Scott Malkin + Bay Networks + 8 Federal Street + Billerica, MA 10821 + + Phone: (978) 916-4237 + EMail: gmalkin@baynetworks.com + + + Art Harkin + Networked Computing Division + Hewlett-Packard Company + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + +Malkin & Harkin Standards Track [Page 4] + +RFC 2348 TFTP Blocksize Option May 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin Standards Track [Page 5] + diff --git a/doc/rfc2349.txt b/doc/rfc2349.txt new file mode 100644 index 0000000..31abb3e --- /dev/null +++ b/doc/rfc2349.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group G. Malkin +Request for Commments: 2349 Bay Networks +Updates: 1350 A. Harkin +Obsoletes: 1784 Hewlett Packard Co. +Category: Standards Track May 1998 + + + TFTP Timeout Interval and Transfer Size Options + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + The Trivial File Transfer Protocol [1] is a simple, lock-step, file + transfer protocol which allows a client to get or put a file onto a + remote host. + + This document describes two TFTP options. The first allows the client + and server to negotiate the Timeout Interval. The second allows the + side receiving the file to determine the ultimate size of the + transfer before it begins. The TFTP Option Extension mechanism is + described in [2]. + +Timeout Interval Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the timeout option as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | timeout| 0 | #secs | 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + + + + + +Malkin & Harkin Standards Track [Page 1] + +RFC 2349 TFTP Timeout Interval and Transfer Size Options May 1998 + + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + timeout + The Timeout Interval option, "timeout" (case in-sensitive). + This is a NULL-terminated field. + + #secs + The number of seconds to wait before retransmitting, specified + in ASCII. Valid values range between "1" and "255" seconds, + inclusive. This is a NULL-terminated field. + + For example: + + +-------+--------+---+--------+---+--------+---+-------+---+ + | 1 | foobar | 0 | octet | 0 | timeout| 0 | 1 | 0 | + +-------+--------+---+--------+---+--------+---+-------+---+ + + is a Read Request, for the file named "foobar", in octet (binary) + transfer mode, with a timeout interval of 1 second. + + If the server is willing to accept the timeout option, it sends an + Option Acknowledgment (OACK) to the client. The specified timeout + value must match the value specified by the client. + +Transfer Size Option Specification + + The TFTP Read Request or Write Request packet is modified to include + the tsize option as follows: + + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + | opc |filename| 0 | mode | 0 | tsize | 0 | size | 0 | + +-------+---~~---+---+---~~---+---+---~~---+---+---~~---+---+ + + opc + The opcode field contains either a 1, for Read Requests, or 2, + for Write Requests, as defined in [1]. + + filename + The name of the file to be read or written, as defined in [1]. + This is a NULL-terminated field. + + + + + +Malkin & Harkin Standards Track [Page 2] + +RFC 2349 TFTP Timeout Interval and Transfer Size Options May 1998 + + + mode + The mode of the file transfer: "netascii", "octet", or "mail", + as defined in [1]. This is a NULL-terminated field. + + tsize + The Transfer Size option, "tsize" (case in-sensitive). This is + a NULL-terminated field. + + size + The size of the file to be transfered. This is a NULL- + terminated field. + + For example: + + +-------+--------+---+--------+---+--------+---+--------+---+ + | 2 | foobar | 0 | octet | 0 | tsize | 0 | 673312 | 0 | + +-------+--------+---+--------+---+--------+---+--------+---+ + + is a Write Request, with the 673312-octet file named "foobar", in + octet (binary) transfer mode. + + In Read Request packets, a size of "0" is specified in the request + and the size of the file, in octets, is returned in the OACK. If the + file is too large for the client to handle, it may abort the transfer + with an Error packet (error code 3). In Write Request packets, the + size of the file, in octets, is specified in the request and echoed + back in the OACK. If the file is too large for the server to handle, + it may abort the transfer with an Error packet (error code 3). + +Security Considerations + + The basic TFTP protocol has no security mechanism. This is why it + has no rename, delete, or file overwrite capabilities. This document + does not add any security to TFTP; however, the specified extensions + do not add any additional security risks. + +References + + [1] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, + October 92. + + [2] Malkin, G., and A. Harkin, "TFTP Option Extension", RFC 2347, + May 1998. + + + + + + + + +Malkin & Harkin Standards Track [Page 3] + +RFC 2349 TFTP Timeout Interval and Transfer Size Options May 1998 + + +Authors' Addresses + + Gary Scott Malkin + Bay Networks + 8 Federal Street + Billerica, MA 01821 + + Phone: (978) 916-4237 + EMail: gmalkin@baynetworks.com + + + Art Harkin + Internet Services Project + Information Networks Division + 19420 Homestead Road MS 43LN + Cupertino, CA 95014 + + Phone: (408) 447-3755 + EMail: ash@cup.hp.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin Standards Track [Page 4] + +RFC 2349 TFTP Timeout Interval and Transfer Size Options May 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Malkin & Harkin Standards Track [Page 5] + diff --git a/doc/rfc783.txt b/doc/rfc783.txt new file mode 100644 index 0000000..04dce94 --- /dev/null +++ b/doc/rfc783.txt @@ -0,0 +1,969 @@ + + + +Network Working Group K. R. Sollins +Request for Comments: 783 MIT + June, 1981 +Updates: IEN 133 + + + THE TFTP PROTOCOL (REVISION 2) + + + + Summary + + TFTP is a very simple protocol used to transfer files. It is from + +this that its name comes, Trivial File Transfer Protocol or TFTP. Each + +nonterminal packet is acknowledged separately. This document describes + +the protocol and its types of packets. The document also explains the + +reasons behind some of the design decisions. + + + + ACKNOWLEDGEMENTS + + + The protocol was originally designed by Noel Chiappa, and was + +redesigned by him, Bob Baldwin and Dave Clark, with comments from Steve + +Szymanski. The current revision of the document includes modifications + +stemming from discussions with and suggestions from Larry Allen, Noel + +Chiappa, Dave Clark, Geoff Cooper, Mike Greenwald, Liza Martin, David + +Reed, Craig Milo Rogers (of UCS-ISI), Kathy Yellick, and the author. + +The acknowledgement and retransmission scheme was inspired by TCP, and + +the error mechanism was suggested by PARC's EFTP abort message. + + + + + + + + + + + + + + + + + + +This research was supported by the Advanced Research Projects Agency of + +the Department of Defense and was monitored by the Office of Naval + +Research under contract number N00014-75-C-0661. + + + + + + + + + + + + + + + + 2 + + +1. Purpose + + TFTP is a simple protocol to transfer files, and therefore was named + +the Trivial File Transfer Protocol or TFTP. It has been implemented on + +top of the Internet User Datagram protocol (UDP or Datagram) [2] so it + +may be used to move files between machines on different networks + +implementing UDP. (This should not exlude the possibility of + +implementing TFTP on top of other datagram protocols.) It is designed + +to be small and easy to implement. Therefore, it lacks most of the + +features of a regular FTP. The only thing it can do is read and write + +files (or mail) from/to a remote server. It cannot list directories, + +and currently has no provisions for user authentication. In common with + +other Internet protocols, it passes 8 bit bytes of data. + + + 1 2 + Three modes of transfer are currently supported: netascii ; octet , + +raw 8 bit bytes; mail, netascii characters sent to a user rather than a + +file. Additional modes can be defined by pairs of cooperating hosts. + + + + + + + + + + + +_______________ + 1 + This is ascii as defined in "USA Standard Code for Information +Interchange" [1] with the modifications specified in "Telnet Protocol +Specification" [3]. Note that it is 8 bit ascii. The term "netascii" +will be used throughout this document to mean this particular version of +ascii. + 2 + This replaces the "binary" mode of previous versions of this + + + + 3 + + +2. Overview of the Protocol + + Any transsfer begins with a request to read or write a file, which also + +serves to request a connection. If the server grants the request, the + +connection is opened and the file is sent in fixed length blocks of 512 + +bytes. Each data packet contains one block of data, and must be + +acknowledged by an acknowledgment packet before the next packet can be + +sent. A data packet of less than 512 bytes signals termination of a + +transfer. If a packet gets lost in the network, the intended recipient + +will timeout and may retransmit his last packet (which may be data or an + +acknowledgment), thus causing the sender of the lost packet to + +retransmit that lost packet. The sender has to keep just one packet on + +hand for retransmission, since the lock step acknowledgment guarantees + +that all older packets have been received. Notice that both machines + +involved in a transfer are considered senders and receivers. One sends + +data and receives acknowledgments, the other sends acknowledgments and + +receives data. + + + + Most errors cause termination of the connection. An error is + +signalled by sending an error packet. This packet is not acknowledged, + +and not retransmitted (i.e., a TFTP server or user may terminate after + +sending an error message), so the other end of the connection may not + +get it. Therefore timeouts are used to detect such a termination when + +the error packet has been lost. Errors are caused by three types of + +events: not being able to satisfy the request (e.g., file not found, + +access violation, or no such user), receiving a packet which cannot be + +explained by a delay or duplication in the network (e.g. an incorrectly + + + 4 + + +formed packet), and losing access to a necessary resource (e.g., disk + +full or access denied during a transfer). + + + + TFTP recognizes only one error condition that does not cause + +termination, the source port of a received packet being incorrect. In + +this case, an error packet is sent to the originating host. + + + + This protocol is very restrictive, in order to simplify + +implementation. For example, the fixed length blocks make allocation + +straight forward, and the lock step acknowledgement provides flow + +control and eliminates the need to reorder incoming data packets. + + + +3. Relation to other Protocols + + As mentioned TFTP is designed to be implemented on top of the Datagram + +protocol. Since Datagram is implemented on the Internet protocol, + +packets will have an Internet header, a Datagram header, and a TFTP + +header. Additionally, the packets may have a header (LNI, ARPA header, + +etc.) to allow them through the local transport medium. As shown in + +Figure 3-1, the order of the contents of a packet will be: local medium + +header, if used, Internet header, Datagram header, TFTP header, followed + +by the remainder of the TFTP packet. (This may or may not be data + +depending on the type of packet as specified in the TFTP header.) TFTP + +does not specify any of the values in the Internet header. On the other + +hand, the source and destination port fields of the Datagram header (its + +format is given in the appendix) are used by TFTP and the length field + +reflects the size of the TFTP packet. The transfer identifiers (TID's) + + + 5 + + +used by TFTP are passed to the Datagram layer to be used as ports; + +therefore they must be between 0 and 65,535. The initialization of + +TID's is discussed in the section on initial connection protocol. + + + + The TFTP header consists of a 2 byte opcode field which indicates the + +packet's type (e.g., DATA, ERROR, etc.) These opcodes and the formats + +of the various types of packets are discussed further in the section on + +TFTP packets. + + Figure 3-1: Order of Headers + + + + + --------------------------------------------------- + | Local Medium | Internet | Datagram | TFTP | + --------------------------------------------------- + + + +4. Initial Connection Protocol + + A transfer is established by sending a request (WRQ to write onto a + +foreign file system, or RRQ to read from it), and receiving a positive + +reply, an acknowledgment packet for write, or the first data packet for + +read. In general an acknowledgment packet will contain the block number + +of the data packet being acknowledged. Each data packet has associated + +with it a block number; block numbers are consecutive and begin with + +one. Since the positive response to a write request is an + +acknowledgment packet, in this special case the block number will be + +zero. (Normally, since an acknowledgment packet is acknowledging a data + +packet, the acknowledgment packet will contain the block number of the + +data packet being acknowledged.) If the reply is an error packet, then + + + 6 + + +the request has been denied. + + + + In order to create a connection, each end of the connection chooses a + +TID for itself, to be used for the duration of that connection. The + +TID's chosen for a connection should be randomly chosen, so that the + +probability that the same number is chosen twice in immediate succession + +is very low. Every packet has associated with it the two TID's of the + +ends of the connection, the source TID and the destination TID. These + +TID's are handed to the supporting UDP (or other datagram protocol) as + +the source and destination ports. A requesting host chooses its source + +TID as described above, and sends its initial request to the known TID + +69 decimal (105 octal) on the serving host. The response to the + +request, under normal operation, uses a TID chosen by the server as its + +source TID and the TID chosen for the previous message by the requestor + +as its destination TID. The two chosen TID's are then used for the + +remainder of the transfer. + + + As an example, the following shows the steps used to establish a + +connection to write a file. Note that WRQ, ACK, and DATA are the names + +of the write request, acknowledgment, and data types of packets + +respectively. The appendix contains a similar example for reading a + +file. + + + 1. Host A sends a "WRQ" to host B with source= A's TID, + destination= 69. + + + 2. Host B sends a "ACK" (with block number= 0) to host A with + source= B's TID, destination= A's TID. + + + 7 + + +At this point the connection has been established and the first data + +packet can be sent by Host A with a sequence number of 1. In the next + +step, and in all succeeding steps, the hosts should make sure that the + +source TID matches the value that was agreed on in steps 1 and 2. If a + +source TID does not match, the packet should be discarded as erroneously + +sent from somewhere else. An error packet should be sent to the source + +of the incorrect packet, while not disturbing the transfer. + +This can be done only if the TFTP in fact receives a packet with an + +incorrect TID. If the supporting protocols do not allow it, this + +particular error condition will not arise. + + + + + The following example demonstrates a correct operation of the protocol + +in which the above situation can occur. Host A sends a request to host + +B. Somewhere in the network, the request packet is duplicated, and as a + +result two acknowledgments are returned to host A, with different TID's + +chosen on host B in response to the two requests. When the first + +response arrives, host A continues the connection. When the second + +response to the request arrives, it should be rejected, but there is no + +reason to terminate the first connection. Therefore, if different TID's + +are chosen for the two connections on host B and host A checks the + +source TID's of the messages it receives, the first connection can be + +maintained while the second is rejected by returning an error packet. + + + + + + + 8 + + +5. TFTP Packets + + TFTP supports five types of packets, all of which have been mentioned + +above: + + + opcode operation + 1 Read request (RRQ) + 2 Write request (WRQ) + 3 Data (DATA) + 4 Acknowledgment (ACK) + 5 Error (ERROR) + + +The TFTP header of a packet contains the opcode associated with that + +packet. + + Figure 5-1: RRQ/WRQ packet + + + + + 2 bytes string 1 byte string 1 byte + ------------------------------------------------ + | Opcode | Filename | 0 | Mode | 0 | + ------------------------------------------------ + + + + RRQ and WRQ packets (opcodes 1 and 2 respectively) have the format + +shown in Figure 5-1. The file name is a sequence of bytes in netascii + +terminated by a zero byte. The mode field contains the string + +"netascii", "octet", or "mail" (or any comibnation of upper and lower + +case, such as "NETASCII", NetAscii", etc.) in netascii indicating the + +three modes defined in the protocol. A host which receives netascii + +mode data must translate the data to its own format. Octet mode is used + +to transfer a file that is in the 8-bit format of the machine from which + +the file is being transferred. It is assumed that each type of machine + +has a single 8-bit format that is more common, and that that format is + + + 9 + + +chosen. For example, on a DEC-20, a 36 bit machine, this is four 8-bit + +bytes to a word with four bits of breakage. If a host receives a octet + +file and then returns it, the returned file must be identical to the + +original. Mail mode uses the name of a mail recipient in place of a + +file and must begin with a WRQ. Otherwise it is identical to netascii + +mode. The mail recipient string should be of the form "username" or + +"username@hostname". If the second form is used, it allows the option + +of mail forwarding by a relay computer. + + + + The discussion above assumes that both the sender and recipient are + +operating in the same mode, but there is no reason that this has to be + +the case. For example, one might build a storage server. There is no + +reason that such a machine needs to translate netascii into its own form + +of text. Rather, the sender might send files in netascii, but the + +storage server might simply store them without translation in 8-bit + +format. Another such situation is a problem that currently exists on + +DEC-20 systems. Neither netascii nor octet accesses all the bits in a + +word. One might create a special mode for such a machine which read all + +the bits in a word, but in which the receiver stored the information in + +8-bit format. When such a file is retrieved from the storage site, it + +must be restored to its original form to be useful, so the reverse mode + +must also be implemented. The user site will have to remember some + +information to achieve this. In both of these examples, the request + +packets would specify octet mode to the foreign host, but the local host + +would be in some other mode. No such machine or application specific + +modes have been specified in TFTP, but one would be compatible with this + + + 10 + + +specification. + + + + It is also possible to define other modes for cooperating pairs of + +hosts, although this must be done with care. There is no requirement + +that any other hosts implement these. There is no central authority + +that will define these modes or assign them names. + + Figure 5-2: DATA packet + + + + + 2 bytes 2 bytes n bytes + ---------------------------------- + | Opcode | Block # | Data | + ---------------------------------- + + + + Data is actually transferred in DATA packets depicted in Figure 5-2. + +DATA packets (opcode = 3) have a block number and data field. The block + +numbers on data packets begin with one and increase by one for each new + +block of data. This restriction allows the program to use a single + +number to discriminate between new packets and duplicates. The data + +field is from zero to 512 bytes long. If it is 512 bytes long, the + +block is not the last block of data; if it is from zero to 511 bytes + +long, it signals the end of the transfer. (See the section on Normal + +Termination for details.) + + + + All packets other than those used for termination are acknowledged + +individually unless a timeout occurs. Sending a DATA packet is an + +acknowledgment for the ACK packet of the previous DATA packet. The WRQ + +and DATA packets are acknowledged by ACK or ERROR packets, while RRQ and + + + 11 + + + Figure 5-3: ACK packet + + + + + 2 bytes 2 bytes + --------------------- + | Opcode | Block # | + --------------------- + + +ACK packets are acknowledged by DATA or ERROR packets. Figure 5-3 + +depicts an ACK packet; the opcode is 4. The block number in an ACK + +echoes the block number of the DATA packet being acknowledged. A WRQ is + +acknowledged with an ACK packet having a block number of zero. + + Figure 5-4: ERROR packet + + + + + 2 bytes 2 bytes string 1 byte + ----------------------------------------- + | Opcode | ErrorCode | ErrMsg | 0 | + ----------------------------------------- + + + + An ERROR packet (opcode 5) takes the form depicted in Figure 5-4. An + +ERROR packet can be the acknowledgment of any other type of packet. The + +error code is an integer indicating the nature of the error. A table of + +values and meanings is given in the appendix. (Note that several error + +codes have been added to this version of this document.) The error + +message is intended for human consumption, and should be in netascii. + +Like all other strings, it is terminated with a zero byte. + + + + + + + + + 12 + + +6. Normal Termination + + The end of a transfer is marked by a DATA packet that contains between + +0 and 511 bytes of data (i.e. Datagram length < 516). This packet is + +acknowledged by an ACK packet like all other DATA packets. The host + +acknowledging the final DATA packet may terminate its side of the + +connection on sending the final ACK. On the other hand, dallying is + +encouraged. This means that the host sending the final ACK will wait + +for a while before terminating in order to retransmit the final ACK if + +it has been lost. The acknowledger will know that the ACK has been lost + +if it receives the final DATA packet again. The host sending the last + +DATA must retransmit it until the packet is acknowledged or the sending + +host times out. If the response is an ACK, the transmission was + +completed successfully. If the sender of the data times out and is not + +prepared to retransmit any more, the transfer may still have been + +completed successfully, after which the acknowledger or network may have + +experienced a problem. It is also possible in this case that the + +transfer was unsuccessful. In any case, the connection has been closed. + + + +7. Premature Termination + + If a request can not be granted, or some error occurs during the + +transfer, then an ERROR packet (opcode 5) is sent. This is only a + +courtesy since it will not be retransmitted or acknowledged, so it may + +never be received. Timeouts must also be used to detect errors. + + + + + + 13 + + +I. Appendix + + +Order of Headers + + + 2 bytes + ---------------------------------------------------------- +| Local Medium | Internet | Datagram | TFTP Opcode | + ---------------------------------------------------------- + + +TFTP Formats + + +Type Op # Format without header + 2 bytes string 1 byte string 1 byte + ----------------------------------------------- +RRQ/ | 01/02 | Filename | 0 | Mode | 0 | +WRQ ----------------------------------------------- + 2 bytes 2 bytes n bytes + --------------------------------- +DATA | 03 | Block # | Data | + --------------------------------- + 2 bytes 2 bytes + ------------------- +ACK | 04 | Block # | + -------------------- + 2 bytes 2 bytes string 1 byte + ---------------------------------------- +ERROR | 05 | ErrorCode | ErrMsg | 0 | + ---------------------------------------- + + + + + + + + + + + + + + + + + + + 14 + + +Initial Connection Protocol for reading a file + + + 1. Host A sends a "RRQ" to host B with source= A's TID, + destination= 69. + + 2. Host B sends a "DATA" (with block number= 1) to host A with + source= B's TID, destination= A's TID. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 15 + + +Error Codes + + +Value Meaning +0 Not defined, see error message (if any). +1 File not found. +2 Access violation. +3 Disk full or allocation exceeded. +4 Illegal TFTP operation. +5 Unknown transfer ID. +6 File already exists. +7 No such user. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 16 + + 3 +Internet User Datagram Header [2] + + + Format + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Source Port | Destination Port | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Length | Checksum | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Values of Fields + + +Source Port Picked by originator of packet. + + +Dest. Port Picked by destination machine (69 for RRQ or WRQ). + + +Length Number of bytes in packet after Datagram header. + + 4 +Checksum Reference 2 describes rules for computing checksum. + Field contains zero if unused. + + +Note: TFTP passes transfer identifiers (TID's) to the Internet User + +Datagram protocol to be used as the source and destination ports. + + + + + + + + + + + + +_______________ + 3 + This has been included only for convenience. TFTP need not be +implemented on top of the Internet User Datagram Protocol. + 4 + The implementor of this should be sure that the correct algorithm is +used here. + + + 17 + + +References + + [1] USA Standard Code for Information Interchange, USASI X3.4- + + 1968. + + + + [2] Postel, Jon., "User Datagram Protocol," RFC768, August 28, + + 1980. + + + + [3] "Telnet Protocol Specification," RFC764, June, 1980. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 18 diff --git a/src/lib/server.zig b/src/lib/server.zig new file mode 100644 index 0000000..c7b10c4 --- /dev/null +++ b/src/lib/server.zig @@ -0,0 +1,422 @@ +const std = @import("std"); + +const log = std.log.scoped(.server); + +const Packet = @import("packet.zig").Packet; +const Decoder = @import("netascii.zig").Decoder; + +pub fn Server(comptime T: type) type { + return struct { + pub const Self = @This(); + + app: *T, + address: std.Io.net.IpAddress, + + pub fn init(app: *T, address: std.Io.net.IpAddress) Self { + return .{ + .app = app, + .address = address, + }; + } + + pub fn run( + self: *Self, + io: std.Io, + alloc: std.mem.Allocator, + ) !void { + const socket = try self.address.bind(io, .{ .mode = .dgram, .protocol = .udp }); + defer socket.close(io); + + var group: std.Io.Group = .init; + defer group.cancel(io); + + while (true) { + const packet_queue_size = 5; + var messages: [packet_queue_size]std.Io.net.IncomingMessage = @splat(.init); + var buffer: [packet_queue_size * Packet.BUFFER_LENGTH]u8 = undefined; + const err_, const count = socket.receiveManyTimeout(io, &messages, &buffer, .{}, .{ + .duration = .{ + .clock = .real, + .raw = .fromMilliseconds(250), + }, + }); + + for (messages[0..count]) |message| { + const data = try alloc.dupe(u8, message.data); + try group.concurrent(io, handleIncomingMessage, .{ + self, + io, + alloc, + message.from, + data, + }); + } + + if (err_) |err| { + switch (err) { + error.Timeout => {}, + else => return err, + } + } + } + } + + pub fn handleIncomingMessage( + self: *Self, + io: std.Io, + alloc: std.mem.Allocator, + remote: std.Io.net.IpAddress, + data: []const u8, + ) error{Canceled}!void { + self._handleIncomingMessage(io, alloc, remote, data) catch |err| switch (err) { + // error.Canceled => return error.Canceled, + else => |e| { + log.warn("handle incoming message failed with {t}", .{e}); + }, + }; + } + + fn _handleIncomingMessage( + self: *Self, + io: std.Io, + alloc: std.mem.Allocator, + remote: std.Io.net.IpAddress, + initial_data: []const u8, + ) !void { + defer alloc.free(initial_data); + + // Create new socket with a random port to handle further communication with + // the remote system. + var local = self.address; + local.setPort(0); + const socket = try local.bind(io, .{ .mode = .dgram, .protocol = .udp }); + + var input_buf: [std.math.maxInt(u16)]u8 = undefined; + const initial: Packet = try .decode(initial_data, &input_buf, .{}); + + log.info("initial {t} packet from {f}", .{ initial, remote }); + + switch (initial) { + .wrq => |*wrq| { + log.info("wrq: {s}", .{wrq.filename}); + + try self.handleWrite(io, alloc, socket, &remote, wrq); + }, + .rrq => |*rrq| { + log.info("rrq: {s}", .{rrq.filename}); + + try self.handleRead(io, alloc, socket, &remote, rrq); + }, + else => { + const packet: Packet = .{ + .err = .{ + .code = .illegal_operation, + }, + }; + var output_buf: Packet.Buffer = undefined; + const d = try packet.encode(&output_buf); + try socket.send(io, &remote, d); + return; + }, + } + } + + fn handleWrite( + self: *Self, + io: std.Io, + alloc: std.mem.Allocator, + socket: std.Io.net.Socket, + remote: *const std.Io.net.IpAddress, + wrq: *const Packet.Wrq, + ) !void { + var request = self.app.writeTo(io, alloc, wrq.filename) catch |err| switch (err) { + error.PermissionDenied => { + var output_buf: Packet.Buffer = undefined; + const output_packet: Packet = .{ + .err = .{ + .code = .access_violation, + }, + }; + const d = try output_packet.encode(&output_buf); + try socket.send(io, remote, d); + return; + }, + else => |e| return e, + }; + defer request.deinit(io, alloc); + + var netascii_buffer: [128]u8 = undefined; + var netascii_decoder: Decoder = undefined; + const writer = switch (wrq.mode) { + .netascii, .mail => writer: { + netascii_decoder = .init(try request.writer(io, alloc), &netascii_buffer); + break :writer &netascii_decoder.interface; + }, + .octet => try request.writer(io, alloc), + }; + + var block: u16 = 0; + + var timeout: TimeoutHandler = .init(io, .fromSeconds(@max(1, wrq.options.timeout orelse 30))); + + var count: usize = 0; + + while (true) { + // Send an acknowlegdment of the packet that we just received. + { + var output_buf: Packet.Buffer = undefined; + const output_packet: Packet = packet: { + if (block == 0) { + if (wrq.options.empty()) break :packet .{ + .ack = .{ + .block = 0, + }, + }; + break :packet .{ + .oack = .{ + .options = wrq.options, + }, + }; + } + break :packet .{ + .ack = .{ + .block = block, + }, + }; + }; + + try socket.send(io, remote, try output_packet.encode(&output_buf)); + } + + // Wait for a new packet from the remote. + var input_message_buf: Packet.Buffer = undefined; + const input_message = socket.receiveTimeout(io, &input_message_buf, timeout.next()) catch |err| switch (err) { + error.Timeout => { + if (timeout.elapsed(io)) return error.Timeout; + continue; + }, + else => |e| return e, + }; + + // Check to make sure that the packet came from the correct source. + if (!remote.eql(&input_message.from)) return error.PacketFromInvalidSource; + + // decode the packet + var input_packet_buf: Packet.Buffer = undefined; + const input_packet: Packet = try .decode(input_message.data, &input_packet_buf, .{ + .mode = wrq.mode, + .blocksize = wrq.options.blocksize, + }); + + switch (input_packet) { + .data => |data| { + timeout.reset(io); + block = data.block; + log.warn("received {d} bytes, last: {}", .{ data.data.len, data.last }); + + try writer.writeAll(data.data); + count += data.data.len; + + if (data.last) { + log.info("last packet received, {d} bytes read from the network", .{count}); + const packet: Packet = .{ + .ack = .{ + .block = block, + }, + }; + var output_buf: Packet.Buffer = undefined; + try socket.send(io, remote, try packet.encode(&output_buf)); + try writer.flush(); + try request.finish(io); + return; + } + }, + .err => { + return error.ErrorReceived; + }, + .rrq, + .wrq, + .ack, + .oack, + => { + var output_buf: Packet.Buffer = undefined; + const packet: Packet = .{ + .err = .{ + .code = .illegal_operation, + }, + }; + try socket.send(io, remote, try packet.encode(&output_buf)); + log.err("illegal packet type", .{}); + return error.IllegalPacketType; + }, + } + } + } + + fn handleRead( + self: *Self, + io: std.Io, + alloc: std.mem.Allocator, + socket: std.Io.net.Socket, + remote: *const std.Io.net.IpAddress, + rrq: *const Packet.Rrq, + ) !void { + const blocksize = rrq.options.blocksize orelse 512; + var data_buffer_raw: Packet.Buffer = undefined; + const data_buffer = data_buffer_raw[0..blocksize]; + + var request = self.app.readFrom(io, alloc, rrq.filename) catch |err| switch (err) { + error.PermissionDenied => { + var output_buf: Packet.Buffer = undefined; + const output_packet: Packet = .{ + .err = .{ + .code = .access_violation, + }, + }; + const d = try output_packet.encode(&output_buf); + try socket.send(io, remote, d); + return; + }, + else => |e| return e, + }; + defer request.deinit(io, alloc); + + const reader: *std.Io.Reader = try request.reader(io, alloc); + + var timeout: TimeoutHandler = .init(io, .fromSeconds(@max(1, rrq.options.timeout orelse 30))); + var block: u16 = 0; + var block_acked: u16 = 0; + var data: []const u8 = undefined; + var last: bool = false; + while (true) { + { + var output_buf: Packet.Buffer = undefined; + const output_packet: Packet = packet: { + if (block == 0 and !rrq.options.empty()) { + break :packet .{ + .oack = .{ + .options = rrq.options, + }, + }; + } + + if (block == block_acked) { + block += 1; + const len = try reader.readSliceShort(data_buffer); + data = data_buffer[0..len]; + last = len < blocksize; + } + + break :packet .{ + .data = .{ + .block = block, + .data = data, + .mode = rrq.mode, + .last = last, + }, + }; + }; + try socket.send( + io, + remote, + try output_packet.encode(&output_buf), + ); + } + + var input_message_buf: Packet.Buffer = undefined; + const input_message = socket.receiveTimeout(io, &input_message_buf, timeout.next()) catch |err| switch (err) { + error.Timeout => { + if (timeout.elapsed(io)) return error.Timeout; + continue; + }, + else => |e| return e, + }; + + if (!remote.eql(&input_message.from)) return error.PacketFromInvalidSource; + + var input_packet_buf: Packet.Buffer = undefined; + const input_packet: Packet = try .decode( + input_message.data, + &input_packet_buf, + .{ + .mode = rrq.mode, + .blocksize = rrq.options.blocksize, + }, + ); + + switch (input_packet) { + .ack => |ack| { + if (ack.block != block) return error.BlockMismatch; + + if (last) return; + + timeout.reset(io); + block_acked = ack.block; + }, + .err => { + return error.ErrorReceived; + }, + .data, + .rrq, + .wrq, + .oack, + => { + var output_buf: Packet.Buffer = undefined; + const packet: Packet = .{ + .err = .{ + .code = .illegal_operation, + }, + }; + try socket.send(io, remote, try packet.encode(&output_buf)); + log.err("illegal packet type", .{}); + return error.IllegalPacketType; + }, + } + } + } + }; +} + +const TimeoutHandler = struct { + start: std.Io.Timestamp, + limit: std.Io.Duration, + timeout: std.Io.Timeout, + + pub fn init(io: std.Io, limit: std.Io.Duration) TimeoutHandler { + return .{ + .start = .now(io, .real), + .limit = limit, + .timeout = .{ + .duration = .{ + .clock = .real, + .raw = .fromMilliseconds(250), + }, + }, + }; + } + + pub fn elapsed(self: *TimeoutHandler, io: std.Io) bool { + const delta = self.start.untilNow(io, .real); + return delta.toNanoseconds() > self.limit.toNanoseconds(); + } + + pub fn reset(self: *TimeoutHandler, io: std.Io) void { + self.* = .{ + .start = .now(io, .real), + .limit = self.limit, + .timeout = .{ + .duration = .{ + .clock = .real, + .raw = .fromMilliseconds(250), + }, + }, + }; + } + + pub fn next(self: *TimeoutHandler) std.Io.Timeout { + defer { + self.timeout.duration.raw.nanoseconds *= 2; + } + return self.timeout; + } +};