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

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

Network Working Group                                            L. Wood
Internet-Draft                                             Cisco Systems
Intended status: Experimental                                   J. McKim
Expires: November 19, 2007                                          RSIS
                                                                 W. Eddy
                                                              W. Ivancic
                                                              C. Jackson
                                                            May 18, 2007

      Saratoga: A Convergence Layer for Delay Tolerant Networking

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   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-

   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

   The list of Internet-Draft Shadow Directories can be accessed at

   This Internet-Draft will expire on November 19, 2007.

Copyright Notice

   Copyright (C) The IETF Trust (2007).


   Saratoga is a simple, lightweight UDP-based transport protocol

Wood, et al.            Expires November 19, 2007               [Page 1]

Internet-Draft              Saratoga Protocol                   May 2007

   intended for use between immediately neighbouring peers which have
   sporadic, intermittent connectivity using dedicated IP links.
   Saratoga focuses on link utilization and loss recovery via an ARQ
   mechanism.  Saratoga is not intended for use over shared paths, so
   transport congestion control is unnecessary.  Saratoga is in
   continuous use by the IP-based Disaster Monitoring Constellation
   satellites in Low Earth Orbit (LEO), and is proposed for use as a
   convergence layer by Delay Tolerant Networking for deep-space and ad-
   hoc networking scenarios.

Table of Contents

   1.  Background and Introduction  . . . . . . . . . . . . . . . . .  3
   2.  Overview of Saratoga File/Bundle Transfer  . . . . . . . . . .  5
     2.1.  Example File Transfers . . . . . . . . . . . . . . . . . .  5
     2.2.  Using Saratoga with a DTN Bundle Agent . . . . . . . . . .  8
   3.  Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 10
     3.1.  BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 12
     3.2.  REQUEST  . . . . . . . . . . . . . . . . . . . . . . . . . 15
     3.3.  METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 17
     3.4.  DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
     3.5.  HOLETOFILL . . . . . . . . . . . . . . . . . . . . . . . . 20
   4.  Directory Entry  . . . . . . . . . . . . . . . . . . . . . . . 24
   5.  Behavior of a Saratoga Peer  . . . . . . . . . . . . . . . . . 26
     5.1.  Saratoga Transactions  . . . . . . . . . . . . . . . . . . 26
     5.2.  Beacons  . . . . . . . . . . . . . . . . . . . . . . . . . 29
     5.3.  Upper-Layer Interface  . . . . . . . . . . . . . . . . . . 30
     5.4.  Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 30
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 31
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 32
   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32
   9.  A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 32
   10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32
     10.1. Normative References . . . . . . . . . . . . . . . . . . . 32
     10.2. Informative References . . . . . . . . . . . . . . . . . . 32
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33
   Intellectual Property and Copyright Statements . . . . . . . . . . 36

Wood, et al.            Expires November 19, 2007               [Page 2]

Internet-Draft              Saratoga Protocol                   May 2007

1.  Background and Introduction

   Saratoga is a rate-based UDP file transfer protocol capable of
   efficiently transferring both small and very large files.  Saratoga
   has been implemented and used since 2004 to move mission imaging data
   from the Disaster Monitoring Constellation remote-sensing satellites
   to ground stations.  These satellites, built by Surrey Satellite
   Technology Ltd (SSTL), all use IP for payload communications and
   delivery of Earth imagery.  Five satellites are already operational
   in orbit; three more are under construction.  Further details on how
   these satellites use IP to communicate with the ground and the
   terrestrial Internet are discussed in other documents

   Saratoga can be used in Delay/Disruption-Tolerant Networking (DTN)
   [RFC4838], as a "convergence layer" to exchange DTN bundles
   [I-D.irtf-dtnrg-bundle-spec] between peer nodes.  The DTN concept is
   applicable to networks where ad-hoc, intermittent connectivity is the
   norm, connections between peers are intermittent and infrequent, and
   end-to-end paths are not present.  Saratoga's design presumes that
   links are not shared, but rather that the links are dedicated to a
   pair of peer DTN nodes that can exchange store-and-forward bundle
   messages.  Each node runs a single instance of Saratoga; any
   multiplexing of simultaneous data transfers takes place in sessions
   between the peering instances of Saratoga.

   Use of store-and-forward delivery is typical of DTN scenarios in
   space exploration for both near-Earth and deep-space missions, and
   useful for other DTN scenarios, such as underwater networking, ad-hoc
   sensor networks, and some message-ferrying relay scenarios.

   High link utilization while a link is established is important in
   order to get the most utility out of the available, but limited,
   connectivity.  Recovery from packets lost due to channel errors is
   important.  Congestion control, to arbitrate fairly between competing
   traffic, is not considered important, as nodes peer without
   competition from other nodes, and loss is never due to congestion.
   Saratoga's design is intended for dedicated point-to-point links
   between peers.  In a shared wireless ad-hoc environment, allocation
   of channel resources to nodes to establish these links becomes a MAC-
   layer function.  Forward error coding to get the most reliable
   transmission through a channel is best left near the physical layer,
   and complements the transport-level negative-acknowledgement approach
   to providea reliable ARQ mechanism [RFC3366] that is presented here.

   Saratoga is capable of transferring small or large files, by choosing
   a width of file offset descriptor appropriate for the filesize, and
   advertising accepted descriptor sizes. 16-bit, 32-bit, 64-bit and

Wood, et al.            Expires November 19, 2007               [Page 3]

Internet-Draft              Saratoga Protocol                   May 2007

   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 4GiB in size, and
   so require a descriptor 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.

   Saratoga can be used with either IPv4 or IPv6.  By using an IP-based
   convergence layer, compatibility between Saratoga and the wide
   variety of links that can already carry IP traffic is assured.  Due
   to widespread compatibility with a vast variety of existing link
   layers, IP is the logical choice of network layer to support DTN
   convergence layers, even though the scheduled or intermittent and
   point-to-point peering operating paradigm behind this use of IP here
   differs from the traditional congestion and competition-oriented
   model that has become established in the fixed terrestrial Internet.

   Some of the motivations in the design of Saratoga are similar to
   those for the Licklider Transmission Protocol (LTP)
   [I-D.irtf-dtnrg-ltp-motivation].  Both of these protocols were
   designed based on experience gained with using the CCSDS File
   Delivery Protocol (CFDP), which was developed for the Consulative
   Committee for Space Data Systems (CCSDS).  The main design difference
   between LTP and Saratoga is that LTP transfers arbitrary un-named
   data blobs (binary large objects), while Saratoga transfers named
   files including file metadata.  LTP can also permit some portion of
   trailing bytes of a blob to be transferred unreliably, which is a
   feature that Saratoga does not support because its focus on file
   transfer requires reliable delivery.

   Saratoga was originally implemented as outlined in [Jackson04], but
   the specification given here differs substantially, as we have added
   a number of features to support DTN bundling, 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 file or bundle transfer
   procedure and transactions using Saratoga in Section 2, followed by a
   formal definition of the packet types used by Saratoga in Section 3,
   and the details of the various protocol mechanisms in Section 5.

   Here, Saratoga transaction types are labelled with underscores around

Wood, et al.            Expires November 19, 2007               [Page 4]

Internet-Draft              Saratoga Protocol                   May 2007

   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 key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in RFC 2119.  [RFC2119]

2.  Overview of Saratoga File/Bundle Transfer

   Saratoga was originally designed for file transfer from LEO imaging
   satellites to the ground, prior to the DTNRG's work on the Bundle
   Protocol [I-D.irtf-dtnrg-bundle-spec].  It was later recognized that
   Saratoga could be used to reliably exchange bundles between DTN
   Bundle Agents by using a logical mapping between DTN bundles and
   Saratoga files and back.  In this section we first describe a typical
   file transfer process using Saratoga and then describe the way that
   Saratoga has been used to reliably and efficiently transfer bundles.

   Saratoga is a peer-to-peer protocol in the sense that between two
   Saratoga peers files may be transferred in both directions
   simultaneously.  Two separate unidirectional file transfers would
   need to be established to do simultaneous transfers.  The
   implementations of Saratoga at each end can be identical equivalent

2.1.  Example File Transfers

   Saratoga nodes are simple file servers.  Saratoga supports several
   types of operations on files including upload, download, directory
   listing, and deletion requests.  Each request begins a "transaction".

   Saratoga nodes MAY advertise their presence, capabilities and desires
   by periodically sending BEACON packets.  These BEACONs are sent to
   either a subnet-directed broadcast address when using IPv4 or a link-
   local all-Saratoga-peers multicast address when using IPv6.  Saratoga
   nodes may discover other Saratoga nodes either through listening for
   BEACONs, through pre-configuration, or via some other trigger from a
   user, lower-layer 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.

   There is an assumption that if multiple nodes do hear a BEACON on a
   link shared by more than two peers and respond with transaction
   requests, the node that sent the BEACON will favour one request and
   complete that before turning to other requests.  In such cases, a

Wood, et al.            Expires November 19, 2007               [Page 5]

Internet-Draft              Saratoga Protocol                   May 2007

   cooperative coarse-grained scheduling model, where transactions
   between different nodes are completed consecutively rather than
   simultaneously, would be desirable.  Currently, no protocol mechanism
   enforces this.  There is no required response to received BEACONs.
   Since request packets are generally small, and the number of nodes
   sharing a link should be small, the number of simultaneous
   transaction requests for a node to deal with, and decide between,
   will also be small.

   A Saratoga transaction begins with either a _get_, _put_, _getdir_,
   or _delete_ transaction request, 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,
   follwed by some number of DATA packets constituting the directory
   listing's contents or 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 HOLETOFILL packet.  The HOLETOFILL
   packet lists which octets of the file have not yet been received and
   whether or not the METADATA packet was received.  From this
   HOLETOFILL packet, the file-sender begins a cycle of selective
   retransmission of DATA packets, until it sees a HOLETOFILL packet
   that acknowledges total reception of all file data.

   In the example scenario in Figure 1, a_get_ request is granted and
   experiences loss of a single DATA packet due to channel-induced

Wood, et al.            Expires November 19, 2007               [Page 6]

Internet-Draft              Saratoga Protocol                   May 2007

         File-Receiver               File-Sender

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

               Figure 1: Example _get_ transaction sequence

   A _getdir_ request proceeds similarly.

   The HOLETOFILL 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 HOLETOFILL 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

   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 HOLETOFILL.  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.

   Figure 2 illustrates the sequence of packets in an example _put_
   transaction where the second DATA packet is lost.

Wood, et al.            Expires November 19, 2007               [Page 7]

Internet-Draft              Saratoga Protocol                   May 2007

                        File-Sender           File-Receiver

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

                Figure 2: Example PUT transaction sequence

   The _delete_ transactions are simple single packet requests that
   trigger a HOLETOFILL 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 HOLETOFILL packet.

2.2.  Using Saratoga with a DTN Bundle Agent

   While Saratoga was first developed for efficient file transfer, the
   similarity between bundle payloads and files, in that both are
   arbitrary blobs of some number of octets, allows Saratoga to be used
   as a convergence layer for exchanging bundles between DTN bundle
   agents.  This section explains the basic concepts involved in mapping
   bundle exchange onto the file transfer mechanism.

   Routing of bundles is outside the scope of Saratoga and this
   document.  Once a complete bundle file has been transferred between
   peers using Saratoga, it can be forwarded onwards along a next
   available hop in any way.

   A DTN bundle agent can work alongside a Saragota peer to move bundles
   if there is a directory accessible to both the DTN and Saratoga
   processes.  To send a bundle, the bundle agent places the complete
   bundle (the concatenated set of Bundle Protocol blocks) into a file
   in the shared directory.  The local Saratoga instance is then able to
   _put_ this bundle to peers or allow them to _get_ it.  A flag bit in
   the Saratoga METADATA packet indicates whether a particular file is a
   bundle or not, so the receiving Saratoga peer knows whether to write
   the received data to the local filesystem as a simple file, or to
   pass it to a local bundle agent that it is working with.

   Note that the name of a file holding a bundle is actually
   unimportant, as long as it can be determined that it does hold a

Wood, et al.            Expires November 19, 2007               [Page 8]

Internet-Draft              Saratoga Protocol                   May 2007

   bundle.  One implementation strategy is to name each bundle file with
   a file name constructed from two fields of the Primary Bundle Header:
   the DTN Endpoint Identifier (EID) of the destination node and the
   bundle's creation time field.  In the rare case of file name
   collisions in using this scheme, additional octets can be appended to
   the filename following some arbitrary local scheme.  Bundle files
   might be placed in different directories with different Saratoga-peer
   access controls depending on the intended next-hop, if this
   information is known ahead of time.  In any case, Saratoga only
   handles reliable transfers, and any forwarding decisions based on
   routing intelligence are made within the DTN bundle agents.  All of
   this detail is considered a matter of implementation for the bundle
   agent, and not specified here.

   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 bundle agent coordinating with one Saratoga peer to
   blindly request any bundle files that the other Saratoga peer's
   bundle agent has ready for it, without prior knowledge of the
   directory listing, and without requiring the ability to determine
   whether files are bundle files or decode remote file names/paths for
   meaningful information such as final destination.

   A field in the Saratoga BEACON packet allows a local DTN bundle agent
   to advertise its administrative EID via Saratoga, so that other
   Saratoga peers that hear that BEACON can notify their local DTN
   bundle agents of the contact.  These notifications might be used to
   integrate contact information into a routing information base, as
   they are similar to the "hello" packets used in several routing
   protocols.  However, this is outside the scope of this document.

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

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

   (2) To avoid bundle 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 HOLETOFILL
   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 that of the previous METADATA in order to re-
   establish the transfer.  Otherwise, the file-receiver MUST assume

Wood, et al.            Expires November 19, 2007               [Page 9]

Internet-Draft              Saratoga Protocol                   May 2007

   that the file has changed and purge the DATA received during the
   first contact.

   This version of the Saratoga specification does not specify the
   functionality required for reactive fragmentation of bundles as
   described in [RFC4838], other than what is needed to support
   disrupted delivery and hop-by-hop custody transfer.

   However, the status of a transfer that Saratoga provides to a bundle
   agent could be used to trigger the reactive fragmentation of bundles
   if a bundle file transfer is interrupted part-way through (assuming
   at least the bundle protocol headers and some portion of the data was
   successfully transferred first).  This would allow for efficient
   recovery when unplanned interruptions occur.  On each end, this
   requires some coordination between the Saratoga node and the local
   bundle agent, but the local API or coupling between these does not
   affect the interoperability between either the Saratoga peers or the
   DTN bundle agents, assuming that both sides agree that fragmentation
   will occur at the lowest un-acknowledged octet of the bundle file
   after the disruption.  This reactive fragmentation and any forwarding
   of the fragments onwards for reassembly at some downstream node is a
   bundle problem.  Reactive fragmentation lies outside the scope of
   custody transfer, of Saratoga and of this document.

3.  Packet Types

   Saratoga is defined for use with UDP over either IPv4 or IPv6
   [RFC0768].  UDP checksums MUST be used.  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

                       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 ... //

   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

Wood, et al.            Expires November 19, 2007              [Page 10]

Internet-Draft              Saratoga Protocol                   May 2007

   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 | HOLETOFILL | Signals list of unreceived data to sender |

   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 follow in the
   remainder of this section.  Some packet types contain file descriptor
   fields.  The lengths of file descriptors are fixed within a transfer,
   but vary between file transfers.  The size is set for each particular
   transfer, depending on the choice of file descriptor width made in
   the METADATA packet, which in turn depends on the size of file being

   In this document, all of the packet structure figures illustrating a
   packet format assume 32-bit lengths for these file 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:

Wood, et al.            Expires November 19, 2007              [Page 11]

Internet-Draft              Saratoga Protocol                   May 2007

   128-bit descriptor for very long files (optional)

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

   64-bit descriptor for longer files (optional)

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

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

   [         (descriptor)          ]

   Saratoga packets are intended to fit within link MTUs to avoid the
   inefficiences 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.

3.1.  BEACON

   BEACON packets may be broadcast 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 liveness
   or presence of the peer.

Wood, et al.            Expires November 19, 2007              [Page 12]

Internet-Draft              Saratoga Protocol                   May 2007


    0                   1
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
   |0 1|    Type   |    Flags      | Bundle Agent EID ...


   | 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.                                           |
   | Bundle | advertises the EID of a bundle agent administrative node |
   | Agent  | that the BEACON-sender is associated with, or some other |
   | EID    | peer-identifying string if no bundle agent is present.   |

   The Flags field is used to provide some additional information about
   the peer.  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 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. |

   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.

Wood, et al.            Expires November 19, 2007              [Page 13]

Internet-Draft              Saratoga Protocol                   May 2007

   | Bit 12 | Bit 14 | Willingness and capability to send files       |
   | 0      | 0      | cannot send files at all.                      |
   | 0      | 1      | capable of sending, but not willing right now. |
   | 1      | 0      | invalid.                                       |
   | 1      | 1      | capable of and willing to send files.          |

   | Bit 13 | Bit 15 | Willingness and capability to receive files     |
   | 0      | 0      | cannot receive files at all.                    |
   | 0      | 1      | capable of receiving, but will reject METADATA. |
   | 1      | 0      | invalid.                                        |
   | 1      | 1      | capable of and willing to receive files.        |

   Also in the Flags field, bits 14 and 15 act as capabilities bits,
   while bits 12 and 13 act as willingness bits.  If bit 14 is set, then
   the peer has the capability to send files.  A peer that is able to
   act as a file-sender MUST set this bit 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 12 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 14.

   If bit 15 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 13 expresses a current general willingness to receive
   and accept files.

   Although a Saratoga implementation does not need to be working in
   conjunction with a DTN bundle agent, the combination will frequently
   be the case.  Saratoga BEACON packets include the administrative
   Endpoint ID of a DTN bundle agent that it is working in conjunction
   with.  This is not a prerequisite for bundle file transfers, or any
   other functionality, but is merely a convenient way to advertise the
   presence of a bundle agent along with the advertisement of Saratoga
   services.  For Saratoga implementations or deployments that do not
   involve bundle agent cooperation, some other type of host-identifier
   can be used in this 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.

Wood, et al.            Expires November 19, 2007              [Page 14]

Internet-Draft              Saratoga Protocol                   May 2007


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


    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 ...             /
   /        ... (Id cont.)         |         File Path ...


   | 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.  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 November 19, 2007              [Page 15]

Internet-Draft              Saratoga Protocol                   May 2007

   | Bit     | Value | Meaning                                         |
   | Number  |       |                                                 |
   | 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_                      |

   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 whatever the local conventions
   on the peers are 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 length of the packet indicates that the File Path field is
   empty (zero-length), 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 is useful in bundle
   transfer, as it permits the file-sender to determine the order and
   selection of bundle files that it would like to forward through the
   file-receiving host's bundle agent in more of a "push" manner.  Of
   course, bundle file retrieval could also follow a "pull" manner, with
   the file-receiving host requesting specific bundle 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-sized bundles, or make other optimizations, such as using its
   local knowledge of contacts to pick small bundles that it has the

Wood, et al.            Expires November 19, 2007              [Page 16]

Internet-Draft              Saratoga Protocol                   May 2007

   best odds of being able to deliver completely.  Bundle file transfer
   through pushing sender-selected files implements delivery
   prioritization decisions made solely at the Saratoga file-sending
   node.  Bundle 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).


   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 descriptor
   is chosen for the session.


    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 ...               /
   /       ... (Id cont.)          |         MD5 Sum ...           /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               /
   /                                                               /
   /          ...  (MD5 Sum cont. middle 96-bits) ...              /
   /                                                               /
   /                               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /     ... (MD5 Sum cont.)       |                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               /
   /                                                               /
   /            single Directory Entry describing file             /
   /                      (variable length)                        /
   /                                                               /


   | Field     | Description                                           |
   | Type      | 2                                                     |
   | Flags     | indicate additional boolean metadata about a file     |
   | Id        | identifies the transaction that this packet describes |
   | MD5 Sum   | full 128-bit MD5 checksum over file contents          |

Wood, et al.            Expires November 19, 2007              [Page 17]

Internet-Draft              Saratoga Protocol                   May 2007

   | Directory | describes file system information about the file,     |
   | Entry     | including length, timestamps, etc.; the format is     |
   |           | specified in Section 4                                |

   In the Flags field, the bits labelled 8 and 9 in the figure above
   indicate the exact size of the file length 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
   HOLETOFILL packets within the session that will follow this packet.

              | Bit 10 | Bit 11 | Checksum capability      |
              | 0      | 0      | no checksum is present.  |
              | 0      | 1      | MD5 checksum is present. |
              | 1      | 0      | reserved for future use. |
              | 1      | 1      | reserved for future use. |

   Also inside the Flags field, bits 10 and 11 indicate the integrity
   checksum for the file to be transferred.  If 00, no checksum is
   present, and higher-level end-to-end checks within the bundle must be
   relied upon.  If 01, an MD5 checksum of the file to be transferred is
   carried as shown, with a fixed 128-bit field before the varying-
   length File Length and File Name information fields.  Other flag
   combinations are reserved for future use.  It is expected that 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 a weaker
   checksum can suffice.

   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 integrity checking
   (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.

Wood, et al.            Expires November 19, 2007              [Page 18]

Internet-Draft              Saratoga Protocol                   May 2007

   | Bit   | Bit   | Bundles and records                               |
   | 14    | 15    |                                                   |
   | 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     | invalid.                                          |

   Also inside the Flags field, bit 15 of the packet signals whether or
   not the file being transferred is a bundle file.  This bit is set to
   1 if the file's contents are blocks belonging to a DTN bundle,
   otherwise this bit is set to 0.  Bit 14 of the Flags, if set,
   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 4.  If bit 14 is set, bit 15 will be 0.

3.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/bundle data being transferred.


    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 ...              /
   /       ... (Id cont.)          [      Offset (descriptor)...   /
   /     ... (Offset cont.)        ]


   | Field  | Description                                              |
   | Type   | 3                                                        |
   | Flags  | bit 15 requests an immediate HOLETOFILL ack to be        |
   |        | generated in response to receiving this packet           |
   | Id     | identifies the transaction that this packet belongs to   |

Wood, et al.            Expires November 19, 2007              [Page 19]

Internet-Draft              Saratoga Protocol                   May 2007

   | Offset | the offset in octets to the location where the first     |
   |        | byte of this packet's payload is to be written           |

   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 here MUST be the same as indicated
   in the initial METADATA packet.

   Immediately following the ten-octet 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.

   Within the Flags field, if bit 15 of the packet is set, the file-
   receiver is to immediately generate a HOLETOFILL packet to provide
   the file-sender with up-to-date information regarding the status of
   the file transfer.

   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 HOLETOFILL packet, and MAY choose to enqueue received DATA
   packets for later processing after the METADATA arrives.


   The HOLETOFILL 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 November 19, 2007              [Page 20]

Internet-Draft              Saratoga Protocol                   May 2007


    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     |          Id ...               /
   /      ... (Id cont.)           |     Status    |    Zero-Pad   |
   [             Cumulative Acknowledgement (descriptor)           ]
   [                 In-Response-To (descriptor)                   ]
   |               (possibly, several Hole fields)                 /
   /                              ...                              /


   | Field           | Description                                     |
   | Type            | 4                                               |
   | Flags           | 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.                          |
   | In-Response-To  | the offset of the highest-numbered octet within |
   |                 | a DATA packet that generated this HOLETOFILL    |
   |                 | packet, or 0 if this HOLETOFILL is generated    |
   |                 | voluntarily.                                    |
   | Holes           | indications of offset ranges of missing data,   |
   |                 | defined below.                                  |

   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 HOLETOFILL packet, as
   this file descriptor size was set in the initial METADATA packet that
   established the Id.

Wood, et al.            Expires November 19, 2007              [Page 21]

Internet-Draft              Saratoga Protocol                   May 2007

   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
   HOLETOFILL 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                                          |
   | Number |       |                                                  |
   | 14     | 0     | file's METADATA has not been received.           |
   | 14     | 1     | file's METADATA has been received.               |
   | 15     | 0     | this packet contains the complete current set of |
   |        |       | holes at the file-receiver.                      |
   | 15     | 1     | this packet contains incomplete hole-state;      |
   |        |       | holes shown in this packet should supplement any |
   |        |       | previous hole-state known to the file-sender.    |

   If bit 14 of a HOLETOFILL packet indicates that the METADATA has not
   yet been received, then the receiver of the packet MUST NOT attempt
   to parse the Cumulative Acknowledgement, In-Response-To, or Hole
   offset fields because there is an implication that the packet's
   sender had no knowledge of the correct width to use for these fields.
   Instead session negotiation MUST begin afresh.

   Bit 15 of the HOLETOFILL packet is only set when there are too many
   holes to fit within a single HOLETOFILL packet due to MTU
   limitations.  This causes the hole list to be spread out over
   multiple HOLETOFILL packets, each of which convey 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
   HOLETOFILL packet, and bit 15 will normally be clear.

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

Wood, et al.            Expires November 19, 2007              [Page 22]

Internet-Draft              Saratoga Protocol                   May 2007

   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 HOLETOFILL packet, given the IPv6 minimum MTU.  In
   some rare cases of high loss, there may be too many holes in the
   received data to convey within a single HOLETOFILL's size, due to
   trying to stay within the link MTU.  In this case, multiple
   HOLETOFILL packets may be generated, and Flag bit 15 should be set on
   each HOLETOFILL packet accordingly, to indicate that each packet
   holds partial results.

   A 'voluntary' HOLETOFILL 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 HOLETOFILL indicating a
   successfully established transfer has a Cumulative Acknowledgement of
   zero and an In-Response-To field of zero.

   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 HOLETOFILL" within this
   document), while any non-zero value means the transaction should be
   aborted (this is called a "failure HOLETOFILL").

Wood, et al.            Expires November 19, 2007              [Page 23]

Internet-Draft              Saratoga Protocol                   May 2007

   | 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 descriptors do not match expect use or file    |
   |             | length.                                             |

   The recipient of a failure HOLETOFILL 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.

4.  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.

Wood, et al.            Expires November 19, 2007              [Page 24]

Internet-Draft              Saratoga Protocol                   May 2007

   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)         /
   /                                                            ...


   | field      | description                                          |
   | Size       | the size of the file or directory in octets.         |
   | Mtime      | a timestamp from the operating system's record of    |
   |            | when the file or directory was modified.             |
   | Ctime      | the timestamp of the last status change for this     |
   |            | file or directory, according to the operating        |
   |            | system.                                              |
   | 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&quot.  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             |

Wood, et al.            Expires November 19, 2007              [Page 25]

Internet-Draft              Saratoga Protocol                   May 2007

                  | 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.

   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.

   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.  This should include all leapseconds.

5.  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.

5.1.  Saratoga Transactions

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

5.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

Wood, et al.            Expires November 19, 2007              [Page 26]

Internet-Draft              Saratoga Protocol                   May 2007

       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 HOLETOFILL packet containing
       an error code in the Status field is sent and the transaction is
       terminated.  This HOLETOFILL 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 HOLETOFILL packet MUST be sent
       with an error code of 0x00 and an In-Response-To field of zero.

   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
       HOLETOFILL 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 HOLETOFILL response from the file-
       receiver.  This can be followed by empty DATA packets with the
       Flags bit set requesting a HOLETOFILL until either a HOLETOFILL
       packet is received, or the inactivity timer expires.  All of the
       DATA packets MUST use field widths for the file 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 HOLETOFILL packet.  The file-receiver MAY voluntarily
       send HOLETOFILL packets at other times, where the In-Response-To
       field MUST set to zero.  The file-receiver SHOULD voluntarily
       send a HOLETOFILL 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 HOLETOFILL packet
       from the file-receiver, with a copy of this hole list.  File-
       receivers MUST send a HOLETOFILL packet immediately in response
       to receiving a DATA packet with the Flags bit set requesting a

   6.  If the file-sender receives a HOLETOFILL 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 HOLETOFILL
       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.

Wood, et al.            Expires November 19, 2007              [Page 27]

Internet-Draft              Saratoga Protocol                   May 2007

   7.  When the file-receiver has fully received the file data and the
       METADATA packet, then it sends a HOLETOFILL packet indicating
       that the transaction is complete, and it terminates the
       transaction locally, although it MUST persist in responding to
       DATA packets requesting HOLETOFILLs 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 HOLETOFILL 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 HOLETOFILLs, and also that a file-receiver
   should be cautious in gratuitously generating HOLETOFILL packets of
   its own volition.  On unidirectional links, a file-sender cannot
   reasonably expect to receive HOLETOFILL packets, so should never
   request them.

5.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 HOLETOFILL 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.

5.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.

Wood, et al.            Expires November 19, 2007              [Page 28]

Internet-Draft              Saratoga Protocol                   May 2007

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

5.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
   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 sends a voluntary (ie, not requested)
   success HOLETOFILL packet to the file-sender.  Otherwise, it sends a
   failure HOLETOFILL packet.  After sending a failure HOLETOFILL
   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 HOLETOFILL packet if the flow of packets does not stop.

5.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.

Wood, et al.            Expires November 19, 2007              [Page 29]

Internet-Draft              Saratoga Protocol                   May 2007

5.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 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.

   We expect that Saratoga instances will often work in conjunction with
   DTN bundle agents to fill the role of a convergence-layer adapter
   between bundle agents connected via point-to-point links.  Saratoga
   implementations designed to work this way should have a way of
   notifying bundle agents when they receive BEACONs from other nodes,
   and when transfers have completed.  In order for custody transfer to
   function properly, notifications between the Saratoga instances and
   bundle agents on both sides of a fully-successful bundle file
   transfer is required.

5.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

   Specifically, the inactivity timer is started on sending REQUEST or
   HOLETOFILL packets.  When sending packets not expected to elicit
   responses (BEACON, METADATA, or DATA without acknowledgement

Wood, et al.            Expires November 19, 2007              [Page 30]

Internet-Draft              Saratoga Protocol                   May 2007

   requests), there is no point to starting the local inactivity timer.

   For normal file (non-bundle 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 HOLETOFILL 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 HOLETOFILL 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.

   For bundle file transfers, the local bundle agent might be interacted
   with in order to perform a reactive fragmentation of the bundle whose
   transfer was interrupted by expiration of the inactivity timer.
   (Reactive fragmentation is discussed in [RFC4838].)  For custody
   transfer, there are some complications to making this reactive
   fragmentation work properly, and the details required to implement
   this functionality are left out of this specification until more
   experience with reactive fragmentation in general is obtained.

6.  Security Considerations

   Saratoga does not in itself provide any services for authentication
   of session requests or data, nor does it in itself provide any
   privacy or access control for data files transferred.  These issues
   may be addressed within an implementation or deployment in several
   ways that do not affect the file transfer protocol itself.  For
   instance, IPsec may be used to protect Saratoga implementations from
   forged packets, to provide privacy, or to authenticate the identity
   of a peer, for instance.  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.  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

   Security in DTNs is in general considered an open issue.  If a
   framework of techniques for handling security in DTN scenarios
   emerges, Saratoga might be adapted to conform to this.

Wood, et al.            Expires November 19, 2007              [Page 31]

Internet-Draft              Saratoga Protocol                   May 2007

7.  IANA Considerations

   Saratoga runs over UDP, so a single UDP port number allocation is
   needed.  Some implementations have used port 4000, but there is
   nothing special or binding about this value.

8.  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 for his review comments.

9.  A Note on Naming

   Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier
   sunk at Bikini Atoll and now a popular diving site.  The philosophy
   behind the protocol and its use described here can be summarized as
   Saratoga Carries Upper Bundles Adequately, or SCUBA.

10.  References

10.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.

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

10.2.  Informative References

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

Wood, et al.            Expires November 19, 2007              [Page 32]

Internet-Draft              Saratoga Protocol                   May 2007

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

              Scott, K. and S. Burleigh, "Bundle Protocol
              Specification", draft-irtf-dtnrg-bundle-spec-09 (work in
              progress), April 2007.

              Burleigh, S., "Licklider Transmission Protocol -
              Motivation", draft-irtf-dtnrg-ltp-motivation-04 (work in
              progress), April 2007.

              Jackson, C., "Saratoga File Transfer Protocol", SSTL
              Internal 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.

   [RFC4838]  Cerf, V., Burleigh, S., Hooke, A., Torgerson, L., Durst,
              R., Scott, K., Fall, K., and H. Weiss, "Delay-Tolerant
              Networking Architecture", RFC 4838, April 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.

   [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",
              submitted to the International Workshop on Satellite and
              Space Communications (IWSSC '07) for review,
              September 2007.

Wood, et al.            Expires November 19, 2007              [Page 33]

Internet-Draft              Saratoga Protocol                   May 2007

Authors' Addresses

   Lloyd Wood
   Cisco Systems
   11 New Square Park, Bedfont Lakes
   Feltham, Middlesex  TW14 8HA
   United Kingdom

   Phone: +44-20-8824-4236
   Email: lwood@cisco.com

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

   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

   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

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

Wood, et al.            Expires November 19, 2007              [Page 34]

Internet-Draft              Saratoga Protocol                   May 2007

   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 November 19, 2007              [Page 35]

Internet-Draft              Saratoga Protocol                   May 2007

Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at


   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).

Wood, et al.            Expires November 19, 2007              [Page 36]

Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/