Network Working Group L. Wood Internet-Draft Cisco Systems Intended status: Experimental J. McKim Expires: January 7, 2008 RSIS W. Eddy Verizon W. Ivancic NASA C. Jackson SSTL July 6, 2007 Saratoga: A Convergence Layer for Delay-Tolerant Networking draft-wood-dtnrg-saratoga-01 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- 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 January 7, 2008. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract Saratoga is a simple, lightweight UDP-based transport protocol Wood, et al. Expires January 7, 2008 [Page 1] Internet-Draft Saratoga Protocol July 2007 intended for use in moving files between immediately neighbouring peers which have sporadic, intermittent connectivity using dedicated IP links. Saratoga focuses on high link utilization for fast file transfers. Loss recovery is implemented via a simple ARQ mechanism. Saratoga is proposed for use as a convergence layer by Delay-Tolerant Networking for deep-space and ad-hoc networking scenarios. Saratoga is not intended for use over shared paths, so transport congestion control is unnecessary, although it could be optionally implemented at the sender to provide rate control of packet output. Saratoga is in continuous operational use by the IP-based Disaster Monitoring Constellation satellites in Low Earth Orbit (LEO) for mission-critical transfer of remote-sensing imagery. 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 2.3. Optional Parts of Saratoga . . . . . . . . . . . . . . . . 11 3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1. BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.2. REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.3. METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.5. HOLESTOFILL . . . . . . . . . . . . . . . . . . . . . . . 27 4. Directory Entry . . . . . . . . . . . . . . . . . . . . . . . 31 5. Behavior of a Saratoga Peer . . . . . . . . . . . . . . . . . 33 5.1. Saratoga Transactions . . . . . . . . . . . . . . . . . . 33 5.2. Beacons . . . . . . . . . . . . . . . . . . . . . . . . . 36 5.3. Upper-Layer Interface . . . . . . . . . . . . . . . . . . 37 5.4. Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 37 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 39 9. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 39 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40 10.1. Normative References . . . . . . . . . . . . . . . . . . . 40 10.2. Informative References . . . . . . . . . . . . . . . . . . 40 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 41 Intellectual Property and Copyright Statements . . . . . . . . . . 43 Wood, et al. Expires January 7, 2008 [Page 2] Internet-Draft Saratoga Protocol July 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 is also capable of streaming continuous content. Saratoga was originally designed for the purpose of file transfer from LEO imaging satellites to the ground, and has been implemented and used since 2004 to move mission imaging data from the Disaster Monitoring Constellation (DMC) remote-sensing satellites to ground stations. These satellites, built at the University of Surrey by Surrey Satellite Technology Ltd (SSTL), all use IP for payload communications and delivery of Earth imagery. Five DMC satellites have been launched into orbit; four are currently operational; three 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. 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]. Saratoga was originally designed 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. 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 across dedicated links without competition from other nodes, and loss is never due to Wood, et al. Expires January 7, 2008 [Page 3] Internet-Draft Saratoga Protocol July 2007 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 (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 the transport-level negative-acknowledgement approach to provide a 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 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 4GiB 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. 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 end- to-end 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. Both run over the User Datagram Protocol, UDP [RFC0768]. LTP can also permit some portion of trailing bytes of a blob to be transferred unreliably, while Saratoga can be used to transfer an entire file or bundle unreliably using Wood, et al. Expires January 7, 2008 [Page 4] Internet-Draft Saratoga Protocol July 2007 UDP-Lite [RFC3828]. 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 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. This specification uses 'file' as a shorthand for 'file or bundle'. 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/Bundle Transfer 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 peers. 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 Wood, et al. Expires January 7, 2008 [Page 5] Internet-Draft Saratoga Protocol July 2007 either a dedicated all-hosts multicast 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 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 HOLESTOFILL packet. The HOLESTOFILL packet lists which octets of the file have not yet been received and whether or not the METADATA packet was received. From this HOLESTOFILL packet, the file-sender begins a cycle of selective retransmission 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 and experiences loss of a single DATA packet due to channel-induced errors. Wood, et al. Expires January 7, 2008 [Page 6] Internet-Draft Saratoga Protocol July 2007 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. 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. 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. Figure 2 illustrates the sequence of packets in an example _put_ transaction where the second DATA packet is lost. Wood, et al. Expires January 7, 2008 [Page 7] Internet-Draft Saratoga Protocol July 2007 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. 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 of 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 January 7, 2008 [Page 8] Internet-Draft Saratoga Protocol July 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 filename 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 is 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 options: (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 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 that of the previous METADATA in order to re- establish the transfer. Otherwise, the file-receiver MUST assume Wood, et al. Expires January 7, 2008 [Page 9] Internet-Draft Saratoga Protocol July 2007 that the file has changed and purge the DATA received during the first contact. If a bundle contains separate parts that require unreliable and reliable transmission, proactive fragmentation can be used to split the bundle into separate reliable and unreliable bundles 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, 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. Like the BEACON packets, a _put_ or a response to a _get_ may be sent to a dedicated IPv4 all-hosts multicast address (the experimental 224.0.0.254 is used, pending an IANA assignment) or a dedicated IPv6 link-local multicast address (FF02:0:0:0:0:0:0:FE is used, pending an IANA assignment) for multiple file-receivers on the link to hear. This is at the discretion of the file-sender, if it believes 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 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. Wood, et al. Expires January 7, 2008 [Page 10] Internet-Draft Saratoga Protocol July 2007 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. 2.3. Optional Parts of Saratoga Implementing support for some parts of Saratoga is optional. These parts are: - bundle support. 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. - real-time streaming of content of unknown length, which requires some form of rate control at the sender. - including and recognising packet timestamps in DATA and HOLESTOFILL. 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. - any congestion control at the sender, based on feedback from acknowledgement HOLESTOFILL packets, or rate control limiting sender output. - multicast DATA transfers, if judged useful for the environment in which Saratoga is deployed. Wood, et al. Expires January 7, 2008 [Page 11] Internet-Draft Saratoga Protocol July 2007 3. 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 or bundles 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 January 7, 2008 [Page 12] Internet-Draft Saratoga Protocol July 2007 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 January 7, 2008 [Page 13] Internet-Draft Saratoga Protocol July 2007 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 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. 3.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 liveness or presence of the peer. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Bundle agent EID... // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// where Wood, et al. Expires January 7, 2008 [Page 14] Internet-Draft Saratoga Protocol July 2007 +--------+----------------------------------------------------------+ | 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 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. | +-------+-------+-------------------------+-------------------+ 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 descriptor size will be preferred to minimise problems with offset sequences wrapping. Wood, et al. Expires January 7, 2008 [Page 15] Internet-Draft Saratoga Protocol July 2007 +-----+-------+-----------------------------------------------------+ | 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 used to indicate whether the sender is capable of handling bundles via a local bundle agent. 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. +-----+-------+--------------------------------------+ | 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 continous streams. +--------+--------+-------------------------------------------------+ | Bit 12 | Bit 13 | Capability and willingness to send | | | | files/bundles | +--------+--------+-------------------------------------------------+ | 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 January 7, 2008 [Page 16] Internet-Draft Saratoga Protocol July 2007 +--------+--------+-------------------------------------------------+ | Bit 14 | Bit 15 | Capability and willingness to receive | | | | files/bundles | +--------+--------+-------------------------------------------------+ | 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 these to with bits indicating willingess. 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. 3.2. REQUEST A REQUEST packet is a command to perform either a _get_, _getdir_, or _delete_ transaction. Wood, et al. Expires January 7, 2008 [Page 17] Internet-Draft Saratoga Protocol July 2007 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / File Path ... / +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / | Directory Entry (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 Path | the path of the requested file/directory following | | | the rules described below. | | Directory | if the receiver already has the file at the expected | | Entry | file path and is requesting an update to that file, | | (optional) | this Directory Entry record information includes | | | known information about the file - length, | | | timestamp, etc. - to allow the file-sender to decide | | | whether an updated file needs to be sent. | +------------+------------------------------------------------------+ 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 January 7, 2008 [Page 18] Internet-Draft Saratoga Protocol July 2007 +-----+-------+-----------------------------------------------------+ | 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 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 REQUEST packet indicates that the File Path and File Record fields are 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 Wood, et al. Expires January 7, 2008 [Page 19] Internet-Draft Saratoga Protocol July 2007 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 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). REQUEST packets may be sent multicast, to learn about all listening nodes. A multicast _get_ request for a file that elicits multiple unicast 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. Delete requests are ignored for files currently being transferred. 3.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 January 7, 2008 [Page 20] Internet-Draft Saratoga Protocol July 2007 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | / / / / MD5 integrity checksum (128 bits) / / / / | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | / / single Directory Entry describing file / / (variable length) / / // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// where +-----------+-------------------------------------------------------+ | 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 | | Directory | describes file system information about the file, | | Entry | including length, timestamps, etc.; the format is | | | specified in Section 4 | +-----------+-------------------------------------------------------+ The first octet of the Flags field is fully 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 January 7, 2008 [Page 21] Internet-Draft Saratoga Protocol July 2007 +-----+-------+-----------------------------------------------------+ | Bit | Value | Meaning | +-----+-------+-----------------------------------------------------+ | 10 | 0 | This is a file. | | 10 | 1 | This file can be passed to a local bundle agent to | | | | be handled as a bundle. | +-----+-------+-----------------------------------------------------+ Bit 10 indicates whether a file or bundle is being transferred. +-----+-------+-----------------------+ | Bit | Value | Meaning | +-----+-------+-----------------------+ | 11 | 0 | This is not a stream. | | 11 | 1 | This is a stream. | +-----+-------+-----------------------+ Bit 11 indicates whether an indefinite-length stream is being transferred. +-----+-------+-----------------------------------------------------+ | 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. +-----+-------+-----------------------------+ | Bit | Value | Meaning | +-----+-------+-----------------------------+ | 13 | 0 | no MD5 checksum is present. | | 13 | 1 | MD5 checksum is present. | +-----+-------+-----------------------------+ Also inside the Flags field, bit 13 indicates the integrity checksum for the file to be transferred. If 0, no MD5 checksum is present, and higher-level end-to-end checks within the bundle must be relied upon. If 1, 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. 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 Wood, et al. Expires January 7, 2008 [Page 22] Internet-Draft Saratoga Protocol July 2007 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. +--------+--------+-------------------------------------------------+ | Bit 14 | Bit 15 | Bundles and records | +--------+--------+-------------------------------------------------+ | 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 | a stream is being sent. | +--------+--------+-------------------------------------------------+ Also inside the Flags field, bits 14 and 15 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 4. 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 16 | Use | +--------+----------------------------------------------------------+ | 0 | This file MUST be delivered reliably using UDP. | | 1 | This file MAY be delivered unreliably or partly | | | unreliably using UDP-Lite. | +--------+----------------------------------------------------------+ Bit 16 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 January 7, 2008 [Page 23] Internet-Draft Saratoga Protocol July 2007 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. 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 has, 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, the METADATA is used to initiate a transfer with following DATA packets to update the file. 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. 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 | bit 8 and 9 specify the size of offset descriptor, as | | and 9 | elsewhere. | | Flag 11 | bit 11 indicates that a stream is being carried. | | | Normally this bit will be zero for files/bundles. | | Flag 12 | bit 12 indicates that an optional timestamp is included | | | in the DATA header before the offset descriptor. | Wood, et al. Expires January 7, 2008 [Page 24] Internet-Draft Saratoga Protocol July 2007 | 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 is capable of handling UDP-Lite, and the file or bundle 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 here MUST be the same as indicated in the initial METADATA packet. +-----+-------+----------------------------+ | Bit | Value | Meaning | +-----+-------+----------------------------+ | 10 | 0 | A file is being carried. | | 10 | 1 | A bundle is being carried. | +-----+-------+----------------------------+ If bit 10 is set, a bundle is being carried for the local bundle agent. +-----+-------+---------------------------------+ | Bit | Value | Meaning | +-----+-------+---------------------------------+ | 11 | 0 | A file/bundle is being carried. | | 11 | 1 | A stream is being carried. | +-----+-------+---------------------------------+ Flag bit 11 indicates whether an open-ended indefinite-length stream is being transferred. Wood, et al. Expires January 7, 2008 [Page 25] Internet-Draft Saratoga Protocol July 2007 +-----+-------+-----------------------------------------------------+ | 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. +-----+-------+------------------------------------+ | 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 is never set if a stream is being transferred, or if multicast is in use. 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. Wood, et al. Expires January 7, 2008 [Page 26] Internet-Draft Saratoga Protocol July 2007 3.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. 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 January 7, 2008 [Page 27] Internet-Draft Saratoga Protocol July 2007 | 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 will 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. | | 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 timestamp is the length of the descriptor field. Wood, et al. Expires January 7, 2008 [Page 28] Internet-Draft Saratoga Protocol July 2007 +-----+-------+----------------------------------------+ | 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. | | 15 | 1 | This HOLESTOFILL is sent voluntarily. | +-----+-------+----------------------------------------------------+ Wood, et al. Expires January 7, 2008 [Page 29] Internet-Draft Saratoga Protocol July 2007 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. 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"). Wood, et al. Expires January 7, 2008 [Page 30] Internet-Draft Saratoga Protocol July 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 offset descriptors do not match expected use or | | | file length. | +------------+------------------------------------------------------+ 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. 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 January 7, 2008 [Page 31] Internet-Draft Saratoga Protocol July 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) / / ... // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// where +------------+------------------------------------------------------+ | 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 | +------------+------------------------------------------------------+ Wood, et al. Expires January 7, 2008 [Page 32] Internet-Draft Saratoga Protocol July 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. 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. 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. 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. 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. Wood, et al. Expires January 7, 2008 [Page 33] Internet-Draft Saratoga Protocol July 2007 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 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. 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- Wood, et al. Expires January 7, 2008 [Page 34] Internet-Draft Saratoga Protocol July 2007 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 its own volition. On unidirectional links, a file-sender cannot reasonably expect to receive HOLESTOFILL 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 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 Wood, et al. Expires January 7, 2008 [Page 35] Internet-Draft Saratoga Protocol July 2007 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. 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. 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 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. 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. Wood, et al. Expires January 7, 2008 [Page 36] Internet-Draft Saratoga Protocol July 2007 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. 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 Wood, et al. Expires January 7, 2008 [Page 37] Internet-Draft Saratoga Protocol July 2007 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 (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 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. 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. 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. 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 Wood, et al. Expires January 7, 2008 [Page 38] Internet-Draft Saratoga Protocol July 2007 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 implementation. 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. 7. 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 A dedicated IPv4 all-hosts multicast address and a dedicated IPv6 link-local multicast address will be requested from IANA. 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 Wood, et al. Expires January 7, 2008 [Page 39] Internet-Draft Saratoga Protocol July 2007 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. [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. 10.2. Informative References [Hogie05] Hogie, K., Criscuolo, E., and R. Parise, "Using Standard Internet Protocols and Applications in Space", Computer Networks Special Issue on Interplanetary Internet, vol. 47, no. 5, pp. 603-650, April 2005. [I-D.irtf-dtnrg-bundle-spec] Scott, K. and S. Burleigh, "Bundle Protocol Specification", draft-irtf-dtnrg-bundle-spec-10 (work in progress), July 2007. [I-D.irtf-dtnrg-ltp-motivation] Burleigh, S., "Licklider Transmission Protocol - Motivation", draft-irtf-dtnrg-ltp-motivation-04 (work in progress), April 2007. [Jackson04] 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 Wood, et al. Expires January 7, 2008 [Page 40] Internet-Draft Saratoga Protocol July 2007 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", to appear in the International Workshop on Satellite and Space Communications (IWSSC '07) Salzburg, September 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 USA Phone: +1-216-433-6536 Email: James.H.McKim@grc.nasa.gov Wood, et al. Expires January 7, 2008 [Page 41] Internet-Draft Saratoga Protocol July 2007 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 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 January 7, 2008 [Page 42] Internet-Draft Saratoga Protocol July 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 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 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 http://www.ietf.org/ipr. 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 ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Wood, et al. Expires January 7, 2008 [Page 43]