[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15

Network Working Group                                            L. Wood
Internet-Draft                                                    Surrey
Intended status: Experimental                                   J. McKim
Expires: April 28, 2010                                             RSIS
                                                                 W. Eddy
                                                                 Verizon
                                                              W. Ivancic
                                                                    NASA
                                                              C. Jackson
                                                                    SSTL
                                                        October 25, 2009


              Saratoga: A Scalable File Transfer Protocol
                      draft-wood-tsvwg-saratoga-04

Status of this Memo

   This Internet-Draft is submitted to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.  This document may not be modified,
   and derivative works of it may not be created, except to format it
   for publication as an RFC and to translate it into languages other
   than English.

   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.

   This Internet-Draft will expire on April 28, 2010.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal



Wood, et al.             Expires April 28, 2010                 [Page 1]

Internet-Draft                  Saratoga                    October 2009


   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Abstract

   This document specifies the Saratoga transfer protocol.  Saratoga was
   originally developed to efficiently transfer remote-sensing imagery
   from a low-Earth-orbiting satellite constellation, but is useful for
   many other scenarios, including ad-hoc peer-to-peer communications,
   delay-tolerant networking, and grid computing.  Saratoga is a simple,
   lightweight, content dissemination protocol that builds on UDP, and
   optionally uses UDP-Lite.  Saratoga is intended for use when moving
   files or streaming data between peers which may have only sporadic or
   intermittent connectivity, and is capable of transferring very large
   amounts of data reliably under adverse conditions.  The Saratoga
   protocol is designed to cope with highly asymmetric link or path
   capacity between peers, and can support fully-unidirectional data
   transfer if required.  In scenarios with dedicated links, Saratoga
   focuses on high link utilization to make the most of limited
   connectivity times, while standard congestion control mechanisms can
   be implemented for operation over shared links.  Loss recovery is
   implemented via a simple negative-ack ARQ mechanism.  The protocol
   specified in this document is considered to be appropriate for
   experimental use on private IP networks.

























Wood, et al.             Expires April 28, 2010                 [Page 2]

Internet-Draft                  Saratoga                    October 2009


Table of Contents

   1.  Background and Introduction  . . . . . . . . . . . . . . . . .  4
   2.  Overview of Saratoga File Transfer . . . . . . . . . . . . . .  6
   3.  Optional Parts of Saratoga . . . . . . . . . . . . . . . . . . 11
   4.  Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 12
     4.1.  BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 14
     4.2.  REQUEST  . . . . . . . . . . . . . . . . . . . . . . . . . 17
     4.3.  METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 20
     4.4.  DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
     4.5.  HOLESTOFILL  . . . . . . . . . . . . . . . . . . . . . . . 27
   5.  The Directory Entry  . . . . . . . . . . . . . . . . . . . . . 33
   6.  Behavior of a Saratoga Peer  . . . . . . . . . . . . . . . . . 35
     6.1.  Saratoga Transactions  . . . . . . . . . . . . . . . . . . 35
     6.2.  Beacons  . . . . . . . . . . . . . . . . . . . . . . . . . 38
     6.3.  Upper-Layer Interface  . . . . . . . . . . . . . . . . . . 38
     6.4.  Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 39
   7.  Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . 39
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 40
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 40
   10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 41
   11. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 41
   12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41
     12.1. Normative References . . . . . . . . . . . . . . . . . . . 41
     12.2. Informative References . . . . . . . . . . . . . . . . . . 41
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 43

























Wood, et al.             Expires April 28, 2010                 [Page 3]

Internet-Draft                  Saratoga                    October 2009


1.  Background and Introduction

   Saratoga is a file transfer and content dissemination protocol
   capable of efficiently sending both small and very large files as
   well as streaming continuous content.  Saratoga was originally
   designed for the purpose of large file transfer from small low-Earth-
   orbit satellites.  It has been used in daily operations since 2004 to
   move mission imaging data files on the order of several hundred
   megabytes from the Disaster Monitoring Constellation (DMC) remote-
   sensing satellites to ground stations.

   The DMC satellites, built at the University of Surrey by Surrey
   Satellite Technology Ltd (SSTL), all use IP for payload
   communications and delivery of Earth imagery.  At the time of this
   writing in October 2009, seven DMC satellites have been launched into
   orbit; six are currently operational; and further DMC satellites are
   under construction.  The DMC satellites use Saratoga to provide
   imagery under the aegis of the International Charter on Space and
   Major Disasters.  A pass of connectivity between a satellite and
   ground station offers an 8-12 minute time window in which to transfer
   imagery files using a minimum of an 8.1 Mbps downlink and a 9.6 kbps
   uplink.  The newer DMC satellites have faster downlinks, with some
   capable of 80 Mbps.  Others are planned to provide upwards of 200
   Mbps, without significant increases in uplink rates.  This high
   degree of asymmetry, and need to fully utilize the downlink to move
   the volume of data required within the limited time available,
   motivates much of Saratoga's design.

   Further details on how these DMC satellites use IP to communicate
   with the ground and the terrestrial Internet are discussed in other
   documents [Hogie05][Wood07a][Wood07b].

   Store-and-forward delivery relies on reliable hop-by-hop transfers of
   files, removing the need for the final receiver to talk to the
   original sender across long delays and allowing for the possibility
   that an end-to-end path may never exist between sender and receiver
   at any given time.  Use of store-and-forward hop-by-hop delivery is
   typical of scenarios in space exploration for both near-Earth and
   deep-space missions, and useful for other scenarios, such as
   underwater networking, ad-hoc sensor networks, and some message-
   ferrying relay scenarios.  Saratoga is intended to be useful for
   relaying data in these scenarios and can optionally also be used to
   carry the Bundle Protocol "bundles" that is proposed for use in Delay
   and Disruption-Tolerant Networking (DTN) by the IRTF DTN Research
   Group [RFC5050].  How Saratoga can optionally function as a "bundle
   convergence layer" alongside a DTN bundle agent is specified in a
   companion document [I-D.wood-dtnrg-saratoga].




Wood, et al.             Expires April 28, 2010                 [Page 4]

Internet-Draft                  Saratoga                    October 2009


   High link utilization is important during periods of limited
   connectivity.  Given that Saratoga was originally developed for
   scheduled peer-to-peer communications over dedicated links in private
   networks where each application has the entire link for the duration
   of its transfer, early Saratoga implementations deliberately lack any
   form of congestion control and send at line rate.  Newer
   implementations may perform TCP-Friendly Rate Control (TFRC)
   [RFC3448] or other congestion control mechanisms such as LEDBAT
   [I-D.ietf-ledbat-congestion], if appropriate for the environment and
   where simultaneous sharing of capacity with other traffic and
   applications is required.

   Saratoga contains a Selective Negative Acknowledgement (SNACK)
   mechanism to provide reliable retransmission of data.  This was
   intended to correct losses of corrupted link-layer frames due to
   channel noise over a space link.  Packet losses in the DMC are due to
   corruption introducing non-recoverable errors in the frame.  The DMC
   design uses point-to-point links and scheduling of applications so
   that the link is dedicated to one application transfer at a time,
   meaning that packet loss can not be due to congestion as applications
   compete for link capacity.  In other wireless environments that may
   be shared by many nodes and applications, allocation of channel
   resources to nodes becomes a MAC-layer function.  Forward Error
   Coding (FEC) to get the most reliable transmission through a channel
   is best left near the physical layer so that it can be tailored for
   the channel.  Use of FEC complements Saratoga's transport-level
   negative-acknowledgement approach to provide a reliable ARQ mechanism
   [RFC3366].

   Saratoga is scalable in that it is capable of efficiently
   transferring small or large files, by choosing a width of file offset
   descriptor appropriate for the filesize, and advertising accepted
   offset descriptor sizes. 16-bit, 32-bit, 64-bit and 128-bit
   descriptors can be selected, for maximum file sizes of 64KiB-1,
   4GiB-1, 2^64-1 and 2^128-1 octets.  Earth imaging files currently
   transferred by Saratoga are mostly up to a few gigabytes in size.
   Some implementations do transfer more than 4 GiB in size, and so
   require offset descriptors larger than 32 bits.  We expect that a
   128-bit descriptor will satisfy all future needs, but we expect
   current implementations to only support up to 32-bit or 64-bit
   descriptors, depending on their application needs.  The 16-bit
   descriptor is useful for small messages, including messages from
   8-bit devices, and is always supported.  The 128-bit descriptor is
   useful for moving very large files stored on a 128-bit filesystem,
   such as on OpenSolaris ZFS.

   Saratoga can be used with either IPv4 or IPv6.  Compatibility between
   Saratoga and the wide variety of links that can already carry IP



Wood, et al.             Expires April 28, 2010                 [Page 5]

Internet-Draft                  Saratoga                    October 2009


   traffic is assured.

   Saratoga was originally implemented as outlined in [Jackson04], but
   the specification given here differs substantially, as we have added
   a number of features, while cleaning up the initial Saratoga
   specification.  The original Saratoga code uses a version number of
   0, while code that implements this version of the protocol advertises
   a version number of 1.  Further discussion of the history and
   development of Saratoga is given in [Wood07b].

   This document contains an overview of the transfer process and
   transactions using Saratoga in Section 2, followed by a formal
   definition of the packet types used by Saratoga in Section 4, and the
   details of the various protocol mechanisms in Section 6.

   Here, Saratoga transaction types are labelled with underscores around
   lowercase names (such as a "_get_" transaction), while Saratoga
   packet types are labelled in all capitals (such as a "REQUEST"
   packet) in order to distinguish between the two.

   The remainder of this specification uses 'file' as a shorthand for
   'binary object', which may be a DTN bundle, or other type of data.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119.  [RFC2119]


2.  Overview of Saratoga File Transfer

   Saratoga is a peer-to-peer protocol in the sense that multiple files
   may be transferred in both directions simultaneously between two
   communicating Saratoga peers, and there is not intended to be a
   strict client-to-server relationship.

   Saratoga nodes are simple file servers.  Saratoga supports several
   types of operations on files including "pull" downloads, "push"
   uploads, directory listing, and deletion requests.  Each operation is
   handled as a distinct "transaction" between the peers.

   Saratoga nodes MAY advertise their presence, capabilities, and
   desires by sending BEACON packets.  These BEACONs are sent to either
   a reserved, unforwardable, multicast address when using IPv4, or a
   link-local all-Saratoga-peers multicast address when using IPv6.  A
   BEACON might also be unicast to another known node as a sort of
   "keepalive".  Saratoga nodes may dynamically discover other Saratoga
   nodes either through listening for BEACONs, through pre-
   configuration, or via some other trigger from a user, lower-layer



Wood, et al.             Expires April 28, 2010                 [Page 6]

Internet-Draft                  Saratoga                    October 2009


   protocol, or another process.  The BEACON is simply useful in low-
   delay ad-hoc networking or as explicit confirmation that another node
   is present; it is not required in order to begin a Saratoga
   transaction.  BEACONs have been used by the DMC satellites to
   indicate to ground stations that a link has become functional, a
   solid-state data recorder is online, and the software is ready to
   transfer any requested files.

   A Saratoga transaction begins with either a _get_, _put_, _getdir_,
   or _delete_ transaction REQUEST packet corresponding to a desired
   download, upload, directory listing, or deletion operation.  The most
   common envisioned transaction is the _get_, which begins with a
   single Saratoga REQUEST packet sent from the peer wishing to receive
   the file, to the peer who currently has the file.  If the transaction
   is rejected, then a brief METADATA packet that conveys rejection is
   generated.  If the file-serving peer accepts the transaction, it
   generates and sends a more useful descriptive METADATA packet,
   followed by some number of DATA packets constituting the requested
   file.

   These DATA packets are finished by (and can intermittently include) a
   DATA packet with a flag bit set that demands the file-receiver send a
   reception report in the form of a HOLESTOFILL packet.  The
   HOLESTOFILL packet is a Selective Negative Acknowledgement listing
   spans of octets within the file that have not yet been received as
   well as whether or not the METADATA packet was received.  From this
   HOLESTOFILL packet, the file-sender begins a cycle of selective
   retransmissions of DATA packets, until it sees a HOLESTOFILL packet
   that acknowledges total reception of all file data.

   In the example scenario in Figure 1, a _get_ request is granted.  The
   reliable file delivery experiences loss of a single DATA packet due
   to channel-induced errors.


















Wood, et al.             Expires April 28, 2010                 [Page 7]

Internet-Draft                  Saratoga                    October 2009


        File-Receiver               File-Sender

           REQUEST --------------------->
      (transfer accepted) <--------- METADATA
           HOLESTOFILL -----------------> (voluntarily sent at start)
              <------------------------- DATA #1
                       (lost) <------ DATA #2
              <------------------------- DATA #3 (bit set
                                       requesting HOLESTOFILL)
           HOLESTOFILL ----------------->
      (indicating that range in DATA #2 was lost)
              <------------------------- DATA #2 (bit set
                                       requesting HOLESTOFILL)
           HOLESTOFILL ----------------->
      (complete file and METADATA received)

               Figure 1: Example _get_ transaction sequence

   A _getdir_ request proceeds similarly, though the DATA packets
   contain the contents of a directory listing, described later, rather
   than a given file's bytes. _getdir_ is the only request to apply to
   directories.

   The HOLESTOFILL and DATA packets are allowed to be sent at any time
   within the scope of a transaction in order for the file-sending node
   to optimize buffer management and transmission order.  For example,
   if the file-receiver already has the first half of a file from a
   previous disrupted transfer, it may send a HOLESTOFILL at the
   beginning of the transaction indicating that it has the first half of
   the file, and so only needs the last half of the file.  Thus,
   efficient recovery from interrupted sessions between peers becomes
   possible, similar to ranged FTP and HTTP requests.

   In deep-space scenarios, the large propagation delays and round-trip
   times involved prohibit ping-pong packet exchanges for starting
   transactions.  The Saratoga _put_ transaction is useful in such
   cases.  A _put_ is initiated by the file-sender sending a METADATA
   packet followed by immediate DATA packets.  This is highly desirable
   in long-propagation deep-space (and similar) scenarios, without first
   waiting for a HOLESTOFILL.  This can be considered an "optimistic"
   mode of protocol operation, as it assumes the transaction request
   will be granted.  If the sender of a PUT request sees a METADATA
   packet indicating that the request was declined, it MUST stop sending
   any DATA packets within that transaction immediately.  Since this
   type of _put_ is open-loop for some period of time, it should not be
   used in scenarios where congestion is a valid concern; in these
   cases, the file-sender should wait on its METADATA to be acknowledged
   by a HOLESTOFILL before sending DATA packets within the transaction.



Wood, et al.             Expires April 28, 2010                 [Page 8]

Internet-Draft                  Saratoga                    October 2009


   Figure 2 illustrates the sequence of packets in an example _put_
   transaction where the second DATA packet is lost.  Other than the way
   that it is initiated, a _put_ transaction is identical to a _get_
   transaction.

                      File-Sender           File-Receiver

                       METADATA ---------------->
                 (transfer accepted) <---------- HOLESTOFILL
                       DATA  #1 ---------------->
                       DATA  #2 ---> (lost)
                  DATA  #3 (bit set ------------>
                requesting HOLESTOFILL)
                   (DATA #2 lost) <------------- HOLESTOFILL
                  DATA  #2 (bit set  ----------->
                requesting HOLESTOFILL)
                 (transfer complete) <---------- HOLESTOFILL

                Figure 2: Example PUT transaction sequence

   The _delete_ transactions are simple single packet requests that
   trigger a HOLESTOFILL packet with a status code that indicates
   whether the file was deleted or not.  If the file is not able to be
   deleted for some reason, this reason can be conveyed in the Status
   field of the HOLESTOFILL packet.

   A _get_ REQUEST packet that does not specify a filename (i.e. the
   request contains a zero-length File Path field) is specially defined
   to be a request for any chosen file that the peer wishes to send it.
   This allows a Saratoga peer to blindly request any files that the
   other Saratoga peer has ready for it, without prior knowledge of the
   directory listing, and without requiring the ability to examine files
   or decode remote file names/paths for meaningful information such as
   final destination.

   If a file is larger than Saratoga can be expected to transfer during
   a time-limited contact, there are at least two feasible options:

   (1) The application can use proactive fragmentation to create
   multiple smaller-sized files.  Saratoga can transfer some number of
   these smaller files fully during a contact.

   (2) To avoid file fragmentation, a Saratoga file-receiver can retain
   a partially-transferred file and request transfer of the unreceived
   bytes during a later contact.  This uses a HOLESTOFILL packet to make
   clear how much of the file has been successfully received and where
   transfer should be resumed from.  On resumption, the new METADATA
   (including file length, timestamps, and possibly MD5 sum) MUST match



Wood, et al.             Expires April 28, 2010                 [Page 9]

Internet-Draft                  Saratoga                    October 2009


   that of the previous METADATA in order to re-establish the transfer.
   Otherwise, the file-receiver MUST assume that the file has changed
   and purge the DATA received during the first contact.

   If a file contains separate parts that require reliable transmission
   without errors or that can tolerate errors in delivered content,
   proactive fragmentation can be used to split the file into separate
   reliable and unreliable files that can be transferred separately,
   using UDP or UDP-Lite.

   If parts of a file require reliability but the rest can be sent by
   unreliable transfer, the file-sender can use its knowledge of the
   internal file structure and vary DATA packet size so that the
   reliable parts always start after the offset field and are covered by
   the UDP-Lite checksum.

   A file that permits unreliable delivery may be transferred onwards
   using UDP, although the METADATA flag indicating that unreliable
   transmission is permitted is retained for later hops, which may
   revert to using UDP-Lite.  If the current sender does not understand
   the internal file format to be able to decide what parts must be
   protected, the current sender or receiver does not support UDP-Lite,
   or the current protocol stack only implements error-free frame
   delivery below the UDP layer, then the file may be delivered using
   UDP.

   Like the BEACON packets, a _put_ or a response to a _get_ may be sent
   to the dedicated IPv4 Saratoga multicast address (allocated to
   224.0.0.108) or the dedicated IPv6 link-local multicast address
   (allocated to FF02:0:0:0:0:0:0:6C) for multiple file-receivers on the
   link to hear.  This is at the discretion of the file-sender, if it
   believes that there is interest from multiple receivers.  In-progress
   DATA transfers may also be moved seamlessly from unicast to multicast
   if the file-sender learns during a transfer, from receipt of further
   unicast _get_ REQUEST packets, that multiple nodes are interested in
   the file.  The associated METADATA packet is multicast when this
   transition takes place, and is then repeated periodically while the
   DATA stream is being sent, to inform newly-arrived listeners about
   the file being multicast.  Acknowledgements MUST NOT be demanded by
   multicast DATA packets, to prevent ack implosion at the file-sender,
   and instead holestofill information is aggregated and sent
   voluntarily by all file-receivers.  File-receivers respond to
   multicast DATA with multicast HOLESTOFILL packets.  File-receivers
   should introduce a short random delay before sending a HOLESTOFILL
   packet, to prevent ack implosion after a channel-induced loss, and
   must listen for HOLESTOFILL packets from others, to avoid duplicating
   fill requests.  The file-sender SHOULD repeat any initial unicast
   portion of the transfer as multicast last of all, and may repeat and



Wood, et al.             Expires April 28, 2010                [Page 10]

Internet-Draft                  Saratoga                    October 2009


   cycle through multicast of the file several times while file-
   receivers express interest via HOLESTOFILL or _get_ packets.  Once in
   multicast and with METADATA being repeated periodically, new file-
   receivers do not need to send individual REQUEST packets.  If a
   transfer has been started using UDP-Lite and new receivers indicate
   UDP-only capability, multicast transfers MUST switch to using UDP to
   accommodate them.


3.  Optional Parts of Saratoga

   Implementing support for some parts of Saratoga is optional.  These
   parts are:

   - sending and parsing BEACONs

   - support for working with DTN bundles and a bundle agent as an
   application driving Saratoga.  Use of a filesystem is expected.

   - transfers permitting some errors in content delivered, using UDP-
   Lite.  These can be useful for decreasing delivery time over
   unreliable channels, especially for unidirectional links - but
   requires that lower-layer frames permit delivery of unreliable data.

   - streaming data, including real-time streaming of content of unknown
   length.  This streaming can be unreliable (without resend requests)
   or reliable (with resend requests).  Session protocols such as http
   expect reliable streaming, and can be used in delay-tolerant networks
   [I-D.wood-dtnrg-http-dtn-delivery].  Although Saratoga data delivery
   is inherently one-way, where a stream of DATA packets elicits a
   stream of HOLESTOFILL packets, bidirectional duplex communication can
   be established by using two Saratoga transfers flowing in opposite
   directions.

   - sending and responding to packet timestamps in DATA and HOLESTOFILL
   packets.  These timestamps are useful for streaming and for giving a
   file-sender an indication of path latency for rate control.  There is
   no need for a file-receiver to understand the format used for these
   timestamps for it to be able to receive and reflect them.

   - performing congestion control at the sender, based on feedback from
   acknowledgement HOLESTOFILL packets, or simple open-loop rate control

   - multicast DATA transfers, if judged useful for the environment in
   which Saratoga is deployed.






Wood, et al.             Expires April 28, 2010                [Page 11]

Internet-Draft                  Saratoga                    October 2009


4.  Packet Types

   Saratoga is defined for use with UDP over either IPv4 or IPv6
   [RFC0768].  UDP checksums, which are mandatory with IPv6, MUST be
   used with IPv4.  Within either version of IP datagram, a Saratoga
   packet appears as a typical UDP header followed by an octet
   indicating how the remainder of the packet is to be interpreted:

                       1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |       UDP source port         |     UDP destination port      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          UDP length           |         UDP checksum          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Ver|Packet Type| other Saratoga fields ... //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+//

   Saratoga data transfers can also be carried out using UDP-Lite
   [RFC3828].  If Saratoga can be carried over UDP-Lite, the
   implementation MUST also support UDP.  All packet types except DATA
   MUST be sent using UDP with checksums turned on.  For reliable
   transfers, DATA packets are sent using UDP with checksums turned on.
   For files where unreliable transfer has been indicated as desired and
   possible, the sender MAY send DATA packets unreliably over UDP-Lite,
   where UDP-Lite protects only the Saratoga headers and parts of the
   file that must be transmitted reliably.

   The two-bit Saratoga version field ("Ver") identifies the version of
   the Saratoga protocol that the packet conforms to.  The value 01
   should be used in this field for implementations conforming to the
   specification in this document, which specifies version 1 of
   Saratoga.  The value 00 was used in earlier implementations, prior to
   the formal specification and public submission of the protocol
   design, and is incompatible with version 01 in several respects.

   The six-bit Saratoga "Packet Type" field indicates how the remainder
   of the packet is intended to be decoded and processed:

      +---+-------------+-------------------------------------------+
      | # | Type        | Use                                       |
      +---+-------------+-------------------------------------------+
      | 0 | BEACON      | Beacon packet indicating peer status      |
      | 1 | REQUEST     | Commands peer to start a transfer         |
      | 2 | METADATA    | Carries file transfer metadata            |
      | 3 | DATA        | Carries octets of file data               |
      | 4 | HOLESTOFILL | Signals list of unreceived data to sender |
      +---+-------------+-------------------------------------------+



Wood, et al.             Expires April 28, 2010                [Page 12]

Internet-Draft                  Saratoga                    October 2009


   Several of these packet types include a Flags field, for which only
   some of the bits have defined meanings and usages in this document.
   Other, undefined, bits may be reserved for future use.  Following the
   principle of being conservative in what you send and liberal in what
   you accept, a packet sender MUST set any undefined bits to zero, and
   a packet recipient MUST NOT rely on these undefined bits being zero
   on reception.

   The specific formats for the different types of packets are given in
   this section.  Some packet types contain file offset descriptor
   fields, which contain unsigned integers.  The lengths of the offset
   descriptors are fixed within a transfer, but vary between file
   transfers.  The size is set for each particular transfer, depending
   on the choice of offset descriptor width made in the METADATA packet,
   which in turn depends on the size of file being transferred.

   In this document, all of the packet structure figures illustrating a
   packet format assume 32-bit lengths for these offset descriptor
   fields, and indicate the transfer-dependent length of the fields by
   using a "(descriptor)" designation within the [field] in all packet
   diagrams.  That is:

   The example 32-bit descriptors shown in all diagrams here

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                          (descriptor)                         ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   are suitable for files of up to 4GiB - 1 octets in length, and may be
   replaced in a file transfer by descriptors using a different length,
   depending on the size of file to be transferred:

   128-bit descriptor for very long files (optional)

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                          (descriptor)                         /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                     (descriptor, continued)                   /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                     (descriptor, continued)                   /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                     (descriptor, continued)                   ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+








Wood, et al.             Expires April 28, 2010                [Page 13]

Internet-Draft                  Saratoga                    October 2009


   64-bit descriptor for longer files (optional)

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                          (descriptor)                         /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                     (descriptor, continued)                   ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   16-bit descriptor for short files (MUST be supported)

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [         (descriptor)          ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   For offset descriptors and types of content being transferred, the
   related flag bits in BEACON and REQUEST indicate capabilities, while
   in METADATA and DATA those flag bits are used slightly differently,
   to indicate the content being transferred.

   Saratoga packets are intended to fit within link MTUs to avoid the
   inefficiencies and overheads of lower-layer fragmentation.  A
   Saratoga implementation itself does not perform any form of MTU
   discovery, but is assumed to be configured with knowledge of usable
   maximum IP MTUs for the link interfaces it uses.

4.1.  BEACON

   BEACON packets may be multicast periodically by nodes willing to act
   as Saratoga peers.  Some implementations have done so every 100
   milliseconds, but this rate is arbitrary, and should be chosen to be
   appropriate for the environment and implementation.

   The main purpose for sending BEACONs is to announce the presence of
   the node to potential peers (e.g. satellites, ground stations) to
   provide automatic service discovery, and also to confirm the activity
   or presence of the peer.

   The Endpoint Identifier (EID) in the BEACON serves to uniquely
   identify the Saratoga peer.  Whenever the Saratoga peer begins using
   a new IP address, it SHOULD issue a BEACON on it and repeat the
   BEACON periodically, to enable listeners to associate the IP address
   with the EID and the peer.









Wood, et al.             Expires April 28, 2010                [Page 14]

Internet-Draft                  Saratoga                    October 2009


   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 2
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |0 1|    Type   |                      Flags                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      Endpoint identifier...                               //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+//

   where

   +------------+------------------------------------------------------+
   | Field      | Description                                          |
   +------------+------------------------------------------------------+
   | Type       | 0                                                    |
   | Flags      | convey whether or not the peer is ready to           |
   |            | send/receive and what the maximum supported file     |
   |            | size range and descriptor is.                        |
   | Endpoint   | This can be used to uniquely identify the sending    |
   | identifier | Saratoga peer, or the administrative node that the   |
   |            | BEACON-sender is associated with.  If Saratoga is    |
   |            | being used with a bundle agent, a bundle endpoint ID |
   |            | (EID) can be used here.                              |
   +------------+------------------------------------------------------+

   The Flags field is used to provide some additional information about
   the peer.  The first octet of the Flags field is currently in use.
   The later two octets are for future use, and MUST be set to zero.

   The two highest-order bits (bits 8 and 9 above) indicate the maximum
   supported file size parameters that the peer's Saratoga
   implementation permits.  Other Saratoga packet types contain
   variable-length fields that convey file sizes or offsets into a file
   -- the file offset descriptors.  These descriptors may be 16-bit, 32-
   bit, 64-bit, or 128-bit in length, depending on the size of the file
   being transferred and/or the integer types supported by the sending
   peer.  The indicated bounds for the possible values of these bits are
   summarized below:

      +-------+-------+-------------------------+-------------------+
      | Bit 8 | Bit 9 | Supported Field Sizes   | Maximum File Size |
      +-------+-------+-------------------------+-------------------+
      | 0     | 0     | 16 bits                 | 2^16 - 1 octets.  |
      | 0     | 1     | 16 or 32 bits           | 2^32 - 1 octets.  |
      | 1     | 0     | 16, 32, or 64 bits      | 2^64 - 1 octets.  |
      | 1     | 1     | 16, 32, 64, or 128 bits | 2^128 - 1 octets. |
      +-------+-------+-------------------------+-------------------+



Wood, et al.             Expires April 28, 2010                [Page 15]

Internet-Draft                  Saratoga                    October 2009


   If a Saratoga peer advertises it is capable of receiving a certain
   size of file, then it MUST also be capable of receiving files sent
   using smaller descriptor values.  This avoids overhead on small
   files, while increasing interoperability between peers.

   It is likely when sending unbounded streams that a larger offset
   descriptor field size will be preferred to minimise problems with
   offset sequences wrapping.  Protecting against sequence wrapping is
   discussed in the HOLESTOFILL section.

   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 10  | 0     | not able to pass bundles to a local bundle agent;   |
   |     |       | handles files.                                      |
   | 10  | 1     | can pass marked bundles to a local bundle agent.    |
   +-----+-------+-----------------------------------------------------+

   Bit 10 is reserved for DTN bundle agent use, indicating whether the
   sender is capable of handling bundles via a local bundle agent.  This
   is described in [I-D.wood-dtnrg-saratoga].

   Any type of host identifier can be used in the endpoint identifier
   field, as long as it is a reasonably unique string within the range
   of operational deployment.  This field encompasses the remainder of
   the packet, and might contain non-UTF-8 and/or null characters.

          +-----+-------+--------------------------------------+
          | Bit | Value | Meaning                              |
          +-----+-------+--------------------------------------+
          | 11  | 0     | not capable of supporting streaming. |
          | 11  | 1     | capable of supporting streaming.     |
          +-----+-------+--------------------------------------+

   Bit 11 is used to indicate whether the sender is capable of sending
   and receiving continuous streams.

   +--------+--------+------------------------------------------------+
   | Bit 12 | Bit 13 | Capability and willingness to send files       |
   +--------+--------+------------------------------------------------+
   | 0      | 0      | cannot send files at all.                      |
   | 0      | 1      | invalid.                                       |
   | 1      | 0      | capable of sending, but not willing right now. |
   | 1      | 1      | capable of and willing to send files.          |
   +--------+--------+------------------------------------------------+






Wood, et al.             Expires April 28, 2010                [Page 16]

Internet-Draft                  Saratoga                    October 2009


   +--------+--------+-------------------------------------------------+
   | Bit 14 | Bit 15 | Capability and willingness to receive files     |
   +--------+--------+-------------------------------------------------+
   | 0      | 0      | cannot receive files at all.                    |
   | 0      | 1      | invalid.                                        |
   | 1      | 0      | capable of receiving, but will reject METADATA. |
   | 1      | 1      | capable of and willing to receive files.        |
   +--------+--------+-------------------------------------------------+

   Also in the Flags field, bits 12 and 14 act as capability bits, while
   bits 13 and 15 augment those flags with bits indicating current
   willingness to use the capability.

   Bits 12 and 13 deal with sending, while bits 14 and 15 deal with
   receiving.  If bit 12 is set, then the peer has the capability to
   send files.  If bit 14 is set, then the peer has the capability to
   receive files.  Bits 13 and 15 indicate willingness to send and
   receive files, respectively.

   A peer that is able to act as a file-sender MUST set the capability
   bit 12 in all BEACONs that it sends, regardless of whether it is
   willing to send any particular files to a particular peer at a
   particular time.  Bit 13 indicates the current presence of data to
   send and a willingness to send it in general, in order to augment the
   capability advertised by bit 12.

   If bit 14 is set, then the peer is capable of acting as a receiver,
   although it still might not currently be ready or willing to receive
   files (for instance, it may be low on free storage).  This bit MUST
   be set in any BEACON packets sent by nodes capable of acting as file-
   receivers.  Bit 15 augments this by expresses a current general
   willingness to receive and accept files.

   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 16  | 0     | supports DATA transfers over UDP only.              |
   | 16  | 1     | supports DATA transfers over both UDP and UDP-Lite. |
   +-----+-------+-----------------------------------------------------+

   Bit 16 is used to indicate whether the sender is capable of sending
   and receiving unreliable transfers via UDP-Lite.

4.2.  REQUEST

   A REQUEST packet is a command to perform either a _get_, _getdir_, or
   _delete_ transaction.




Wood, et al.             Expires April 28, 2010                [Page 17]

Internet-Draft                  Saratoga                    October 2009


   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |0 1|   Type    |                     Flags                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                               Id                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                 variable-length File Path ...                 /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /               |    null byte    |                             /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /     variable-length Authentication Field (optional)   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


   where

   +--------+----------------------------------------------------------+
   | Field  | Description                                              |
   +--------+----------------------------------------------------------+
   | Type   | 1                                                        |
   | Flags  | provide additional information about the requested       |
   |        | file/operation; see table below for definition.          |
   | Id     | uniquely identifies the transaction between two peers.   |
   | File   | the path of the requested file/directory following the   |
   | Path   | rules described below.                                   |
   +--------+----------------------------------------------------------+

   The Id that is used during transactions serves to uniquely associate
   a given packet with a particular transaction.  This enables multiple
   simultaneous data transfer transactions between two peers, with each
   peer deciding how to multiplex and prioritise the parallel flows it
   sends.  The Id for a transaction is selected by the initiator so as
   to not conflict with any other in-progress or recent transactions
   with the same host.  This Id should be unique and generated using
   properties of the file, which will remain constant across a host
   reboot.  The 3-tuple of both host identifiers and a carefully-
   generated transaction Id field can be used to uniquely index a
   particular transaction's state.

   In the Flags field, the bits labelled 8 and 9 in the figure above
   indicate the maximum supported file length fields that the peer can
   handle, and are interpreted exactly as the bits 8 and 9 in the BEACON
   packet described above.  The remaining defined bits are:



Wood, et al.             Expires April 28, 2010                [Page 18]

Internet-Draft                  Saratoga                    October 2009


   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 10  | 0     | The requester cannot handle bundles locally.        |
   | 10  | 1     | The requester can handle bundles.                   |
   | 11  | 0     | The requester cannot receive streams.               |
   | 11  | 1     | The requester is also able to receive streams.      |
   | 14  | 0     | a _get_ or _getdir_ transaction is requested        |
   | 14  | 1     | a _delete_ transaction is requested                 |
   | 15  | 0     | the File Path field holds a file for a _get_ or     |
   |     |       | _delete_                                            |
   | 15  | 1     | the File Path field specifies a directory name for  |
   |     |       | a _getdir_ or _delete_                              |
   | 16  | 0     | The requester is able to receive DATA over UDP      |
   |     |       | only.                                               |
   | 16  | 1     | The requester is also able to receive DATA over     |
   |     |       | UDP-Lite.                                           |
   +-----+-------+-----------------------------------------------------+

   The File Path portion of a _get_ packet is a null-terminated UTF-8
   encoded string [RFC3629] that represents the path and base file name
   on the file-sender of the file (or directory) that the file-receiver
   wishes to perform the _get_, _getdir_, or _delete_ operation on.
   Implementations SHOULD only send as many octets of File Path as are
   needed for carrying this string, although some implementations MAY
   choose to send a fixed-size File Path field in all REQUEST packets
   that is filled with null octets after the last UTF-8 encoded octet of
   the path.  A maximum of 1024 octets for this field, and for the File
   Path fields in other Saratoga packet types, is used to limit the
   total packet size to within a single IPv6 minimum MTU (minus some
   padding for network layer headers), and thus avoid the need for
   fragmentation.  The 1024-octet maximum applies after UTF-8 encoding
   and null termination.

   As in the standard Internet File Transfer Protocol (FTP) [RFC0959],
   for path separators, Saratoga allows the local naming convention on
   the peers to be used.  There are security implications to processing
   these strings without some intelligent filtering and checking on the
   filesystem items they refer to, as discussed in the Security
   Considerations section later within this document.

   If the File Path field is empty, i.e. is a null-terminated zero-
   length string one octet long, then this indicates that the file-
   receiver is ready to receive any file that the file-sender would like
   to send it, rather than requesting a particular file.  This allows
   the file-sender to determine the order and selection of files that it
   would like to forward to the receiver in more of a "push" manner.  Of
   course, file retrieval could also follow a "pull" manner, with the



Wood, et al.             Expires April 28, 2010                [Page 19]

Internet-Draft                  Saratoga                    October 2009


   file-receiving host requesting specific files from the file-sender.
   This may be desirable at times if the file-receiver is low on storage
   space, or other resources.  The file-receiver could also use the
   Saratoga _getdir_ transaction results in order to select small files,
   or make other optimizations, such as using its local knowledge of
   contact times to pick files of a size likely to be able to be
   delivered completely.  File transfer through pushing sender-selected
   files implements delivery prioritization decisions made solely at the
   Saratoga file-sending node.  File transfer through pulling specific
   receiver-selected files implements prioritization involving more
   participation from the Saratoga file-receiver.  This is how Saratoga
   implements Quality of Service (QoS).

   The null-terminated File Path string MAY be followed by an optional
   Authentication Field that can be used to validate the REQUEST packet.
   Any value in the Authentication Field is the result of a computation
   of packet contents that SHOULD include, at a minimum, source and
   destination IP addresses and port numbers and packet length in a
   'pseudo-header', as well as the content of all Saratoga fields from
   Version to File Path, excluding the predictable null-termination
   octet.  This Authentication Field can be used to allow the REQUEST
   receiver to discriminate between other peers, and permit and deny
   various REQUEST actions as appropriate.  The format of this field is
   unspecified for local use.

   REQUEST packets may be sent multicast, to learn about all listening
   nodes.  A multicast _get_ request for a file that elicits multiple
   METADATA responses should be followed by unicast HOLESTOFILL packets
   with status errors cancelling all but one of the proposed transfers.
   Timestamps in the Directory Entry can be used to select the most
   recent version of an offered file, and the host to fetch it from.

   If the receiver already has the file at the expected file path and is
   requesting an update to that file, REQUEST can be sent after a
   METADATA advertising that file, to allow the sender to determine
   whether a replacement for the file should be sent.

   Delete requests are ignored for files currently being transferred.

4.3.  METADATA

   METADATA packets are sent as part of a data transfer transaction
   (_get_, _getfile_, and _put_).  A METADATA packet says how large the
   file is and what its name is, as well as what size of file offset
   descriptor is chosen for the session.  METADATA packets are normally
   sent at the start of a data transfer, but may be repeated if
   requested.




Wood, et al.             Expires April 28, 2010                [Page 20]

Internet-Draft                  Saratoga                    October 2009


   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |0 1|    Type   |                 Flags                 |Sumtype|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                               Id                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               /
   /                                                               /
   /     example error-detection checksum (128-bit MD5 shown)      /
   /                                                               /
   /                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               /
   /            single Directory Entry describing file             /
   /                      (variable length)                        /
   /                                                              //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//

   where

   +-----------+-------------------------------------------------------+
   | Field     | Description                                           |
   +-----------+-------------------------------------------------------+
   | Type      | 2                                                     |
   | Flags     | indicate additional boolean metadata about a file     |
   | Sumtype   | indicates whether a checksum is present after the Id, |
   |           | and what type it is.                                  |
   | Id        | identifies the transaction that this packet describes |
   | Checksum  | an example included checksum covering file contents   |
   | Directory | describes file system information about the file,     |
   | Entry     | including length, timestamps, etc.; the format is     |
   |           | specified in Section 5                                |
   +-----------+-------------------------------------------------------+

   The first octet of the Flags field is currently specified for use.
   The later two octets are reserved for future use, and MUST be set to
   zero.

   In the Flags field, the bits labelled 8 and 9 in the figure above
   indicate the exact size of the offset descriptor fields used in this
   particular packet and are interpreted exactly as the bits 8 and 9 in
   the BEACON packet described above.  The value of these bits
   determines the size of the File Length field in the current packet,
   as well as indicating the size of the offset fields used in DATA and
   HOLESTOFILL packets within the session that will follow this packet.



Wood, et al.             Expires April 28, 2010                [Page 21]

Internet-Draft                  Saratoga                    October 2009


   +--------+--------+-------------------------------------------------+
   | Bit 10 | Bit 11 | Type of transfer                                |
   +--------+--------+-------------------------------------------------+
   | 0      | 0      | a file is being sent.                           |
   | 0      | 1      | the file being sent should be interpreted as a  |
   |        |        | directory record.                               |
   | 1      | 0      | a bundle is being sent.                         |
   | 1      | 1      | an indefinite-length stream is being sent.      |
   +--------+--------+-------------------------------------------------+

   Also inside the Flags field, bits 10 and 11 indicate what is being
   transferred - a file, special file that contains directory records,
   bundle, or stream.  The value 01 indicates that the METADATA and DATA
   packets are being generated in response to a _getdir_ REQUEST, and
   that the assembled DATA contents should be interpreted as a sequence
   of Directory Records, as defined in Section 5.

   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 12  | 0     | This transfer is in progress.                       |
   | 12  | 1     | This transfer is no longer in progress, and has     |
   |     |       | been terminated.                                    |
   +-----+-------+-----------------------------------------------------+

   Bit 12 indicates whether the transfer is in progress, or has been
   terminated by the sender.  It is normally set to 1 only when METADATA
   is resent to indicate that a stream transfer has been ended.

   If a stream is being transferred, its length is unknown -- otherwise
   it would be a file.  The length property of a Directory Entry for a
   stream is expected to be zero.

   +--------+----------------------------------------------------------+
   | Bit 13 | Use                                                      |
   +--------+----------------------------------------------------------+
   | 0      | This file's content MUST be delivered reliably without   |
   |        | errors using UDP.                                        |
   | 1      | This file's content MAY be delivered unreliably, without |
   |        | errors, or partly unreliably, where errors are           |
   |        | tolerated, using UDP-Lite.                               |
   +--------+----------------------------------------------------------+

   Bit 13 indicates whether the file must be sent reliably or can be
   sent at least partly unreliably, using UDP-Lite.  This flag can only
   be set if the originator of the file knows that at least some of the
   file content is suitable for sending unreliably and is robust to
   errors.  This flag reflects a property of the file itself.  This flag



Wood, et al.             Expires April 28, 2010                [Page 22]

Internet-Draft                  Saratoga                    October 2009


   may still be set if the immediate file-receiver is only capable of
   UDP delivery, on the assumption that this preference will be
   preserved for later transfers where UDP-Lite transfers may be taken
   advantage of by senders with knowledge of the internal file
   structure.  The file-sender may know that the receiver is capable of
   handling UDP-Lite, either from a _get_ REQUEST, from exchange of
   BEACONs, or a-priori.

   The high four bits of the Flags field, bits 28-31, are used to
   indicate if an error-detection checksum has been included in the
   METADATA for the file to be transferred.  Here, bits 0000 indicate
   that no checksum is present, with the implicit assumption that the
   application will do its own end-to-end check.  Other values indicate
   the type of checksum to use.  The choice of checksum depends on the
   available computing power and the length of the file to be
   checksummed.  Longer files require stronger checksums to ensure
   error-free delivery.  The checksum of the file to be transferred is
   carried as shown, with a fixed-length field before the varying-length
   File Length and File Name information fields.

   Assigned values for the checksum field are:

   +-----------+-------------------------------------------------------+
   | Value     | Use                                                   |
   | (0-15)    |                                                       |
   +-----------+-------------------------------------------------------+
   | 0         | No checksum is provided.                              |
   | 1         | 32-bit CRC32 checksum, suitable for small files.      |
   | 2         | 128-bit MD5 checksum, suitable for larger files       |
   | 3         | 160-bit SHA-1 checksum, suitable for larger files but |
   |           | slower to process than MD5.                           |
   +-----------+-------------------------------------------------------+

   It is expected that higher values will be allocated to new and
   stronger checksums able to better protect larger files.  A checksum
   SHOULD be included for files being transferred.  The checksum SHOULD
   be as strong as possible.  Streaming of an indefinite-length stream
   MUST set the checksum field to zero.

   It is expected that a minimum of the MD5 checksum will be used,
   unless the Saratoga implementation is used exclusively for small
   transfers at the low end of the 16-bit file descriptor range, such as
   on low-performing hardware, where the weaker CRC-32c checksum can
   suffice.

   The CRC32 checksum is computed as described for the CRC-32c algorithm
   given in [RFC3309].




Wood, et al.             Expires April 28, 2010                [Page 23]

Internet-Draft                  Saratoga                    October 2009


   The MD5 Sum field is generated via the MD5 algorithm [RFC1321],
   computed over the entire contents of the file being transferred.  The
   file-receiver can compute the MD5 result over the reassembled
   Saratoga DATA packet contents, and compare this to the METADATA's MD5
   Sum field in order to gain confidence that there were no undetected
   protocol errors or UDP checksum weaknesses encountered during the
   transfer.  Although MD5 is known to be less than optimal for security
   uses, it remains excellent for non-security use in error detection
   (as is done here in Saratoga), and has better performance
   implications than cryptographically-stronger alternatives given the
   limited available processing of many DTN use cases.

   Checksums may be privately keyed for local use, to allow transmission
   of authenticated or encrypted files delivered in DATA packets.  This
   has limitations, discussed further in the Security Considerations
   section at end.

   Use of the checksum to ensure that a file has been correctly relayed
   to the receiving node is important.  A provided checksum MUST be
   checked against the received data file.  If checksum verification
   fails, either due to corruption or due to the receiving node not
   having the right key for a keyed checksum), the file MUST be
   discarded.  If the file is to be relayed onwards later to another
   Saratoga peer, the metadata, including the checksum, MUST be retained
   with the file and SHOULD be retransmitted onwards unchanged with the
   file for end-to-end coverage.  If it is necessary to recompute the
   checksum or encrypted data for the new peer, either because a
   different key is in use or the existing checksum algorithm is not
   supported, the new checksum MUST be computed before the old checksum
   is verified, to ensure overlapping checksum coverage and detect
   errors introduced in file storage.

   If the METADATA is in response to a _get_ REQUEST including a file
   record, and the record information for the held file matches what the
   requester already has, as has been indicated by a previously-received
   METADATA advertisement from the requester, then only the METADATA is
   sent repeating this information and verifying that the file is up to
   date.  If the record information does not match and a newer file can
   be supplied, the METADATA begins a transfer with following DATA
   packets to update the file.

4.4.  DATA

   A series of DATA packets form the main part of a data transfer
   transaction (_get_, _put_, or _getdir_).  The payloads constitute the
   actual file data being transferred.





Wood, et al.             Expires April 28, 2010                [Page 24]

Internet-Draft                  Saratoga                    October 2009


   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |0 1|    Type   |                      Flags                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                               Id                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                Timestamp (optional, descriptor-size)          ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                      Offset (descriptor)                      ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   where

   +---------------+---------------------------------------------------+
   | Field         | Description                                       |
   +---------------+---------------------------------------------------+
   | Type          | 3                                                 |
   | Flags 8 and 9 | bit 8 and 9 specify the size of offset            |
   |               | descriptor, as elsewhere.                         |
   | Flag 10       | bit 10, with bit 11, indicates whether a file,    |
   |               | bundle, stream or directory entry is being        |
   |               | carried.  This bit will normally be zero for      |
   |               | files.                                            |
   | Flag 11       | bit 11 is used with bit 10.  Normally this bit    |
   |               | will be zero for files.                           |
   | Flag 12       | bit 12 indicates that an optional timestamp is    |
   |               | included in the DATA header before the offset     |
   |               | descriptor.                                       |
   | Flag 15       | bit 15 requests an immediate HOLESTOFILL ack to   |
   |               | be generated in response to receiving this        |
   |               | packet.                                           |
   | Id            | identifies the transaction that this packet       |
   |               | belongs to                                        |
   | Offset        | the offset in octets to the location where the    |
   |               | first byte of this packet's payload is to be      |
   |               | written                                           |
   +---------------+---------------------------------------------------+

   The DATA packet has a minimum size of ten octets, using sixteen-bit
   descriptors and no timestamps.

   DATA packets are normally sent error-free using UDP for reliable
   transfer (of both content and delivery).  However, for transfers that
   can tolerate content errors, DATA packets MAY be sent using UDP-Lite.
   If UDP-Lite is used, the file-sender must know that the file-receiver



Wood, et al.             Expires April 28, 2010                [Page 25]

Internet-Draft                  Saratoga                    October 2009


   is capable of handling UDP-Lite, and the file contents to be
   transferred should be resilient to errors.  The UDP-Lite checksum
   MUST protect the Saratoga headers, up to and including the offset
   descriptor, and MAY protect more of each packet's payload, depending
   on the file-sender's knowledge of the internal structure of the file
   and the file's reliability requirements.

   Flag bits 8 and 9 are set to indicate the size of the offset
   descriptor as described for BEACON and METADATA packets, so that each
   DATA packet is self-describing.  This allows the DATA packet to be
   used to construct a file even when the initial METADATA is lost and
   must be resent.  The flag values for bits 8, 9, 10 and 11 MUST be the
   same as indicated in the initial METADATA packet.

   +--------+--------+-------------------------------------------------+
   | Bit 10 | Bit 11 | Type of transfer                                |
   +--------+--------+-------------------------------------------------+
   | 0      | 0      | a file is being sent.                           |
   | 0      | 1      | the file being sent should be interpreted as a  |
   |        |        | directory record.                               |
   | 1      | 0      | a bundle is being sent.                         |
   | 1      | 1      | an indefinite-length stream is being sent.      |
   +--------+--------+-------------------------------------------------+

   Also inside the Flags field, bits 10 and 11 indicate what is being
   transferred - a file, special file that contains directory records,
   bundle, or stream.  The value 01 indicates that the METADATA and DATA
   packets are being generated in response to a _getdir_ REQUEST, and
   that the assembled DATA contents should be interpreted as a sequence
   of Directory Records, as defined in Section 5.

   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 12  | 0     | This packet does not include an optional timestamp  |
   |     |       | field.                                              |
   | 12  | 1     | This packet includes an optional timestamp field.   |
   +-----+-------+-----------------------------------------------------+

   Flag bit 12 indicates that an optional timestamp is carried in the
   packet before the offset field.  The length of this timestamp is the
   length of the offset descriptor field.  Timestamps are particularly
   useful when streaming.  The timestamp format is implementation-
   dependent.







Wood, et al.             Expires April 28, 2010                [Page 26]

Internet-Draft                  Saratoga                    October 2009


           +-----+-------+------------------------------------+
           | Bit | Value | Meaning                            |
           +-----+-------+------------------------------------+
           | 15  | 0     | No response is requested.          |
           | 15  | 1     | A HOLESTOFILL packet is requested. |
           +-----+-------+------------------------------------+

   Within the Flags field, if bit 15 of the packet is set, the file-
   receiver is to immediately generate a HOLESTOFILL packet to provide
   the file-sender with up-to-date information regarding the status of
   the file transfer.  This flag is set carefully and rarely.  It may be
   set periodically, but infrequently.  Asymmetric links with
   constrained backchannels can only carry a limited amount of
   HOLESTOFILL packets before ack congestion becomes a problem.  This
   flag SHOULD NOT be set if an unreliable stream is being transferred,
   or if multicast is in use.  This flag SHOULD be set periodically for
   reliable file transfers, or reliable streaming.

   Immediately following the DATA header is the payload, which consumes
   the remainder of the packet and whose length is implicitly defined by
   the end of the packet.  The payload octets are directly formed from
   the continuous octets starting at the specified Offset in the file
   being transferred.  No special coding is performed.  A zero-octet
   payload length is allowable.

   The length of the Offset fields used within all DATA packets for a
   given transaction MUST be consistent with the length indicated by
   bits 8 and 9 of the transactions METADATA packet.  If the METADATA
   packet has not yet been received, a file-receiver SHOULD request it
   via a HOLESTOFILL packet, and MAY choose to enqueue received DATA
   packets for later processing after the METADATA arrives.

4.5.  HOLESTOFILL

   The HOLESTOFILL packet type is used for feedback from a Saratoga
   file-receiver to a Saratoga file-sender to indicate transaction
   progress and request transmission (usually re-transmission) of
   specific sets of octets within the current transaction (called
   "holes").  This can be used to clean up losses (or indicate no
   losses) at the end of, or during, a transaction, or to efficiently
   resume a transfer that was interrupted in a previous transaction.










Wood, et al.             Expires April 28, 2010                [Page 27]

Internet-Draft                  Saratoga                    October 2009


   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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |1 0|    Type   |               Flags           |     Status    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                Id                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [             Cumulative Acknowledgement (descriptor)           ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                 In-Response-To (timestamp, optional)          ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                 In-Response-To (descriptor)                   ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |               (possibly, several Hole fields)                 /
   /                              ...                              /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   where

   +-----------------+-------------------------------------------------+
   | Field           | Description                                     |
   +-----------------+-------------------------------------------------+
   | Type            | 4                                               |
   | Flags           | are defined below.                              |
   | Id              | identifies the transaction that this packet     |
   |                 | belongs to.                                     |
   | Status          | a value of 0x00 indicates the transfer is       |
   |                 | sucessfully proceeding.  All other values are   |
   |                 | errors terminating the transfer, explained      |
   |                 | below.                                          |
   | Zero-Pad        | an octet fixed at 0x00 to allow later fields to |
   |                 | be conveniently aligned for processing.         |
   | Cumulative      | the offset of the lowest-numbered octet of the  |
   | Acknowledgement | file not yet received.                          |















Wood, et al.             Expires April 28, 2010                [Page 28]

Internet-Draft                  Saratoga                    October 2009


   | In-Response-To  | This is only present if the timestamp flag is   |
   | (optional       | set.  If the HOLESTOFILL packet is voluntary    |
   | timestamp)      | and the voluntary flag is set, this should      |
   |                 | repeat the timestamp of the DATA packet         |
   |                 | containing the highest offset seen.  If the     |
   |                 | HOLESTOFILL packet is in response to a          |
   |                 | mandatory request, this will repeat the         |
   |                 | timestamp of the requesting DATA packet.  The   |
   |                 | file-sender may use these timestamps to         |
   |                 | estimate latency.  There are special            |
   |                 | considerations for streaming, to protect        |
   |                 | against the ambiguity of wrapped offset         |
   |                 | descriptor sequence numbers, discussed below.   |
   | In-Response-To  | the offset of the highest-numbered octet within |
   | (descriptor)    | a DATA packet that generated this HOLESTOFILL   |
   |                 | packet, or the offset of the highest-numbered   |
   |                 | octet seen if this HOLESTOFILL is generated     |
   |                 | voluntarily and the voluntary flag is set.      |
   | Holes           | indications of offset ranges of missing data,   |
   |                 | defined below.                                  |
   +-----------------+-------------------------------------------------+

   The HOLESTOFILL packet has a minimum size of twelve octets, using
   sixteen-bit descriptors and no timestamps.

   The Id field is needed to associate the packet with the transaction
   that it refers to.  Using the Id as a key, the receiver of a packet
   can determine the lengths of the Cumulative Acknowledgement, In-
   Response-To, and Hole offsets used within the HOLESTOFILL packet, as
   this file offset descriptor size was set in the initial METADATA
   packet that established the Id.

   Flags bits 8 and 9 are set to indicate the size of the offset
   descriptor as described for BEACON and METADATA packets, so that each
   HOLESTOFILL packet is self-describing.  The flag values here MUST be
   the same as indicated in the initial METADATA and DATA packets.

   Other bits in the Flags field are defined as:

    +-----+-------+---------------------------------------------------+
    | Bit | Value | Meaning                                           |
    +-----+-------+---------------------------------------------------+
    | 12  | 0     | This packet does not include a timestamp field.   |
    | 12  | 1     | This packet includes an optional timestamp field. |
    +-----+-------+---------------------------------------------------+

   Flag bit 12 indicates that an optional timestamp is carried in the
   packet before the In-Response-To descriptor.  The length of this



Wood, et al.             Expires April 28, 2010                [Page 29]

Internet-Draft                  Saratoga                    October 2009


   timestamp is the length of the descriptor field.

         +-----+-------+----------------------------------------+
         | Bit | Value | Meaning                                |
         +-----+-------+----------------------------------------+
         | 13  | 0     | file's METADATA has been received.     |
         | 13  | 1     | file's METADATA has not been received. |
         +-----+-------+----------------------------------------+

   If bit 13 of a HOLESTOFILL packet has been set to indicate that the
   METADATA has not yet been received, then the METADATA should be
   resent.  This flag should normally be clear.

   +-----+-------+-----------------------------------------------------+
   | Bit | Value | Meaning                                             |
   +-----+-------+-----------------------------------------------------+
   | 14  | 0     | this packet contains the complete current set of    |
   |     |       | holes at the file-receiver.                         |
   | 14  | 1     | this packet contains incomplete hole-state; holes   |
   |     |       | shown in this packet should supplement other        |
   |     |       | incomplete hole-state known to the file-sender.     |
   +-----+-------+-----------------------------------------------------+

   Bit 14 of the HOLESTOFILL packet is only set when there are too many
   holes to fit within a single HOLESTOFILL packet due to MTU
   limitations.  This causes the hole list to be spread out over
   multiple HOLESTOFILL packets, each of which conveys distinct sets of
   holes.  This could occur, for instance, in a large file _put_
   scenario with a long-delay feedback loop and poor physical layer
   conditions.  When losses are light and/or hole reporting and repair
   is relatively frequent, all holes should easily fit within a single
   HOLESTOFILL packet, and this flag will be clear.  Bit 14 should
   normally be clear.

   In some rare cases of high loss, there may be too many holes in the
   received data to convey within a single HOLESTOFILL's size, which is
   limited by the link MTU size.  In this case, multiple HOLESTOFILL
   packets may be generated, and Flags bit 14 should be set on each
   HOLESTOFILL packet accordingly, to indicate that each packet holds
   incomplete results.  The complete group of HOLESTOFILL packets, each
   containing incomplete information, will share common In-Response-To
   information to distinguish them from any earlier groups.

   +-----+-------+----------------------------------------------------+
   | Bit | Value | Meaning                                            |
   +-----+-------+----------------------------------------------------+
   | 15  | 0     | This HOLESTOFILL was requested by the file-sender. |




Wood, et al.             Expires April 28, 2010                [Page 30]

Internet-Draft                  Saratoga                    October 2009


   | 15  | 1     | This HOLESTOFILL is sent voluntarily.              |
   +-----+-------+----------------------------------------------------+

   Flag bit 15 indicates whether the HOLESTOFILL is sent voluntarily or
   due to a request by the sender.  It affects content of the In-
   Response-To timestamp and descriptor fields.

   In the case of a transfer proceeding normally, immediately following
   the HOLESTOFILL packet header shown above, is a set of "Hole"
   definitions.  Each Hole definition is a pair of unsigned integers.
   For a 32-bit offset descriptor, each Hole definition consists of two
   four-octet unsigned integers:

   Hole Definition 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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [             offset to start of hole (descriptor)              ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [              offset to end of hole (descriptor)               ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The start of the hole means the offset of the first unreceived byte
   in that hole.  The end of the hole means the last unreceived byte in
   that hole.

   For 16-bit descriptors, each Hole definition holds two two-octet
   unsigned integers, while Hole definitions for 64- and 128-bit
   descriptors require two eight- and two sixteen-octet unsigned
   integers respectively.

   Since each Hole definition takes up eight octets when 32-bit offset
   lengths are used, we expect that well over 100 such definitions can
   fit in a single HOLESTOFILL packet, given the IPv6 minimum MTU.

   A 'voluntary' HOLESTOFILL is sent at the start of each transaction,
   once METADATA information has been received.  This indicates that the
   receiver is ready to receive the file, or indicates an error or
   rejection code, described below.  A HOLESTOFILL indicating a
   successfully established transfer has a Cumulative Acknowledgement of
   zero and an In-Response-To field of zero.

   A completed transfer is inferred from the reported receiver window
   position.  In the final HOLESTOFILL packet sent (which may be
   repeated, depending on sender behaviour), bit 14 is 0 (indicating a
   complete set of holes in this packet), there are no holestofill
   offset pairs indicating holes, the In-Response-To field points to the



Wood, et al.             Expires April 28, 2010                [Page 31]

Internet-Draft                  Saratoga                    October 2009


   last byte of the file, and the voluntary flag is set.

   In the case of an error causing a transfer to be aborted, the Status
   field holds a code that can be used to explain the cause of the error
   to the other peer.  A zero value indicates that there have been no
   significant errors (this is called a "success HOLESTOFILL" within
   this document), while any non-zero value means the transaction should
   be aborted (this is called a "failure HOLESTOFILL").

   +------------+------------------------------------------------------+
   | Status     | Meaning                                              |
   | Value      |                                                      |
   +------------+------------------------------------------------------+
   | 0x00       | Success, No Errors.                                  |
   | 0x01       | Unspecified Error.                                   |
   | 0x02       | Unable to send file due to resource constraints.     |
   | 0x03       | Unable to receive file due to resource constraints.  |
   | 0x04       | File not found.                                      |
   | 0x05       | Access Denied.                                       |
   | 0x06       | Unknown Id field for transaction.                    |
   | 0x07       | Did not delete file.                                 |
   | 0x08       | File length is longer than REQUEST indicates support |
   |            | for.                                                 |
   | 0x09       | File offset descriptors do not match expected use or |
   |            | file length.                                         |
   | 0x0A       | Unsupported packet type received.                    |
   | 0x0B       | DATA flag bits describing transfer have changed      |
   |            | unexpectedly.                                        |
   | 0x0C       | receiver is no longer interested in receiving this   |
   |            | file.                                                |
   +------------+------------------------------------------------------+

   The recipient of a failure HOLESTOFILL MUST NOT try to process the
   Cumulative Acknowledgement, In-Response-To, or Hole offsets, because,
   in some types of error conditions, the packet's sender may not have
   any way of setting them to the right length for the transaction.

   When sending an indefinite-length stream, the possibility of offset
   sequence numbers wrapping back to zero must be considered.  This can
   be protected against by using large offsets, and by the stream
   receiver.  The receiver MUST separate out holes before the offset
   wraps to zero from holes after the wrap, and send Hole definitions in
   different HOLESTOFILL packets, with Flag 14 set to mark them as
   incomplete.  Any Hole straddling a sequence wrap MUST be broken into
   two separate Holes, with the second Hole starting at zero.  The
   timestamps in HOLESTOFILL packets carrying any pre-wrap holes should
   be earlier than the timestamp in later packets, and should repeat the
   timestamp of the last DATA packet seen for that offset sequence



Wood, et al.             Expires April 28, 2010                [Page 32]

Internet-Draft                  Saratoga                    October 2009


   before the following wrap to zero occurred.  Receivers indicate that
   they no longer wish to receive streams by sending Status Code 0x0C.


5.  The Directory Entry

   Directory Entries have two uses within Saratoga:

   1.  Within a METADATA packet, a Directory Entry is used to give
       information about the file being transferred, in order to
       facilitate proper reassembly of the file and to help the file-
       receiver understand how recently the file may have been created
       or modified.

   2.  When a peer requests a directory listing via a _getdir_ REQUEST,
       the other peer generates a file containing a series of one or
       more concatenated Directory Entry records, and transfers this
       file as it would transfer the response to a normal _get_ REQUEST,
       sending the records together within DATA packets.  This file may
       be either temporary or within-memory and not actually a part of
       the host's file system itself.

   Directory Entry 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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   [                    Size  (descriptor)                         ]
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          Mtime                                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          Ctime                                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Properties   |                                               /
   +-+-+-+-+-+-+-+-+                                               /
   /                                                               /
   /           File Path (max 1024 octets,variable length)         /
   /                                                          ... //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//

   where










Wood, et al.             Expires April 28, 2010                [Page 33]

Internet-Draft                  Saratoga                    October 2009


   +------------+------------------------------------------------------+
   | field      | description                                          |
   +------------+------------------------------------------------------+
   | Size       | the size of the file or directory in octets.         |
   | Mtime      | a timestamp showing when the file or directory was   |
   |            | modified.                                            |
   | Ctime      | the timestamp of the last status change for this     |
   |            | file or directory.                                   |
   | Properties | if set, bit 7 of this field indicates that the entry |
   |            | corresponds to a directory.  Bit 6, if set,          |
   |            | indicates that the file is "special".  A special     |
   |            | file may not be directly transferable as it          |
   |            | corresponds to a symbolic link, a named pipe, a      |
   |            | device node, or some other "special" filesystem      |
   |            | object.  A file-sender may simply choose not to      |
   |            | include these types of files in the results of a     |
   |            | _getdir_ request.                                    |
   | File Path  | contains the file's name relative within the         |
   |            | requested path of the _getdir_ transaction, a        |
   |            | maximum of 1024-octet UTF-8 string, that is          |
   |            | null-terminated to indicate the beginning of the     |
   |            | next directory entry in _getdir_ results             |
   +------------+------------------------------------------------------+

                  +-------+-------+---------------------+
                  | Bit 6 | Bit 7 | Properties conveyed |
                  +-------+-------+---------------------+
                  | 0     | 0     | normal file.        |
                  | 0     | 1     | normal directory.   |
                  | 1     | 0     | special file.       |
                  | 1     | 1     | special directory.  |
                  +-------+-------+---------------------+

   Whether a particular Directory Entry is being interpreted as the
   contents of a METADATA packet, or as the result of a _getdir_
   transaction, the width of the Size field is the same as that used for
   all lengths and offsets within the transfer, given by the METADATA
   and DATA Flags bits 8 and 9.

   Streams listed in a directory should be marked as special.

   It is expected that files are only listed in Directory Entries if
   they can be transferred to the requester.  An implementation only
   capable of receiving small files using 16-bit descriptors will only
   see small files capable of being transferred to it when browsing the
   filesystem of an implementation capable of larger sizes.  Directory
   sizes are not sent, and a Size of 0 is given instead for directories.




Wood, et al.             Expires April 28, 2010                [Page 34]

Internet-Draft                  Saratoga                    October 2009


   The "epoch" format used in the timestamps for Mtime and Ctime in file
   object records is the number of seconds since January 1, 2000 in UTC,
   which is the same epoch used in the DTN Bundle Protocol for
   timestamps and postpones wrapping for 30 years beyond typical 1970-
   based timestamps.  This should include all leapseconds.

   A file-receiver should preserve the timestamp information received in
   the METADATA for its own copy of the file, to allow newer versions of
   files to propagate and supercede older versions.


6.  Behavior of a Saratoga Peer

   This section describes some details of Saratoga implementations and
   uses the RFC 2119 standards language to describe which portions are
   needed for interoperability.

6.1.  Saratoga Transactions

   Following are descriptions of the packet exchanges between two peers
   for each type of transaction.

6.1.1.  The _get_ Transaction

   1.  A peer (the file-receiver) sends a REQUEST packet to its peer
       (the file-sender).  The Flags bits are set to indicate that this
       is not a _delete_ request, nor does the File Path indicate a
       directory.  Each _get_ transaction corresponds to a single file,
       and fetching multiple files requires sending multiple REQUEST
       packets and using multiple transaction Ids. If a specific file is
       being requested, then its name is filled into the File Path
       field, otherwise it is left null and the file-sender will send a
       file of its choice.

   2.  If the request is rejected, then a HOLESTOFILL packet containing
       an error code in the Status field is sent and the transaction is
       terminated.  This HOLESTOFILL packet MUST be sent to reject and
       terminate the transaction.  The error code MAY make use of the
       "Unspecified Error" value for security reasons.  Some REQUESTs
       might also be rejected for specifying files that are too large to
       have their lengths encoded within the maximum integer field width
       advertised by bits 8 and 9 of the REQUEST.

   3.  If the request is accepted, then a HOLESTOFILL packet MUST be
       sent with an error code of 0x00 and an In-Response-To field of
       zero.





Wood, et al.             Expires April 28, 2010                [Page 35]

Internet-Draft                  Saratoga                    October 2009


   4.  Otherwise, if the request is granted, then the file-sender
       generates and sends a METADATA packet along with the contents of
       the file as a series of DATA packets.  In the absence of
       HOLESTOFILL packets, if the file-sender believes it has finished
       sending the file, it MUST send the last DATA packet with the
       Flags bit set requesting a HOLESTOFILL response from the file-
       receiver.  This can be followed by empty DATA packets with the
       Flags bit set requesting a HOLESTOFILL until either a HOLESTOFILL
       packet is received, or the inactivity timer expires.  All of the
       DATA packets MUST use field widths for the file offset descriptor
       fields that match what the Flags of the METADATA packet
       specified.  Some arbitrarily selected DATA packets may have the
       Flags bit set that requests a HOLESTOFILL packet.  The file-
       receiver MAY voluntarily send HOLESTOFILL packets at other times,
       where the In-Response-To field MUST set to zero.  The file-
       receiver SHOULD voluntarily send a HOLESTOFILL packet in response
       to the first DATA packet.

   5.  As the file-receiver takes in the DATA packets, it writes them
       into the file locally.  The file-receiver keeps track of missing
       data in a hole list.  Periodically the file sender will set the
       ack flag bit in a DATA packet and request a HOLESTOFILL packet
       from the file-receiver, with a copy of this hole list.  File-
       receivers MUST send a HOLESTOFILL packet immediately in response
       to receiving a DATA packet with the Flags bit set requesting a
       HOLESTOFILL.

   6.  If the file-sender receives a HOLESTOFILL packet with a non-zero
       number of holes, it re-fetches the file data at the specified
       offsets and re-transmits it.  If the METADATA packet requires
       retransmission, this is indicated by a bit in the HOLESTOFILL
       packet, and the METADATA packet is retransmitted.  The file-
       sender MUST retransmit data from any holes reported by the file-
       receiver before proceeding further with new DATA packets.

   7.  When the file-receiver has fully received the file data and the
       METADATA packet, then it sends a HOLESTOFILL packet indicating
       that the transaction is complete, and it terminates the
       transaction locally, although it MUST persist in responding to
       DATA packets requesting HOLESTOFILLs from the file-sender for
       some reasonable amount of time.

   Given that there may be a high degree of asymmetry in link bandwidth
   between the file-sender and file-receiver, the HOLESTOFILL packets
   should be carefully generated so as to not congest the feedback path.
   This means that both a file-sender should be cautious in setting the
   DATA Flags bit requesting HOLESTOFILLs, and also that a file-receiver
   should be cautious in gratuitously generating HOLESTOFILL packets of



Wood, et al.             Expires April 28, 2010                [Page 36]

Internet-Draft                  Saratoga                    October 2009


   its own volition.  On unidirectional links, a file-sender cannot
   reasonably expect to receive HOLESTOFILL packets, so should never
   request them.

6.1.2.  The _getdir_ Transaction

   A _getdir_ transaction proceeds through the same states as the _get_
   transaction.  The two differences are that the REQUEST has the
   directory bit set in its Flags field, and that, rather than
   transferring the contents of a file from the file-receiver to the
   file-sender, a set of records representing the contents of a
   directory are transferred.  These can be parsed and dealt with by the
   file-receiver as desired.  There is no requirement that a Saratoga
   peer send the full contents of a directory listing; a peer may filter
   the results to only those entries that are actually accessible to the
   requesting peer.

   For _getdir_ transactions, the METADATA's bits 8 and 9 in the Flags
   field specify both the width of the offset and length fields used
   within the transfers DATA and HOLESTOFILL packets, and also the width
   of file Size fields within Directory Entries in the interpreted
   _getdir_ results.  These Flags bits are set to the minimum of the
   file-sender's locally-supported maximum width and the advertised
   maximum width within the REQUEST packet, and any file system entries
   that would normally be contained in the results, but that have sizes
   greater than this width can convey, MUST be filtered out.

6.1.3.  The _delete_ Transaction

   1.  A peer sends a REQUEST packet with the bit set indicating that it
       is a deletion request and the path to be deleted is filled into
       the File Path field.  The File Path MUST be filled in for
       _delete_ transactions, unlike for _get_ transactions.

   2.  The other peer replies with a feedback HOLESTOFILL packet having
       a Status code that indicates whether the deletion was granted and
       occurred successfully (indicated by the 0x00 Status field in a
       success HOLESTOFILL), or whether some error occurred (indicated
       by the non-zero Status field in a failure HOLESTOFILL).  This
       HOLESTOFILL packet MUST have no Holes and 16-bit width zero-
       valued Cumulative Acknowledgement and In-Response-To fields.

6.1.4.  The _put_ Transaction

   A _put_ transaction proceeds exactly as a _get_, except the file-
   sender and file-receiver roles are exchanged between peers, and no
   REQUEST packet is ever sent.  The file-sending end senses that the
   transaction is in progress when it receives METADATA or DATA packets



Wood, et al.             Expires April 28, 2010                [Page 37]

Internet-Draft                  Saratoga                    October 2009


   for which it has no knowledge of the Id field.  If the file-receiver
   decides that it will store and handle this request (at least
   provisionally), then it MUST send a voluntary (ie, not requested)
   success HOLESTOFILL packet to the file-sender.  Otherwise, it sends a
   failure HOLESTOFILL packet.  After sending a failure HOLESTOFILL
   packet, it may ignore future packets with the same Id field from the
   file-sender, but it should, at a low rate, periodically regenerate
   the failure HOLESTOFILL packet if the flow of packets does not stop.

6.2.  Beacons

   Sending BEACON packets is not needed in any of the transactions
   discussed in this specification, but optional BEACONs can provide
   useful information in many situations.  If a node periodically
   generates BEACON packets, then it should do so at a low rate which
   does not significantly affect in-progress data transfers.

   A node that supports multiple versions of Saratoga (e.g. version 1
   from this specification along with the older version 0), MAY send
   multiple BEACON packets showing different version numbers.  The
   version number in a single BEACON should not be used to infer the
   larger set of protocol versions that a peer is compatible with.

   If a node receives BEACONs from a peer, then it SHOULD NOT attempt to
   start any _get_, _getdir_, or _delete_ transactions with that peer if
   bit 14 is not set in the latest received BEACONs.  Likewise, if
   received BEACONs from a peer do not have bit 15 set, then _put_
   transactions SHOULD NOT be attempted to that peer.  Unlike the
   capabilities bits which prevent certain types of transactions from
   being attempted, the willingness bits are advisory, and transactions
   MAY be attempted even if the node is not advertising a willingness,
   as long as it advertises a capability.  This avoids waiting for a
   willingness indication across long-delay links.

6.3.  Upper-Layer Interface

   No particular interface functionality is required in implementations
   of this specification.  The means and degree of access to Saratoga
   configuration settings and transaction control that is offered to
   upper layers and applications is completely implementation-dependent.
   In general, it is expected that upper layers (or users) can set
   timeout values for transaction requests and for inactivity periods
   during the transaction, on a per-peer or per-transaction basis, but
   in some implementations where the Saratoga code is restricted to run
   only over certain interfaces with well-understood operational latency
   bounds, then these timers MAY be hard-coded.





Wood, et al.             Expires April 28, 2010                [Page 38]

Internet-Draft                  Saratoga                    October 2009


6.4.  Inactivity Timer

   In order to determine the liveliness of a transaction, Saratoga nodes
   may implement an inactivity timer for each peer they are expecting to
   see packets from.  For each packet received from a peer, its
   associated inactivity timer is reset.  If no packets are received for
   some amount of time, and the inactivity timer expires, this serves as
   a signal to the node that it should abort (and optionally retry) any
   sessions that were in progress with the peer.  Information from the
   link interface (i.e. link down) can override this timer for point-to-
   point links.

   The actual length of time that the inactivity timer runs for is a
   matter of both implementation and deployment situation.  Relatively
   short timers (on the order of several round-trip times) allow nodes
   to quickly react to loss of contact, while longer timers allow for
   transaction robustness in the presence of transient link problems.
   This document deliberately does not specify a particular inactivity
   timer value nor any rules for setting the inactivity timer, because
   the protocol is intended to be used in both long- and short-delay
   regimes.

   Specifically, the inactivity timer is started on sending REQUEST or
   HOLESTOFILL packets.  When sending packets not expected to elicit
   responses (BEACON, METADATA, or DATA without acknowledgement
   requests), there is no point to starting the local inactivity timer.

   For normal file transfers, there are simple rules for handling
   expiration of the inactivity timer during a _get_ or _put_
   transaction.  The file-sender SHOULD terminate the transaction state
   and cease to send DATA or METADATA packets.  The file-receiver SHOULD
   stop sending HOLESTOFILL packets, and MAY choose to store the file in
   some cache location so that the transfer can be recovered.  This is
   possible by waiting for an opportunity to re-attempt the transaction
   and immediately sending a HOLESTOFILL that only lists the parts of
   the file not yet received if the transaction is granted.  In any
   case, a partially-received file MUST NOT be handled in any way that
   would allow another application to think it is complete.

   The file-sender may implement more complex timers to allow rate-based
   pacing or simple congestion control using information provided in
   HOLESTOFILL packets, but such possible timers and their effects are
   deliberately not specified here.


7.  Mailing list

   There is a mailing list for discussion of Saratoga and its



Wood, et al.             Expires April 28, 2010                [Page 39]

Internet-Draft                  Saratoga                    October 2009


   implementations.  Contact Lloyd Wood for details.


8.  Security Considerations

   The design of Saratoga provides limited, deliberately lightweight,
   services for authentication of session requests, and for
   authentication or encryption of data files via keyed metadata
   checksums.  This document does not specify privacy or access control
   for data files transferred.  Privacy, access, authentication and
   encryption issues may be addressed within an implementation or
   deployment in several ways that do not affect the file transfer
   protocol itself.  As examples, IPsec may be used to protect Saratoga
   implementations from forged packets, to provide privacy, or to
   authenticate the identity of a peer.  Other implementation-specific
   or configuration-specific mechanisms and policies might also be
   employed for authentication and authorization of requests.
   Protection of file data and meta-data can also be provided by a
   higher-level file encryption facility.  If IPsec is not required, use
   of encryption before the file is given to Saratoga is preferable.
   Basic security practices like not accepting paths with "..", not
   following symbolic links, and using a chroot() system call, among
   others, should also be considered within an implementation.

   Note that Saratoga is intended solely for single-hop transfers
   between peers.  A METADATA checksum using a previously shared key can
   be used to decrypt or authenticate delivered DATA files.  Saratoga
   can only provide encryption across a single link, not end-to-end
   across concatenated links through untrusted peers, as checksum
   verification of file integrity is required at each node.  End-to-end
   data encryption, if required, MUST be implemented by the application
   using Saratoga.


9.  IANA Considerations

   IANA has allocated port 7542 (tcp/udp) for use by Saratoga.

   saratoga        7542/tcp    Saratoga Transfer Protocol
   saratoga        7542/udp    Saratoga Transfer Protocol

   IANA has allocated a dedicated IPv4 all-hosts multicast address
   (224.0.0.108) and a dedicated IPv6 link-local multicast addresses
   (FF02:0:0:0:0:0:0:6c) for use by Saratoga.







Wood, et al.             Expires April 28, 2010                [Page 40]

Internet-Draft                  Saratoga                    October 2009


10.  Acknowledgements

   Developing and deploying the on-orbit IP infrastructure of the
   Disaster Monitoring Constellation, in which Saratoga has proven
   useful, has taken the efforts of hundreds of people over more than a
   decade.  We thank them all.

   Work on this document at NASA's Glenn Research Center was funded by
   NASA's Earth Science Technology Office (ESTO).

   We thank Stewart Bryant, Cathryn Peoples and Charles Smith for their
   review comments.


11.  A Note on Naming

   Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier
   sunk at Bikini Atoll that is now a popular diving site.


12.  References

12.1.  Normative References

   [RFC0768]  Postel, J., "User Datagram Protocol", STD 6, RFC 768,
              August 1980.

   [RFC1321]  Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
              April 1992.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3309]  Stone, J., Stewart, R., and D. Otis, "Stream Control
              Transmission Protocol (SCTP) Checksum Change", RFC 3309,
              September 2002.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC3828]  Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and
              G. Fairhurst, "The Lightweight User Datagram Protocol
              (UDP-Lite)", RFC 3828, July 2004.

12.2.  Informative References

   [Hogie05]  Hogie, K., Criscuolo, E., and R. Parise, "Using Standard
              Internet Protocols and Applications in Space", Computer



Wood, et al.             Expires April 28, 2010                [Page 41]

Internet-Draft                  Saratoga                    October 2009


              Networks, Special Issue on Interplanetary Internet, vol.
              47, no. 5, pp. 603-650, April 2005.

   [I-D.ietf-ledbat-congestion]
              Shalunov, S., "Low Extra Delay Background Transport
              (LEDBAT)", draft-ietf-ledbat-congestion-00 (work in
              progress), October 2009.

   [I-D.wood-dtnrg-http-dtn-delivery]
              Wood, L. and P. Holliday, "Using HTTP for delivery in
              Delay/Disruption-Tolerant Networks",
              draft-wood-dtnrg-http-dtn-delivery-04 (work in progress) ,
              October 2009.

   [I-D.wood-dtnrg-saratoga]
              Wood, L., McKim, J., Eddy, W., Ivancic, W., and C.
              Jackson, "Using Saratoga with a Bundle Agent as a
              Convergence Layer for Delay-Tolerant Networking",
              draft-wood-dtnrg-saratoga-06 (work in progress) ,
              October 2009.

   [Jackson04]
              Jackson, C., "Saratoga File Transfer Protocol", Surrey
              Satellite Technology Ltd internal technical document ,
              2004.

   [RFC0959]  Postel, J. and J. Reynolds, "File Transfer Protocol",
              STD 9, RFC 959, October 1985.

   [RFC3366]  Fairhurst, G. and L. Wood, "Advice to link designers on
              link Automatic Repeat reQuest (ARQ)", BCP 62, RFC 3366,
              August 2002.

   [RFC3448]  Handley, M., Floyd, S., Padhye, J., and J. Widmer, "TCP
              Friendly Rate Control (TFRC): Protocol Specification",
              RFC 3448, January 2003.

   [RFC5050]  Scott, K. and S. Burleigh, "Bundle Protocol
              Specification", RFC 5050, November 2007.

   [Wood07a]  Wood, L., Ivancic, W., Hodgson, D., Miller, E., Conner,
              B., Lynch, S., Jackson, C., da Silva Curiel, A., Cooke,
              D., Shell, D., Walke, J., and D. Stewart, "Using Internet
              Nodes and Routers Onboard Satellites", International
              Journal of Satellite Communications and
              Networking, Special Issue on Space Networks, vol. 25, no.
              2, pp. 195-216, March/April 2007.




Wood, et al.             Expires April 28, 2010                [Page 42]

Internet-Draft                  Saratoga                    October 2009


   [Wood07b]  Wood, L., Eddy, W., Ivancic, W., Miller, E., McKim, J.,
              and C. Jackson, "Saratoga: a Delay-Tolerant Networking
              convergence layer with efficient link utilization",
              International Workshop on Satellite and Space
              Communications (IWSSC '07) Salzburg, September 2007.


Authors' Addresses

   Lloyd Wood
   Surrey, England

   Email: L.Wood@society.surrey.ac.uk


   Jim McKim
   RS Information Systems
   NASA Glenn Research Center
   21000 Brookpark Road, MS 142-1
   Cleveland, OH  44135
   USA

   Phone: +1-216-433-6536
   Email: James.H.McKim@grc.nasa.gov


   Wesley M. Eddy
   Verizon Federal Network Systems
   NASA Glenn Research Center
   21000 Brookpark Road, MS 54-5
   Cleveland, OH  44135
   USA

   Phone: +1-216-433-6682
   Email: weddy@grc.nasa.gov


   Will Ivancic
   NASA Glenn Research Center
   21000 Brookpark Road, MS 54-5
   Cleveland, OH  44135
   USA

   Phone: +1-216-433-3494
   Email: William.D.Ivancic@grc.nasa.gov






Wood, et al.             Expires April 28, 2010                [Page 43]

Internet-Draft                  Saratoga                    October 2009


   Chris Jackson
   Surrey Satellite Technology Ltd
   Tycho House
   Surrey Space Centre
   20 Stephenson Road
   Guildford, Surrey  GU2 7YE
   United Kingdom

   Phone: +44-1483-803-803
   Email: C.Jackson@sstl.co.uk









































Wood, et al.             Expires April 28, 2010                [Page 44]


Html markup produced by rfcmarkup 1.108, available from http://tools.ietf.org/tools/rfcmarkup/