INTERNET-DRAFT M. Johnston expires: 103-Dec-1 Intel Corporation 103-Jun-1 TFTP Directory Op-Code Definition draft-johnston-tftp-directory-00.txt Status of This Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at: http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at: http://www.ietf.org/shadow.html Copyright Notice Copyright (C) The Internet Society (2003). All rights reserved. Abstract This document defines a new TFTP op-code, DATA packet format and option definition that can be used to get a list of files residing in the current logical directory of a TFTP server. M. Johnston draft-johnston-tftp-directory-00.txt [Page 1] Internet Draft TFTP Directory Op-Code 103-Jun-1 Table of Contents Status of This Memo......................................1 Copyright Notice.........................................1 Abstract.................................................1 Table of Contents........................................2 1 Introduction..........................................3 2 Packet Information....................................3 2.1 TFTP Op-Codes.....................................3 2.2 Directory Packet (DIR)............................3 2.3 Option Acknowledgement Packet (OACK)..............4 2.4 Data Packet (DATA)................................4 2.5 Acknowledgement Packet (ACK)......................5 2.6 Error Packet (ERROR)..............................5 3 Examples..............................................6 3.1 Server Does Not Support Directory Op-Code.........6 3.2 Server Does Support Directory Op-Code.............6 4 Security Considerations...............................6 5 References............................................6 6 Author's Address......................................7 7 Full Copyright Statement..............................7 M. Johnston draft-johnston-tftp-directory-00.txt [Page 2] Internet Draft TFTP Directory Op-Code 103-Jun-1 1 Introduction In order to make remote boot applications and OS loaders a little more flexible, this specification defines the concept of a TFTP directory. The fact that the Filename field used by TFTP clients and servers can be implemented as an opaque string of bytes terminated by a null character makes the implementation of the TFTP directory a little different than the typical OS directory command. In order to make the TFTP directory command function properly in all cases, the client must treat the Filename field as an opaque string. It is up to the server to determine the list of files, if any, that reside in the same logical directory and return that list of files and file information to the client. 2 Packet Information Detailed information about TFTP packet op-codes and formats can be found in [1] and [2]. This document only covers changes required when implementing the directory (DIR) op- code. 2.1 TFTP Op-Codes Data (DATA) 3 Acknowledgement (ACK) 4 Error (ERROR) 5 Option Acknowledgement (OACK) 6 Directory (DIR) 7 2.2 Directory Packet (DIR) 2-bytes string string string string ------------------------------------------------------------ | OpCode | Filename | 0 | Mode | 0 | Option | 0 | Value | 0 | ------------------------------------------------------------ The format of the DIR packet is similar to the format of the RRQ and WRQ packets, as defined in [1]. The main difference is which option strings are supported and that the "multicast" option string operates differently. The following TFTP options [2] may be used in the DIR packet (they are not required to be implemented by the TFTP server): "blksize", "timeout", "tsize" and "multicast". M. Johnston draft-johnston-tftp-directory-00.txt [Page 3] Internet Draft TFTP Directory Op-Code 103-Jun-1 The presence of the "multicast" option in the DIR packet directs the TFTP server to return static multicast information about the files in the returned file list. If the TFTP server does not support the DIR op-code, it should return an ERROR packet with the ErrorCode field set to 4 (illegal TFTP operation). Unrecognised and unsupported option strings will be ignored by the TFTP server and will not be returned in the OACK packet. Recognised option strings with invalid value strings will result in an ERROR packet being returned with the ErrorCode field set to 8 (option negotiation error). If the Filename is not present on the TFTP server, an ERROR packet with the ErrorCode field set to 1 (file not found) will be returned. 2.3 Option Acknowledgement Packet (OACK) 2-bytes string string ----------------------------------- | OpCode | Option | 0 | Value | 0 | ----------------------------------- If valid supported options were present in the DIR packet, the server will respond with an OACK packet. The supported option strings in the OACK packet will be identical to those in DIR packet. The value strings received in the OACK packet may have different values than those sent in the DIR packet. If there is "multicast" option string in the OACK packet, its value string will be set to "1" to indicate the presence of static multicast data in the DATA packets. In this case, only files in the current directory with static multicast data will be returned. If there is no static multicast information to be returned, the server must not return the "multicast" option string in the OACK packet. 2.4 Data Packet (DATA) 2-bytes 2-bytes n-bytes ----------------------------- | OpCode | Block# | Data | ----------------------------- M. Johnston draft-johnston-tftp-directory-00.txt [Page 4] Internet Draft TFTP Directory Op-Code 103-Jun-1 The directory listing in the DATA packets consists of a list of two or three variable length ASCII string fields, each terminated by a null character, for each file in the directory. If the "multicast" option string is present in the OACK packet, the first field for each directory entry is the static multicast IP address and UDP port number associated with the Filename. The format of this field is: ip.ip.ip.ip:port If the "multicast" option string is not present in the OACK packet, this field and its terminating null character are not present in the DATA packet. The next field of each directory entry is the Filename and the last field is the file information string. The information string contains the file size and create/modify timestamp. The format of the information string is: filesize yyyy-mm-dd hh:mm:ss.ffff The filesize field is an unsigned 64-bit integer. The year, month, day, hour and minute fields are normal unsigned integers. The seconds field is also unsigned, but it may contain a floating point number (with at most four digits to the right of the decimal point). The timestamp must be UTC. 2.5 Acknowledgement Packet (ACK) 2-bytes 2-bytes ------------------- | OpCode | Block# | ------------------- ACK packets are sent for the OACK and DATA packets as defined in [1] and [2]. 2.6 Error Packet (ERROR) 2-bytes 2-bytes n-bytes ------------------------------------ | OpCode | ErrorCode | ErrorMessage | ------------------------------------ No new ErrorCode values or ErrorMessage strings are defined. M. Johnston draft-johnston-tftp-directory-00.txt [Page 5] Internet Draft TFTP Directory Op-Code 103-Jun-1 3 Examples 3.1 Server Does Not Support Directory Op-Code In this example the client sends a DIR packet. In this case the server responds with an illegal TFTP operation error (ErrorCode 4). client server ----------------------------------------------------------- |7|foofile|0|octet|0| --> RRQ <-- |5|4| Unrecognised Op-Code | DATA 3.2 Server Does Support Directory Op-Code In this example the client sends a DIR packet with a valid Filename. The server responds with a DATA packet containing the directory contents. client server ----------------------------------------------------------- |7|foofile|0|octet|0| --> RRQ <-- |3|1| n octets of data | DATA |4|1| --> ACK <-- |3|2| ACK 4 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. A poorly implemented TFTP directory mechanism makes it easier for malicious programs to determine the names of files on the TFTP server. If the TFTP directory mechanism is implemented, it should only allow the listing of public files. (This caution should not be necessary since private files should not be served by an unsecure protocol like TFTP.) 5 References [1] The TFTP Protocol (Revision 2) RFC 783 M. Johnston draft-johnston-tftp-directory-00.txt [Page 6] Internet Draft TFTP Directory Op-Code 103-Jun-1 [2] TFTP Option Extension RFC 2347 [3] TFTP Blocksize Option RFC 2348 6 Author's Address Michael Johnston Intel Corporation MS. JF1-239 2111 NE 25th Ave. Hillsboro, OR 97124 Phone: +1 503-264-9703 Email: michael.johnston@intel.com 7 Full Copyright Statement Copyright (C) The Internet Society (2003). 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, THE INTERNET ENGINEERING TASK FORCE, THE AUTHOR AND THE AUTHOR'S EMPLOYER DISCLAIM 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. M. Johnston draft-johnston-tftp-directory-00.txt [Page 7] Internet Draft TFTP Directory Op-Code 103-Jun-1 M. Johnston draft-johnston-tftp-directory-00.txt [Page 8]