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|<n octets of data |    DATA 
               |4|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]