idnits 2.17.1 draft-wood-tsvwg-saratoga-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with multicast IPv4 addresses in the document. If these are generic example addresses, they should be changed to use the 233.252.0.x range defined in RFC 5771 == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 12, 2009) is 5462 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3309 (Obsoleted by RFC 4960) == Outdated reference: A later version (-09) exists of draft-wood-dtnrg-http-dtn-delivery-03 == Outdated reference: A later version (-14) exists of draft-wood-dtnrg-saratoga-05 Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Wood 3 Internet-Draft Cisco Systems 4 Intended status: Experimental J. McKim 5 Expires: November 13, 2009 RSIS 6 W. Eddy 7 Verizon 8 W. Ivancic 9 NASA 10 C. Jackson 11 SSTL 12 May 12, 2009 14 Saratoga: A Scalable File Transfer Protocol 15 draft-wood-tsvwg-saratoga-03 17 Status of this Memo 19 This Internet-Draft is submitted to IETF in full conformance with the 20 provisions of BCP 78 and BCP 79. This document may not be modified, 21 and derivative works of it may not be created, except to format it 22 for publication as an RFC and to translate it into languages other 23 than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on November 13, 2009. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This document specifies the Saratoga transfer protocol. Saratoga was 57 originally developed to efficiently transfer remote-sensing imagery 58 from a low-Earth-orbiting satellite constellation, but is useful for 59 many other scenarios, including ad-hoc peer-to-peer communications, 60 delay-tolerant networking, and grid computing. Saratoga is a simple, 61 lightweight, content dissemination protocol that builds on UDP, and 62 optionally uses UDP-Lite. Saratoga is intended for use when moving 63 files or streaming data between peers which may have only sporadic or 64 intermittent connectivity, and is capable of transferring very large 65 amounts of data reliably under adverse conditions. The Saratoga 66 protocol is designed to cope with highly asymmetric link or path 67 capacity between peers, and can support fully-unidirectional data 68 transfer if required. In scenarios with dedicated links, Saratoga 69 focuses on high link utilization to make the most of limited 70 connectivity times, while standard congestion control mechanisms can 71 be implemented for operation over shared links. Loss recovery is 72 implemented via a simple negative-ack ARQ mechanism. The protocol 73 specified in this document is considered to be appropriate for 74 experimental use on private IP networks. 76 Table of Contents 78 1. Background and Introduction . . . . . . . . . . . . . . . . . 4 79 2. Overview of Saratoga File Transfer . . . . . . . . . . . . . . 6 80 3. Optional Parts of Saratoga . . . . . . . . . . . . . . . . . . 11 81 4. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 4.1. BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 4.2. REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 4.3. METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 86 4.5. HOLESTOFILL . . . . . . . . . . . . . . . . . . . . . . . 27 87 5. The Directory Entry . . . . . . . . . . . . . . . . . . . . . 32 88 6. Behavior of a Saratoga Peer . . . . . . . . . . . . . . . . . 35 89 6.1. Saratoga Transactions . . . . . . . . . . . . . . . . . . 35 90 6.2. Beacons . . . . . . . . . . . . . . . . . . . . . . . . . 38 91 6.3. Upper-Layer Interface . . . . . . . . . . . . . . . . . . 38 92 6.4. Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 38 93 7. Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . 39 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 39 95 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 96 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 40 97 11. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 41 98 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 99 12.1. Normative References . . . . . . . . . . . . . . . . . . . 41 100 12.2. Informative References . . . . . . . . . . . . . . . . . . 41 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42 103 1. Background and Introduction 105 Saratoga is a file transfer and content dissemination protocol 106 capable of efficiently sending both small and very large files as 107 well as streaming continuous content. Saratoga was originally 108 designed for the purpose of large file transfer from small low-Earth- 109 orbit satellites. It has been used in daily operations since 2004 to 110 move mission imaging data files on the order of several hundred 111 megabytes from the Disaster Monitoring Constellation (DMC) remote- 112 sensing satellites to ground stations. 114 The DMC satellites, built at the University of Surrey by Surrey 115 Satellite Technology Ltd (SSTL), all use IP for payload 116 communications and delivery of Earth imagery. At the time of this 117 writing in September 2007, five DMC satellites have been launched 118 into orbit; four are currently operational; and three further DMC 119 satellites are under construction. The DMC satellites use Saratoga 120 to provide imagery under the aegis of the International Charter on 121 Space and Major Disasters. A pass of connectivity between a 122 satellite and ground station offers an 8-12 minute time window in 123 which to transfer these files using a minimum of an 8.1 Mbps downlink 124 and a 9.6 kbps uplink. The newer DMC satellites have faster 125 downlinks, with some capable of 40 Mbps, and others planned to 126 provide upwards of 200 Mbps, without significant increases in uplink 127 rates. This high degree of asymmetry and need to fully utilize the 128 downlink to move the volume of data required within the limited time 129 available motivates much of Saratoga's design. 131 Further details on how these DMC satellites use IP to communicate 132 with the ground and the terrestrial Internet are discussed in other 133 documents [Hogie05][Wood07a][Wood07b]. 135 Store-and-forward delivery relies on reliable hop-by-hop transfers of 136 files, removing the need for the final receiver to talk to the 137 original sender across long delays and allowing for the possibility 138 that an end-to-end path may never exist between sender and receiver 139 at any given time. Use of store-and-forward hop-by-hop delivery is 140 typical of scenarios in space exploration for both near-Earth and 141 deep-space missions, and useful for other scenarios, such as 142 underwater networking, ad-hoc sensor networks, and some message- 143 ferrying relay scenarios. Saratoga is intended to be useful for 144 relaying data in these scenarios and can also be used to carry the 145 Bundle Protocol "bundles" proposed for use in Delay and Disruption- 146 Tolerant Networking (DTN) by the IRTF DTN Research Group [RFC5050]. 147 How Saratoga can optionally function as a "bundle convergence layer" 148 alongside a DTN bundle agent is specified in a companion document 149 [I-D.wood-dtnrg-saratoga]. 151 High link utilization is important during periods of limited 152 connectivity. Given that Saratoga was originally developed for 153 scheduled peer-to-peer communications over dedicated links in private 154 networks where each application has the entire link for the duration 155 of its transfer, early Saratoga implementations deliberately lack any 156 form of congestion control and send at line rate. Newer 157 implementations may perform TCP-Friendly Rate Control (TFRC) or other 158 congestion control mechanisms, if appropriate for the environment and 159 where simultaneous sharing of capacity with other traffic and 160 applications is required. 162 Saratoga contains a Selective Negative Acknowledgement (SNACK) 163 mechanism to provide reliable retransmission of data. This was 164 intended to correct losses of corrupted link-layer frames due to 165 channel noise over a space link. Packet losses in the DMC are due to 166 corruption introducing non-recoverable errors in the frame. The DMC 167 design uses point-to-point links and scheduling of applications so 168 that the link is dedicated to one application transfer at a time, 169 meaning that packet loss can not be due to congestion as applications 170 compete for link capacity. In other wireless environments that may 171 be shared by many nodes and applications, allocation of channel 172 resources to nodes becomes a MAC-layer function. Forward Error 173 Coding (FEC) to get the most reliable transmission through a channel 174 is best left near the physical layer so that it can be tailored for 175 the channel. Use of FEC complements Saratoga's transport-level 176 negative-acknowledgement approach to provide a reliable ARQ mechanism 177 [RFC3366]. 179 Saratoga is scalable in that it is capable of efficiently 180 transferring small or large files, by choosing a width of file offset 181 descriptor appropriate for the filesize, and advertising accepted 182 offset descriptor sizes. 16-bit, 32-bit, 64-bit and 128-bit 183 descriptors can be selected, for maximum file sizes of 64KiB-1, 184 4GiB-1, 2^64-1 and 2^128-1 octets. Earth imaging files currently 185 transferred by Saratoga are mostly up to a few gigabytes in size. 186 Some implementations do transfer more than 4 GiB in size, and so 187 require offset descriptors larger than 32 bits. We expect that a 188 128-bit descriptor will satisfy all future needs, but we expect 189 current implementations to only support up to 32-bit or 64-bit 190 descriptors, depending on their application needs. The 16-bit 191 descriptor is useful for small messages, including messages from 192 8-bit devices, and is always supported. The 128-bit descriptor is 193 useful for moving very large files stored on a 128-bit filesystem, 194 such as on OpenSolaris ZFS. 196 Saratoga can be used with either IPv4 or IPv6. Compatibility between 197 Saratoga and the wide variety of links that can already carry IP 198 traffic is assured. 200 Saratoga was originally implemented as outlined in [Jackson04], but 201 the specification given here differs substantially, as we have added 202 a number of features, while cleaning up the initial Saratoga 203 specification. The original Saratoga code uses a version number of 204 0, while code that implements this version of the protocol advertises 205 a version number of 1. Further discussion of the history and 206 development of Saratoga is given in [Wood07b]. 208 This document contains an overview of the transfer process and 209 transactions using Saratoga in Section 2, followed by a formal 210 definition of the packet types used by Saratoga in Section 4, and the 211 details of the various protocol mechanisms in Section 6. 213 Here, Saratoga transaction types are labelled with underscores around 214 lowercase names (such as a "_get_" transaction), while Saratoga 215 packet types are labelled in all capitals (such as a "REQUEST" 216 packet) in order to distinguish between the two. 218 The remainder of this specification uses 'file' as a shorthand for 219 'binary object', which may be a DTN bundle, or other type of data. 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 223 document are to be interpreted as described in RFC 2119. [RFC2119] 225 2. Overview of Saratoga File Transfer 227 Saratoga is a peer-to-peer protocol in the sense that multiple files 228 may be transferred in both directions simultaneously between two 229 communicating Saratoga peers, and there is not intended to be a 230 strict client-to-server relationship. 232 Saratoga nodes are simple file servers. Saratoga supports several 233 types of operations on files including "pull" downloads, "push" 234 uploads, directory listing, and deletion requests. Each operation is 235 handled as a distinct "transaction" between the peers. 237 Saratoga nodes MAY advertise their presence, capabilities, and 238 desires by sending BEACON packets. These BEACONs are sent to either 239 a reserved, unforwardable, multicast address when using IPv4, or a 240 link-local all-Saratoga-peers multicast address when using IPv6. A 241 BEACON might also be unicast to another known node as a sort of 242 "keepalive". Saratoga nodes may dynamically discover other Saratoga 243 nodes either through listening for BEACONs, through pre- 244 configuration, or via some other trigger from a user, lower-layer 245 protocol, or another process. The BEACON is simply useful in low- 246 delay ad-hoc networking or as explicit confirmation that another node 247 is present; it is not required in order to begin a Saratoga 248 transaction. BEACONs have been used by the DMC satellites to 249 indicate to ground stations that a link has become functional, a 250 solid-state data recorder is online, and the software is ready to 251 transfer any requested files. 253 A Saratoga transaction begins with either a _get_, _put_, _getdir_, 254 or _delete_ transaction REQUEST packet corresponding to a desired 255 download, upload, directory listing, or deletion operation. The most 256 common envisioned transaction is the _get_, which begins with a 257 single Saratoga REQUEST packet sent from the peer wishing to receive 258 the file, to the peer who currently has the file. If the transaction 259 is rejected, then a brief METADATA packet that conveys rejection is 260 generated. If the file-serving peer accepts the transaction, it 261 generates and sends a more useful descriptive METADATA packet, 262 followed by some number of DATA packets constituting the requested 263 file. 265 These DATA packets are finished by (and can intermittently include) a 266 DATA packet with a flag bit set that demands the file-receiver send a 267 reception report in the form of a HOLESTOFILL packet. The 268 HOLESTOFILL packet is a Selective Negative Acknowledgement listing 269 spans of octets within the file that have not yet been received as 270 well as whether or not the METADATA packet was received. From this 271 HOLESTOFILL packet, the file-sender begins a cycle of selective 272 retransmissions of DATA packets, until it sees a HOLESTOFILL packet 273 that acknowledges total reception of all file data. 275 In the example scenario in Figure 1, a _get_ request is granted. The 276 reliable file delivery experiences loss of a single DATA packet due 277 to channel-induced errors. 279 File-Receiver File-Sender 281 REQUEST ---------------------> 282 (transfer accepted) <--------- METADATA 283 HOLESTOFILL -----------------> (voluntarily sent at start) 284 <------------------------- DATA #1 285 (lost) <------ DATA #2 286 <------------------------- DATA #3 (bit set 287 requesting HOLESTOFILL) 288 HOLESTOFILL -----------------> 289 (indicating that range in DATA #2 was lost) 290 <------------------------- DATA #2 (bit set 291 requesting HOLESTOFILL) 292 HOLESTOFILL -----------------> 293 (complete file and METADATA received) 294 Figure 1: Example _get_ transaction sequence 296 A _getdir_ request proceeds similarly, though the DATA packets 297 contain the contents of a directory listing, described later, rather 298 than a given file's bytes. 300 The HOLESTOFILL and DATA packets are allowed to be sent at any time 301 within the scope of a transaction in order for the file-sending node 302 to optimize buffer management and transmission order. For example, 303 if the file-receiver already has the first half of a file from a 304 previous disrupted transfer, it may send a HOLESTOFILL at the 305 beginning of the transaction indicating that it has the first half of 306 the file, and so only needs the last half of the file. Thus, 307 efficient recovery from interrupted sessions between peers becomes 308 possible, similar to ranged FTP and HTTP requests. 310 In deep-space scenarios, the large propagation delays and round-trip 311 times involved prohibit ping-pong packet exchanges for starting 312 transactions. The Saratoga _put_ transaction is useful in such 313 cases. A _put_ is initiated by the file-sender sending a METADATA 314 packet followed by immediate DATA packets. This is highly desirable 315 in long-propagation deep-space (and similar) scenarios, without first 316 waiting for a HOLESTOFILL. This can be considered an "optimistic" 317 mode of protocol operation, as it assumes the transaction request 318 will be granted. If the sender of a PUT request sees a METADATA 319 packet indicating that the request was declined, it MUST stop sending 320 any DATA packets within that transaction immediately. Since this 321 type of _put_ is open-loop for some period of time, it should not be 322 used in scenarios where congestion is a valid concern; in these 323 cases, the file-sender should wait on its METADATA to be acknowledged 324 by a HOLESTOFILL before sending DATA packets within the transaction. 326 Figure 2 illustrates the sequence of packets in an example _put_ 327 transaction where the second DATA packet is lost. Other than the way 328 that it is initiated, a _put_ transaction is identical to a _get_ 329 transaction. 331 File-Sender File-Receiver 333 METADATA ----------------> 334 (transfer accepted) <---------- HOLESTOFILL 335 DATA #1 ----------------> 336 DATA #2 ---> (lost) 337 DATA #3 (bit set ------------> 338 requesting HOLESTOFILL) 339 (DATA #2 lost) <------------- HOLESTOFILL 340 DATA #2 (bit set -----------> 341 requesting HOLESTOFILL) 342 (transfer complete) <---------- HOLESTOFILL 344 Figure 2: Example PUT transaction sequence 346 The _delete_ transactions are simple single packet requests that 347 trigger a HOLESTOFILL packet with a status code that indicates 348 whether the file was deleted or not. If the file is not able to be 349 deleted for some reason, this reason can be conveyed in the Status 350 field of the HOLESTOFILL packet. 352 A _get_ REQUEST packet that does not specify a filename (i.e. the 353 request contains a zero-length File Path field) is specially defined 354 to be a request for any chosen file that the peer wishes to send it. 355 This allows a Saratoga peer to blindly request any files that the 356 other Saratoga peer has ready for it, without prior knowledge of the 357 directory listing, and without requiring the ability to examine files 358 or decode remote file names/paths for meaningful information such as 359 final destination. 361 If a file is larger than Saratoga can be expected to transfer during 362 a time-limited contact, there are at least two feasible options: 364 (1) The application can use proactive fragmentation to create 365 multiple smaller-sized files. Saratoga can transfer some number of 366 these smaller files fully during a contact. 368 (2) To avoid file fragmentation, a Saratoga file-receiver can retain 369 a partially-transferred file and request transfer of the unreceived 370 bytes during a later contact. This uses a HOLESTOFILL packet to make 371 clear how much of the file has been successfully received and where 372 transfer should be resumed from. On resumption, the new METADATA 373 (including file length, timestamps, and possibly MD5 sum) MUST match 374 that of the previous METADATA in order to re-establish the transfer. 375 Otherwise, the file-receiver MUST assume that the file has changed 376 and purge the DATA received during the first contact. 378 If a file contains separate parts that require reliable transmission 379 without errors or that can tolerate errors in delivered content, 380 proactive fragmentation can be used to split the file into separate 381 reliable and unreliable files that can be transferred separately, 382 using UDP or UDP-Lite. 384 If parts of a file require reliability but the rest can be sent by 385 unreliable transfer, the file-sender can use its knowledge of the 386 internal file structure and vary DATA packet size so that the 387 reliable parts always start after the offset field and are covered by 388 the UDP-Lite checksum. 390 A file that permits unreliable delivery may be transferred onwards 391 using UDP, although the METADATA flag indicating that unreliable 392 transmission is permitted is retained for later hops, which may 393 revert to using UDP-Lite. If the current sender does not understand 394 the internal file format to be able to decide what parts must be 395 protected, the current sender or receiver does not support UDP-Lite, 396 or the current protocol stack only implements error-free frame 397 delivery below the UDP layer, then the file may be delivered using 398 UDP. 400 Like the BEACON packets, a _put_ or a response to a _get_ may be sent 401 to the dedicated IPv4 Saratoga multicast address (allocated to 402 224.0.0.108) or the dedicated IPv6 link-local multicast address 403 (allocated to FF02:0:0:0:0:0:0:6C) for multiple file-receivers on the 404 link to hear. This is at the discretion of the file-sender, if it 405 believes that there is interest from multiple receivers. In-progress 406 DATA transfers may also be moved seamlessly from unicast to multicast 407 if the file-sender learns during a transfer, from receipt of further 408 unicast _get_ REQUEST packets, that multiple nodes are interested in 409 the file. The associated METADATA packet is multicast when this 410 transition takes place, and is then repeated periodically while the 411 DATA stream is being sent, to inform newly-arrived listeners about 412 the file being multicast. Acknowledgements MUST NOT be demanded by 413 multicast DATA packets, to prevent ack implosion at the file-sender, 414 and instead holestofill information is aggregated and sent 415 voluntarily by all file-receivers. File-receivers respond to 416 multicast DATA with multicast HOLESTOFILL packets. File-receivers 417 should introduce a short random delay before sending a HOLESTOFILL 418 packet, to prevent ack implosion after a channel-induced loss, and 419 must listen for HOLESTOFILL packets from others, to avoid duplicating 420 fill requests. The file-sender SHOULD repeat any initial unicast 421 portion of the transfer as multicast last of all, and may repeat and 422 cycle through multicast of the file several times while file- 423 receivers express interest via HOLESTOFILL or _get_ packets. Once in 424 multicast and with METADATA being repeated periodically, new file- 425 receivers do not need to send individual REQUEST packets. If a 426 transfer has been started using UDP-Lite and new receivers indicate 427 UDP-only capability, multicast transfers MUST switch to using UDP to 428 accommodate them. 430 3. Optional Parts of Saratoga 432 Implementing support for some parts of Saratoga is optional. These 433 parts are: 435 - sending and parsing BEACONs 437 - support for working with DTN bundles and a bundle agent as an 438 application driving Saratoga. Use of a filesystem is expected. 440 - transfers permitting some errors in content delivered, using UDP- 441 Lite. These can be useful for decreasing delivery time over 442 unreliable channels, especially for unidirectional links - but 443 requires that lower-layer frames permit delivery of unreliable data. 445 - streaming data, including real-time streaming of content of unknown 446 length. This streaming can be unreliable (without resend requests) 447 or reliable (with resend requests). Session protocols such as http 448 expect reliable streaming, and can be used in delay-tolerant networks 449 [I-D.wood-dtnrg-http-dtn-delivery]. Although Saratoga data delivery 450 is inherently one-way, where a stream of DATA packets elicits a 451 stream of HOLESTOFILL packets, bidirectional duplex communication can 452 be established by using two Saratoga transfers flowing in opposite 453 directions. 455 - sending and responding to packet timestamps in DATA and HOLESTOFILL 456 packets. These timestamps are useful for streaming and for giving a 457 file-sender an indication of path latency for rate control. There is 458 no need for a file-receiver to understand the format used for these 459 timestamps for it to be able to receive and reflect them. 461 - performing congestion control at the sender, based on feedback from 462 acknowledgement HOLESTOFILL packets, or simple open-loop rate control 464 - multicast DATA transfers, if judged useful for the environment in 465 which Saratoga is deployed. 467 4. Packet Types 469 Saratoga is defined for use with UDP over either IPv4 or IPv6 470 [RFC0768]. UDP checksums, which are mandatory with IPv6, MUST be 471 used with IPv4. Within either version of IP datagram, a Saratoga 472 packet appears as a typical UDP header followed by an octet 473 indicating how the remainder of the packet is to be interpreted: 475 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 476 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 477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 478 | UDP source port | UDP destination port | 479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 480 | UDP length | UDP checksum | 481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 482 |Ver|Packet Type| other Saratoga fields ... // 483 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 485 Saratoga data transfers can also be carried out using UDP-Lite 486 [RFC3828]. If Saratoga can be carried over UDP-Lite, the 487 implementation MUST also support UDP. All packet types except DATA 488 MUST be sent using UDP with checksums turned on. For reliable 489 transfers, DATA packets are sent using UDP with checksums turned on. 490 For files where unreliable transfer has been indicated as desired and 491 possible, the sender MAY send DATA packets unreliably over UDP-Lite, 492 where UDP-Lite protects only the Saratoga headers and parts of the 493 file that must be transmitted reliably. 495 The two-bit Saratoga version field ("Ver") identifies the version of 496 the Saratoga protocol that the packet conforms to. The value 01 497 should be used in this field for implementations conforming to the 498 specification in this document, which specifies version 1 of 499 Saratoga. The value 00 was used in earlier implementations, prior to 500 the formal specification and public submission of the protocol 501 design, and is incompatible with version 01 in several respects. 503 The six-bit Saratoga "Packet Type" field indicates how the remainder 504 of the packet is intended to be decoded and processed: 506 +---+-------------+-------------------------------------------+ 507 | # | Type | Use | 508 +---+-------------+-------------------------------------------+ 509 | 0 | BEACON | Beacon packet indicating peer status | 510 | 1 | REQUEST | Commands peer to start a transfer | 511 | 2 | METADATA | Carries file transfer metadata | 512 | 3 | DATA | Carries octets of file data | 513 | 4 | HOLESTOFILL | Signals list of unreceived data to sender | 514 +---+-------------+-------------------------------------------+ 516 Several of these packet types include a Flags field, for which only 517 some of the bits have defined meanings and usages in this document. 518 Other, undefined, bits may be reserved for future use. Following the 519 principle of being conservative in what you send and liberal in what 520 you accept, a packet sender MUST set any undefined bits to zero, and 521 a packet recipient MUST NOT rely on these undefined bits being zero 522 on reception. 524 The specific formats for the different types of packets are given in 525 this section. Some packet types contain file offset descriptor 526 fields, which contain unsigned integers. The lengths of the offset 527 descriptors are fixed within a transfer, but vary between file 528 transfers. The size is set for each particular transfer, depending 529 on the choice of offset descriptor width made in the METADATA packet, 530 which in turn depends on the size of file being transferred. 532 In this document, all of the packet structure figures illustrating a 533 packet format assume 32-bit lengths for these offset descriptor 534 fields, and indicate the transfer-dependent length of the fields by 535 using a "(descriptor)" designation within the [field] in all packet 536 diagrams. That is: 538 The example 32-bit descriptors shown in all diagrams here 540 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 541 [ (descriptor) ] 542 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 544 are suitable for files of up to 4GiB - 1 octets in length, and may be 545 replaced in a file transfer by descriptors using a different length, 546 depending on the size of file to be transferred: 548 128-bit descriptor for very long files (optional) 550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 551 [ (descriptor) / 552 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 553 / (descriptor, continued) / 554 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 555 / (descriptor, continued) / 556 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 557 / (descriptor, continued) ] 558 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 560 64-bit descriptor for longer files (optional) 562 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 563 [ (descriptor) / 564 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 565 / (descriptor, continued) ] 566 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 567 16-bit descriptor for short files (MUST be supported) 569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 570 [ (descriptor) ] 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 573 For offset descriptors and types of content being transferred, the 574 related flag bits in BEACON and REQUEST indicate capabilities, while 575 in METADATA and DATA those flag bits are used slightly differently, 576 to indicate the content being transferred. 578 Saratoga packets are intended to fit within link MTUs to avoid the 579 inefficiencies and overheads of lower-layer fragmentation. A 580 Saratoga implementation itself does not perform any form of MTU 581 discovery, but is assumed to be configured with knowledge of usable 582 maximum IP MTUs for the link interfaces it uses. 584 4.1. BEACON 586 BEACON packets may be multicast periodically by nodes willing to act 587 as Saratoga peers. Some implementations have done so every 100 588 milliseconds, but this rate is arbitrary, and should be chosen to be 589 appropriate for the environment and implementation. 591 The main purpose for sending BEACONs is to announce the presence of 592 the node to potential peers (e.g. satellites, ground stations) to 593 provide automatic service discovery, and also to confirm the activity 594 or presence of the peer. 596 The Endpoint Identifier (EID) in the BEACON serves to uniquely 597 identify the Saratoga peer. Whenever the Saratoga peer begins using 598 a new IP address, it SHOULD issue a BEACON on it and repeat the 599 BEACON periodically, to enable listeners to associate the IP address 600 with the EID and the peer. 602 Format 604 0 1 2 3 605 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 606 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 607 |0 1| Type | Flags | 608 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 609 | Endpoint identifier... // 610 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 612 where 613 +------------+------------------------------------------------------+ 614 | Field | Description | 615 +------------+------------------------------------------------------+ 616 | Type | 0 | 617 | Flags | convey whether or not the peer is ready to | 618 | | send/receive and what the maximum supported file | 619 | | size range and descriptor is. | 620 | Endpoint | This can be used to uniquely identify the sending | 621 | identifier | Saratoga peer, or the administrative node that the | 622 | | BEACON-sender is associated with. If Saratoga is | 623 | | being used with a bundle agent, a bundle endpoint ID | 624 | | (EID) can be used here. | 625 +------------+------------------------------------------------------+ 627 The Flags field is used to provide some additional information about 628 the peer. The first octet of the Flags field is currently in use. 629 The later two octets are for future use, and MUST be set to zero. 631 The two highest-order bits (bits 8 and 9 above) indicate the maximum 632 supported file size parameters that the peer's Saratoga 633 implementation permits. Other Saratoga packet types contain 634 variable-length fields that convey file sizes or offsets into a file 635 -- the file offset descriptors. These descriptors may be 16-bit, 32- 636 bit, 64-bit, or 128-bit in length, depending on the size of the file 637 being transferred and/or the integer types supported by the sending 638 peer. The indicated bounds for the possible values of these bits are 639 summarized below: 641 +-------+-------+-------------------------+-------------------+ 642 | Bit 8 | Bit 9 | Supported Field Sizes | Maximum File Size | 643 +-------+-------+-------------------------+-------------------+ 644 | 0 | 0 | 16 bits | 2^16 - 1 octets. | 645 | 0 | 1 | 16 or 32 bits | 2^32 - 1 octets. | 646 | 1 | 0 | 16, 32, or 64 bits | 2^64 - 1 octets. | 647 | 1 | 1 | 16, 32, 64, or 128 bits | 2^128 - 1 octets. | 648 +-------+-------+-------------------------+-------------------+ 650 If a Saratoga peer advertises it is capable of receiving a certain 651 size of file, then it MUST also be capable of receiving files sent 652 using smaller descriptor values. This avoids overhead on small 653 files, while increasing interoperability between peers. 655 It is likely when sending unbounded streams that a larger offset 656 descriptor field size will be preferred to minimise problems with 657 offset sequences wrapping. Protecting against sequence wrapping is 658 discussed in the HOLESTOFILL section. 660 +-----+-------+-----------------------------------------------------+ 661 | Bit | Value | Meaning | 662 +-----+-------+-----------------------------------------------------+ 663 | 10 | 0 | not able to pass bundles to a local bundle agent; | 664 | | | handles files. | 665 | 10 | 1 | can pass marked bundles to a local bundle agent. | 666 +-----+-------+-----------------------------------------------------+ 668 Bit 10 is reserved for DTN bundle agent use, indicating whether the 669 sender is capable of handling bundles via a local bundle agent. This 670 is described in [I-D.wood-dtnrg-saratoga]. 672 Any type of host identifier can be used in the endpoint identifier 673 field, as long as it is a reasonably unique string within the range 674 of operational deployment. This field encompasses the remainder of 675 the packet, and might contain non-UTF-8 and/or null characters. 677 +-----+-------+--------------------------------------+ 678 | Bit | Value | Meaning | 679 +-----+-------+--------------------------------------+ 680 | 11 | 0 | not capable of supporting streaming. | 681 | 11 | 1 | capable of supporting streaming. | 682 +-----+-------+--------------------------------------+ 684 Bit 11 is used to indicate whether the sender is capable of sending 685 and receiving continuous streams. 687 +--------+--------+------------------------------------------------+ 688 | Bit 12 | Bit 13 | Capability and willingness to send files | 689 +--------+--------+------------------------------------------------+ 690 | 0 | 0 | cannot send files at all. | 691 | 0 | 1 | invalid. | 692 | 1 | 0 | capable of sending, but not willing right now. | 693 | 1 | 1 | capable of and willing to send files. | 694 +--------+--------+------------------------------------------------+ 696 +--------+--------+-------------------------------------------------+ 697 | Bit 14 | Bit 15 | Capability and willingness to receive files | 698 +--------+--------+-------------------------------------------------+ 699 | 0 | 0 | cannot receive files at all. | 700 | 0 | 1 | invalid. | 701 | 1 | 0 | capable of receiving, but will reject METADATA. | 702 | 1 | 1 | capable of and willing to receive files. | 703 +--------+--------+-------------------------------------------------+ 705 Also in the Flags field, bits 12 and 14 act as capability bits, while 706 bits 13 and 15 augment those flags with bits indicating current 707 willingness to use the capability. 709 Bits 12 and 13 deal with sending, while bits 14 and 15 deal with 710 receiving. If bit 12 is set, then the peer has the capability to 711 send files. If bit 14 is set, then the peer has the capability to 712 receive files. Bits 13 and 15 indicate willingness to send and 713 receive files, respectively. 715 A peer that is able to act as a file-sender MUST set the capability 716 bit 12 in all BEACONs that it sends, regardless of whether it is 717 willing to send any particular files to a particular peer at a 718 particular time. Bit 13 indicates the current presence of data to 719 send and a willingness to send it in general, in order to augment the 720 capability advertised by bit 12. 722 If bit 14 is set, then the peer is capable of acting as a receiver, 723 although it still might not currently be ready or willing to receive 724 files (for instance, it may be low on free storage). This bit MUST 725 be set in any BEACON packets sent by nodes capable of acting as file- 726 receivers. Bit 15 augments this by expresses a current general 727 willingness to receive and accept files. 729 +-----+-------+-----------------------------------------------------+ 730 | Bit | Value | Meaning | 731 +-----+-------+-----------------------------------------------------+ 732 | 16 | 0 | supports DATA transfers over UDP only. | 733 | 16 | 1 | supports DATA transfers over both UDP and UDP-Lite. | 734 +-----+-------+-----------------------------------------------------+ 736 Bit 16 is used to indicate whether the sender is capable of sending 737 and receiving unreliable transfers via UDP-Lite. 739 4.2. REQUEST 741 A REQUEST packet is a command to perform either a _get_, _getdir_, or 742 _delete_ transaction. 744 Format 746 0 1 2 3 747 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 748 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 749 |0 1| Type | Flags | 750 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 751 | Id | 752 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 753 | variable-length File Path ... / 754 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 755 / / 756 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 757 / | null byte | / 758 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 759 / variable-length Authentication Field (optional) | 760 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 762 where 764 +--------+----------------------------------------------------------+ 765 | Field | Description | 766 +--------+----------------------------------------------------------+ 767 | Type | 1 | 768 | Flags | provide additional information about the requested | 769 | | file/operation; see table below for definition. | 770 | Id | uniquely identifies the transaction between two peers. | 771 | File | the path of the requested file/directory following the | 772 | Path | rules described below. | 773 +--------+----------------------------------------------------------+ 775 The Id that is used during transactions serves to uniquely associate 776 a given packet with a particular transaction. This enables multiple 777 simultaneous data transfer transactions between two peers, with each 778 peer deciding how to multiplex and prioritise the parallel flows it 779 sends. The Id for a transaction is selected by the initiator so as 780 to not conflict with any other in-progress or recent transactions 781 with the same host. This Id should be unique and generated using 782 properties of the file, which will remain constant across a host 783 reboot. The 3-tuple of both host identifiers and a carefully- 784 generated transaction Id field can be used to uniquely index a 785 particular transaction's state. 787 In the Flags field, the bits labelled 8 and 9 in the figure above 788 indicate the maximum supported file length fields that the peer can 789 handle, and are interpreted exactly as the bits 8 and 9 in the BEACON 790 packet described above. The remaining defined bits are: 792 +-----+-------+-----------------------------------------------------+ 793 | Bit | Value | Meaning | 794 +-----+-------+-----------------------------------------------------+ 795 | 10 | 0 | The requester cannot handle bundles locally. | 796 | 10 | 1 | The requester can handle bundles. | 797 | 11 | 0 | The requester cannot receive streams. | 798 | 11 | 1 | The requester is also able to receive streams. | 799 | 14 | 0 | a _get_ or _getdir_ transaction is requested | 800 | 14 | 1 | a _delete_ transaction is requested | 801 | 15 | 0 | the File Path field holds a file for a _get_ or | 802 | | | _delete_ | 803 | 15 | 1 | the File Path field specifies a directory name for | 804 | | | a _getdir_ or _delete_ | 805 | 16 | 0 | The requester is able to receive DATA over UDP | 806 | | | only. | 807 | 16 | 1 | The requester is also able to receive DATA over | 808 | | | UDP-Lite. | 809 +-----+-------+-----------------------------------------------------+ 811 The File Path portion of a _get_ packet is a null-terminated UTF-8 812 encoded string [RFC3629] that represents the path and base file name 813 on the file-sender of the file (or directory) that the file-receiver 814 wishes to perform the _get_, _getdir_, or _delete_ operation on. 815 Implementations SHOULD only send as many octets of File Path as are 816 needed for carrying this string, although some implementations MAY 817 choose to send a fixed-size File Path field in all REQUEST packets 818 that is filled with null octets after the last UTF-8 encoded octet of 819 the path. A maximum of 1024 octets for this field, and for the File 820 Path fields in other Saratoga packet types, is used to limit the 821 total packet size to within a single IPv6 minimum MTU (minus some 822 padding for network layer headers), and thus avoid the need for 823 fragmentation. The 1024-octet maximum applies after UTF-8 encoding 824 and null termination. 826 As in the standard Internet File Transfer Protocol (FTP) [RFC0959], 827 for path separators, Saratoga allows the local naming convention on 828 the peers to be used. There are security implications to processing 829 these strings without some intelligent filtering and checking on the 830 filesystem items they refer to, as discussed in the Security 831 Considerations section later within this document. 833 If the File Path field is empty, i.e. is a null-terminated zero- 834 length string one octet long, then this indicates that the file- 835 receiver is ready to receive any file that the file-sender would like 836 to send it, rather than requesting a particular file. This allows 837 the file-sender to determine the order and selection of files that it 838 would like to forward to the receiver in more of a "push" manner. Of 839 course, file retrieval could also follow a "pull" manner, with the 840 file-receiving host requesting specific files from the file-sender. 841 This may be desirable at times if the file-receiver is low on storage 842 space, or other resources. The file-receiver could also use the 843 Saratoga _getdir_ transaction results in order to select small files, 844 or make other optimizations, such as using its local knowledge of 845 contact times to pick files of a size likely to be able to be 846 delivered completely. File transfer through pushing sender-selected 847 files implements delivery prioritization decisions made solely at the 848 Saratoga file-sending node. File transfer through pulling specific 849 receiver-selected files implements prioritization involving more 850 participation from the Saratoga file-receiver. This is how Saratoga 851 implements Quality of Service (QoS). 853 The null-terminated File Path string MAY be followed by an optional 854 Authentication Field that can be used to validate the REQUEST packet. 855 Any value in the Authentication Field is the result of a computation 856 of packet contents that SHOULD include, at a minimum, source and 857 destination IP addresses and port numbers and packet length in a 858 'pseudo-header', as well as the content of all Saratoga fields from 859 Version to File Path, excluding the predictable null-termination 860 octet. This Authentication Field can be used to allow the REQUEST 861 receiver to discriminate between other peers, and permit and deny 862 various REQUEST actions as appropriate. The format of this field is 863 unspecified for local use. 865 REQUEST packets may be sent multicast, to learn about all listening 866 nodes. A multicast _get_ request for a file that elicits multiple 867 METADATA responses should be followed by unicast HOLESTOFILL packets 868 with status errors cancelling all but one of the proposed transfers. 869 Timestamps in the Directory Entry can be used to select the most 870 recent version of an offered file, and the host to fetch it from. 872 If the receiver already has the file at the expected file path and is 873 requesting an update to that file, REQUEST can be sent after a 874 METADATA advertising that file, to allow the sender to determine 875 whether a replacement for the file should be sent. 877 Delete requests are ignored for files currently being transferred. 879 4.3. METADATA 881 METADATA packets are sent as part of a data transfer transaction 882 (_get_, _getfile_, and _put_). A METADATA packet says how large the 883 file is and what its name is, as well as what size of file offset 884 descriptor is chosen for the session. METADATA packets are normally 885 sent at the start of a data transfer, but may be repeated if 886 requested. 888 Format 890 0 1 2 3 891 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 892 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 893 |0 1| Type | Flags |Sumtype| 894 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 895 | Id | 896 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 897 | / 898 / / 899 / example error-detection checksum (128-bit MD5 shown) / 900 / / 901 / | 902 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 903 | / 904 / single Directory Entry describing file / 905 / (variable length) / 906 / // 907 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 909 where 911 +-----------+-------------------------------------------------------+ 912 | Field | Description | 913 +-----------+-------------------------------------------------------+ 914 | Type | 2 | 915 | Flags | indicate additional boolean metadata about a file | 916 | Sumtype | indicates whether a checksum is present after the Id, | 917 | | and what type it is. | 918 | Id | identifies the transaction that this packet describes | 919 | Checksum | an example included checksum covering file contents | 920 | Directory | describes file system information about the file, | 921 | Entry | including length, timestamps, etc.; the format is | 922 | | specified in Section 5 | 923 +-----------+-------------------------------------------------------+ 925 The first octet of the Flags field is currently specified for use. 926 The later two octets are reserved for future use, and MUST be set to 927 zero. 929 In the Flags field, the bits labelled 8 and 9 in the figure above 930 indicate the exact size of the offset descriptor fields used in this 931 particular packet and are interpreted exactly as the bits 8 and 9 in 932 the BEACON packet described above. The value of these bits 933 determines the size of the File Length field in the current packet, 934 as well as indicating the size of the offset fields used in DATA and 935 HOLESTOFILL packets within the session that will follow this packet. 937 +--------+--------+-------------------------------------------------+ 938 | Bit 10 | Bit 11 | Type of transfer | 939 +--------+--------+-------------------------------------------------+ 940 | 0 | 0 | a file is being sent. | 941 | 0 | 1 | the file being sent should be interpreted as a | 942 | | | directory record. | 943 | 1 | 0 | a bundle is being sent. | 944 | 1 | 1 | an indefinite-length stream is being sent. | 945 +--------+--------+-------------------------------------------------+ 947 Also inside the Flags field, bits 10 and 11 indicate what is being 948 transferred - a file, special file that contains directory records, 949 bundle, or stream. The value 01 indicates that the METADATA and DATA 950 packets are being generated in response to a _getdir_ REQUEST, and 951 that the assembled DATA contents should be interpreted as a sequence 952 of Directory Records, as defined in Section 5. 954 +-----+-------+-----------------------------------------------------+ 955 | Bit | Value | Meaning | 956 +-----+-------+-----------------------------------------------------+ 957 | 12 | 0 | This transfer is in progress. | 958 | 12 | 1 | This transfer is no longer in progress, and has | 959 | | | been terminated. | 960 +-----+-------+-----------------------------------------------------+ 962 Bit 12 indicates whether the transfer is in progress, or has been 963 terminated by the sender. It is normally set to 1 only when METADATA 964 is resent to indicate that a stream transfer has been ended. 966 If a stream is being transferred, its length is unknown -- otherwise 967 it would be a file. The length property of a Directory Entry for a 968 stream is expected to be zero. 970 +--------+----------------------------------------------------------+ 971 | Bit 13 | Use | 972 +--------+----------------------------------------------------------+ 973 | 0 | This file's content MUST be delivered reliably without | 974 | | errors using UDP. | 975 | 1 | This file's content MAY be delivered unreliably, without | 976 | | errors, or partly unreliably, where errors are | 977 | | tolerated, using UDP-Lite. | 978 +--------+----------------------------------------------------------+ 980 Bit 13 indicates whether the file must be sent reliably or can be 981 sent at least partly unreliably, using UDP-Lite. This flag can only 982 be set if the originator of the file knows that at least some of the 983 file content is suitable for sending unreliably and is robust to 984 errors. This flag reflects a property of the file itself. This flag 985 may still be set if the immediate file-receiver is only capable of 986 UDP delivery, on the assumption that this preference will be 987 preserved for later transfers where UDP-Lite transfers may be taken 988 advantage of by senders with knowledge of the internal file 989 structure. The file-sender may know that the receiver is capable of 990 handling UDP-Lite, either from a _get_ REQUEST, from exchange of 991 BEACONs, or a-priori. 993 The high four bits of the Flags field, bits 28-31, are used to 994 indicate if an error-detection checksum has been included in the 995 METADATA for the file to be transferred. Here, bits 0000 indicate 996 that no checksum is present, with the implicit assumption that the 997 application will do its own end-to-end check. Other values indicate 998 the type of checksum to use. The choice of checksum depends on the 999 available computing power and the length of the file to be 1000 checksummed. Longer files require stronger checksums to ensure 1001 error-free delivery. The checksum of the file to be transferred is 1002 carried as shown, with a fixed-length field before the varying-length 1003 File Length and File Name information fields. 1005 Assigned values for the checksum field are: 1007 +-----------+-------------------------------------------------------+ 1008 | Value | Use | 1009 | (0-15) | | 1010 +-----------+-------------------------------------------------------+ 1011 | 0 | No checksum is provided. | 1012 | 1 | 32-bit CRC32 checksum, suitable for small files. | 1013 | 2 | 128-bit MD5 checksum, suitable for larger files | 1014 | 3 | 160-bit SHA-1 checksum, suitable for larger files but | 1015 | | slower to process than MD5. | 1016 +-----------+-------------------------------------------------------+ 1018 It is expected that higher values will be allocated to new and 1019 stronger checksums able to better protect larger files. A checksum 1020 SHOULD be included for files being transferred. The checksum SHOULD 1021 be as strong as possible. Streaming of an indefinite-length stream 1022 MUST set the checksum field to zero. 1024 It is expected that a minimum of the MD5 checksum will be used, 1025 unless the Saratoga implementation is used exclusively for small 1026 transfers at the low end of the 16-bit file descriptor range, such as 1027 on low-performing hardware, where the weaker CRC-32c checksum can 1028 suffice. 1030 The CRC32 checksum is computed as described for the CRC-32c algorithm 1031 given in [RFC3309]. 1033 The MD5 Sum field is generated via the MD5 algorithm [RFC1321], 1034 computed over the entire contents of the file being transferred. The 1035 file-receiver can compute the MD5 result over the reassembled 1036 Saratoga DATA packet contents, and compare this to the METADATA's MD5 1037 Sum field in order to gain confidence that there were no undetected 1038 protocol errors or UDP checksum weaknesses encountered during the 1039 transfer. Although MD5 is known to be less than optimal for security 1040 uses, it remains excellent for non-security use in error detection 1041 (as is done here in Saratoga), and has better performance 1042 implications than cryptographically-stronger alternatives given the 1043 limited available processing of many DTN use cases. 1045 Checksums may be privately keyed for local use, to allow transmission 1046 of authenticated or encrypted files delivered in DATA packets. This 1047 has limitations, discussed further in the Security Considerations 1048 section at end. 1050 Use of the checksum to ensure that a file has been correctly relayed 1051 to the receiving node is important. A provided checksum MUST be 1052 checked against the received data file. If checksum verification 1053 fails, either due to corruption or due to the receiving node not 1054 having the right key for a keyed checksum), the file MUST be 1055 discarded. If the file is to be relayed onwards later to another 1056 Saratoga peer, the metadata, including the checksum, MUST be retained 1057 with the file and SHOULD be retransmitted onwards unchanged with the 1058 file for end-to-end coverage. If it is necessary to recompute the 1059 checksum or encrypted data for the new peer, either because a 1060 different key is in use or the existing checksum algorithm is not 1061 supported, the new checksum MUST be computed before the old checksum 1062 is verified, to ensure overlapping checksum coverage and detect 1063 errors introduced in file storage. 1065 If the METADATA is in response to a _get_ REQUEST including a file 1066 record, and the record information for the held file matches what the 1067 requester already has, as has been indicated by a previously-received 1068 METADATA advertisement from the requester, then only the METADATA is 1069 sent repeating this information and verifying that the file is up to 1070 date. If the record information does not match and a newer file can 1071 be supplied, the METADATA begins a transfer with following DATA 1072 packets to update the file. 1074 4.4. DATA 1076 A series of DATA packets form the main part of a data transfer 1077 transaction (_get_, _put_, or _getdir_). The payloads constitute the 1078 actual file data being transferred. 1080 Format 1082 0 1 2 3 1083 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 1084 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1085 |0 1| Type | Flags | 1086 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1087 [ Id | 1088 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1089 [ Timestamp (optional, descriptor-size) ] 1090 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1091 [ Offset (descriptor) ] 1092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1094 where 1096 +---------------+---------------------------------------------------+ 1097 | Field | Description | 1098 +---------------+---------------------------------------------------+ 1099 | Type | 3 | 1100 | Flags 8 and 9 | bit 8 and 9 specify the size of offset | 1101 | | descriptor, as elsewhere. | 1102 | Flag 10 | bit 10, with bit 11, indicates whether a file, | 1103 | | bundle, stream or directory entry is being | 1104 | | carried. This bit will normally be zero for | 1105 | | files. | 1106 | Flag 11 | bit 11 is used with bit 10. Normally this bit | 1107 | | will be zero for files. | 1108 | Flag 12 | bit 12 indicates that an optional timestamp is | 1109 | | included in the DATA header before the offset | 1110 | | descriptor. | 1111 | Flag 15 | bit 15 requests an immediate HOLESTOFILL ack to | 1112 | | be generated in response to receiving this | 1113 | | packet. | 1114 | Id | identifies the transaction that this packet | 1115 | | belongs to | 1116 | Offset | the offset in octets to the location where the | 1117 | | first byte of this packet's payload is to be | 1118 | | written | 1119 +---------------+---------------------------------------------------+ 1121 The DATA packet has a minimum size of ten octets, using sixteen-bit 1122 descriptors and no timestamps. 1124 DATA packets are normally sent error-free using UDP for reliable 1125 transfer (of both content and delivery). However, for transfers that 1126 can tolerate content errors, DATA packets MAY be sent using UDP-Lite. 1127 If UDP-Lite is used, the file-sender must know that the file-receiver 1128 is capable of handling UDP-Lite, and the file contents to be 1129 transferred should be resilient to errors. The UDP-Lite checksum 1130 MUST protect the Saratoga headers, up to and including the offset 1131 descriptor, and MAY protect more of each packet's payload, depending 1132 on the file-sender's knowledge of the internal structure of the file 1133 and the file's reliability requirements. 1135 Flag bits 8 and 9 are set to indicate the size of the offset 1136 descriptor as described for BEACON and METADATA packets, so that each 1137 DATA packet is self-describing. This allows the DATA packet to be 1138 used to construct a file even when the initial METADATA is lost and 1139 must be resent. The flag values for bits 8, 9, 10 and 11 MUST be the 1140 same as indicated in the initial METADATA packet. 1142 +--------+--------+-------------------------------------------------+ 1143 | Bit 10 | Bit 11 | Type of transfer | 1144 +--------+--------+-------------------------------------------------+ 1145 | 0 | 0 | a file is being sent. | 1146 | 0 | 1 | the file being sent should be interpreted as a | 1147 | | | directory record. | 1148 | 1 | 0 | a bundle is being sent. | 1149 | 1 | 1 | an indefinite-length stream is being sent. | 1150 +--------+--------+-------------------------------------------------+ 1152 Also inside the Flags field, bits 10 and 11 indicate what is being 1153 transferred - a file, special file that contains directory records, 1154 bundle, or stream. The value 01 indicates that the METADATA and DATA 1155 packets are being generated in response to a _getdir_ REQUEST, and 1156 that the assembled DATA contents should be interpreted as a sequence 1157 of Directory Records, as defined in Section 5. 1159 +-----+-------+-----------------------------------------------------+ 1160 | Bit | Value | Meaning | 1161 +-----+-------+-----------------------------------------------------+ 1162 | 12 | 0 | This packet does not include an optional timestamp | 1163 | | | field. | 1164 | 12 | 1 | This packet includes an optional timestamp field. | 1165 +-----+-------+-----------------------------------------------------+ 1167 Flag bit 12 indicates that an optional timestamp is carried in the 1168 packet before the offset field. The length of this timestamp is the 1169 length of the offset descriptor field. Timestamps are particularly 1170 useful when streaming. The timestamp format is implementation- 1171 dependent. 1173 +-----+-------+------------------------------------+ 1174 | Bit | Value | Meaning | 1175 +-----+-------+------------------------------------+ 1176 | 15 | 0 | No response is requested. | 1177 | 15 | 1 | A HOLESTOFILL packet is requested. | 1178 +-----+-------+------------------------------------+ 1180 Within the Flags field, if bit 15 of the packet is set, the file- 1181 receiver is to immediately generate a HOLESTOFILL packet to provide 1182 the file-sender with up-to-date information regarding the status of 1183 the file transfer. This flag is set carefully and rarely. It may be 1184 set periodically, but infrequently. Asymmetric links with 1185 constrained backchannels can only carry a limited amount of 1186 HOLESTOFILL packets before ack congestion becomes a problem. This 1187 flag SHOULD NOT be set if an unreliable stream is being transferred, 1188 or if multicast is in use. This flag SHOULD be set periodically for 1189 reliable file transfers, or reliable streaming. 1191 Immediately following the DATA header is the payload, which consumes 1192 the remainder of the packet and whose length is implicitly defined by 1193 the end of the packet. The payload octets are directly formed from 1194 the continuous octets starting at the specified Offset in the file 1195 being transferred. No special coding is performed. A zero-octet 1196 payload length is allowable. 1198 The length of the Offset fields used within all DATA packets for a 1199 given transaction MUST be consistent with the length indicated by 1200 bits 8 and 9 of the transactions METADATA packet. If the METADATA 1201 packet has not yet been received, a file-receiver SHOULD request it 1202 via a HOLESTOFILL packet, and MAY choose to enqueue received DATA 1203 packets for later processing after the METADATA arrives. 1205 4.5. HOLESTOFILL 1207 The HOLESTOFILL packet type is used for feedback from a Saratoga 1208 file-receiver to a Saratoga file-sender to indicate transaction 1209 progress and request transmission (usually re-transmission) of 1210 specific sets of octets within the current transaction (called 1211 "holes"). This can be used to clean up losses (or indicate no 1212 losses) at the end of, or during, a transaction, or to efficiently 1213 resume a transfer that was interrupted in a previous transaction. 1215 Format 1217 0 1 2 3 1218 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 1219 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1220 |1 0| Type | Flags | Status | 1221 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1222 | Id | 1223 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1224 [ Cumulative Acknowledgement (descriptor) ] 1225 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1226 [ In-Response-To (timestamp, optional) ] 1227 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1228 [ In-Response-To (descriptor) ] 1229 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1230 | (possibly, several Hole fields) / 1231 / ... / 1232 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1234 where 1236 +-----------------+-------------------------------------------------+ 1237 | Field | Description | 1238 +-----------------+-------------------------------------------------+ 1239 | Type | 4 | 1240 | Flags | are defined below. | 1241 | Id | identifies the transaction that this packet | 1242 | | belongs to. | 1243 | Status | a value of 0x00 indicates the transfer is | 1244 | | sucessfully proceeding. All other values are | 1245 | | errors terminating the transfer, explained | 1246 | | below. | 1247 | Zero-Pad | an octet fixed at 0x00 to allow later fields to | 1248 | | be conveniently aligned for processing. | 1249 | Cumulative | the offset of the lowest-numbered octet of the | 1250 | Acknowledgement | file not yet received. | 1251 | In-Response-To | This is only present if the timestamp flag is | 1252 | (optional | set. If the HOLESTOFILL packet is voluntary | 1253 | timestamp) | and the voluntary flag is set, this should | 1254 | | repeat the timestamp of the DATA packet | 1255 | | containing the highest offset seen. If the | 1256 | | HOLESTOFILL packet is in response to a | 1257 | | mandatory request, this will repeat the | 1258 | | timestamp of the requesting DATA packet. The | 1259 | | file-sender may use these timestamps to | 1260 | | estimate latency. There are special | 1261 | | considerations for streaming, to protect | 1262 | | against the ambiguity of wrapped offset | 1263 | | descriptor sequence numbers, discussed below. | 1264 | In-Response-To | the offset of the highest-numbered octet within | 1265 | (descriptor) | a DATA packet that generated this HOLESTOFILL | 1266 | | packet, or the offset of the highest-numbered | 1267 | | octet seen if this HOLESTOFILL is generated | 1268 | | voluntarily and the voluntary flag is set. | 1269 | Holes | indications of offset ranges of missing data, | 1270 | | defined below. | 1271 +-----------------+-------------------------------------------------+ 1273 The HOLESTOFILL packet has a minimum size of twelve octets, using 1274 sixteen-bit descriptors and no timestamps. 1276 The Id field is needed to associate the packet with the transaction 1277 that it refers to. Using the Id as a key, the receiver of a packet 1278 can determine the lengths of the Cumulative Acknowledgement, In- 1279 Response-To, and Hole offsets used within the HOLESTOFILL packet, as 1280 this file offset descriptor size was set in the initial METADATA 1281 packet that established the Id. 1283 Flags bits 8 and 9 are set to indicate the size of the offset 1284 descriptor as described for BEACON and METADATA packets, so that each 1285 HOLESTOFILL packet is self-describing. The flag values here MUST be 1286 the same as indicated in the initial METADATA and DATA packets. 1288 Other bits in the Flags field are defined as: 1290 +-----+-------+---------------------------------------------------+ 1291 | Bit | Value | Meaning | 1292 +-----+-------+---------------------------------------------------+ 1293 | 12 | 0 | This packet does not include a timestamp field. | 1294 | 12 | 1 | This packet includes an optional timestamp field. | 1295 +-----+-------+---------------------------------------------------+ 1297 Flag bit 12 indicates that an optional timestamp is carried in the 1298 packet before the In-Response-To descriptor. The length of this 1299 timestamp is the length of the descriptor field. 1301 +-----+-------+----------------------------------------+ 1302 | Bit | Value | Meaning | 1303 +-----+-------+----------------------------------------+ 1304 | 13 | 0 | file's METADATA has been received. | 1305 | 13 | 1 | file's METADATA has not been received. | 1306 +-----+-------+----------------------------------------+ 1308 If bit 13 of a HOLESTOFILL packet has been set to indicate that the 1309 METADATA has not yet been received, then the METADATA should be 1310 resent. This flag should normally be clear. 1312 +-----+-------+-----------------------------------------------------+ 1313 | Bit | Value | Meaning | 1314 +-----+-------+-----------------------------------------------------+ 1315 | 14 | 0 | this packet contains the complete current set of | 1316 | | | holes at the file-receiver. | 1317 | 14 | 1 | this packet contains incomplete hole-state; holes | 1318 | | | shown in this packet should supplement other | 1319 | | | incomplete hole-state known to the file-sender. | 1320 +-----+-------+-----------------------------------------------------+ 1322 Bit 14 of the HOLESTOFILL packet is only set when there are too many 1323 holes to fit within a single HOLESTOFILL packet due to MTU 1324 limitations. This causes the hole list to be spread out over 1325 multiple HOLESTOFILL packets, each of which conveys distinct sets of 1326 holes. This could occur, for instance, in a large file _put_ 1327 scenario with a long-delay feedback loop and poor physical layer 1328 conditions. When losses are light and/or hole reporting and repair 1329 is relatively frequent, all holes should easily fit within a single 1330 HOLESTOFILL packet, and this flag will be clear. Bit 14 should 1331 normally be clear. 1333 In some rare cases of high loss, there may be too many holes in the 1334 received data to convey within a single HOLESTOFILL's size, which is 1335 limited by the link MTU size. In this case, multiple HOLESTOFILL 1336 packets may be generated, and Flags bit 14 should be set on each 1337 HOLESTOFILL packet accordingly, to indicate that each packet holds 1338 incomplete results. The complete group of HOLESTOFILL packets, each 1339 containing incomplete information, will share common In-Response-To 1340 information to distinguish them from any earlier groups. 1342 +-----+-------+----------------------------------------------------+ 1343 | Bit | Value | Meaning | 1344 +-----+-------+----------------------------------------------------+ 1345 | 15 | 0 | This HOLESTOFILL was requested by the file-sender. | 1346 | 15 | 1 | This HOLESTOFILL is sent voluntarily. | 1347 +-----+-------+----------------------------------------------------+ 1349 Flag bit 15 indicates whether the HOLESTOFILL is sent voluntarily or 1350 due to a request by the sender. It affects content of the In- 1351 Response-To timestamp and descriptor fields. 1353 In the case of a transfer proceeding normally, immediately following 1354 the HOLESTOFILL packet header shown above, is a set of "Hole" 1355 definitions. Each Hole definition is a pair of unsigned integers. 1356 For a 32-bit offset descriptor, each Hole definition consists of two 1357 four-octet unsigned integers: 1359 Hole Definition Format 1361 0 1 2 3 1362 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 1363 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1364 [ offset to start of hole (descriptor) ] 1365 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1366 [ offset to end of hole (descriptor) ] 1367 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1369 The start of the hole means the offset of the first unreceived byte 1370 in that hole. The end of the hole means the last unreceived byte in 1371 that hole. 1373 For 16-bit descriptors, each Hole definition holds two two-octet 1374 unsigned integers, while Hole definitions for 64- and 128-bit 1375 descriptors require two eight- and two sixteen-octet unsigned 1376 integers respectively. 1378 Since each Hole definition takes up eight octets when 32-bit offset 1379 lengths are used, we expect that well over 100 such definitions can 1380 fit in a single HOLESTOFILL packet, given the IPv6 minimum MTU. 1382 A 'voluntary' HOLESTOFILL is sent at the start of each transaction, 1383 once METADATA information has been received. This indicates that the 1384 receiver is ready to receive the file, or indicates an error or 1385 rejection code, described below. A HOLESTOFILL indicating a 1386 successfully established transfer has a Cumulative Acknowledgement of 1387 zero and an In-Response-To field of zero. 1389 In the case of an error causing a transfer to be aborted, the Status 1390 field holds a code that can be used to explain the cause of the error 1391 to the other peer. A zero value indicates that there have been no 1392 significant errors (this is called a "success HOLESTOFILL" within 1393 this document), while any non-zero value means the transaction should 1394 be aborted (this is called a "failure HOLESTOFILL"). 1396 +------------+------------------------------------------------------+ 1397 | Status | Meaning | 1398 | Value | | 1399 +------------+------------------------------------------------------+ 1400 | 0x00 | Success, No Errors. | 1401 | 0x01 | Unspecified Error. | 1402 | 0x02 | Unable to send file due to resource constraints. | 1403 | 0x03 | Unable to receive file due to resource constraints. | 1404 | 0x04 | File not found. | 1405 | 0x05 | Access Denied. | 1406 | 0x06 | Unknown Id field for transaction. | 1407 | 0x07 | Did not delete file. | 1408 | 0x08 | File length is longer than REQUEST indicates support | 1409 | | for. | 1410 | 0x09 | File offset descriptors do not match expected use or | 1411 | | file length. | 1412 | 0x0A | Unsupported packet type received. | 1413 | 0x0B | DATA flag bits describing transfer have changed | 1414 | | unexpectedly. | 1415 +------------+------------------------------------------------------+ 1417 The recipient of a failure HOLESTOFILL MUST NOT try to process the 1418 Cumulative Acknowledgement, In-Response-To, or Hole offsets, because, 1419 in some types of error conditions, the packet's sender may not have 1420 any way of setting them to the right length for the transaction. 1422 When sending an indefinite-length stream, the possibility of offset 1423 sequence numbers wrapping back to zero must be considered. This can 1424 be protected against by using large offsets, and by the stream 1425 receiver. The receiver MUST separate out holes before the offset 1426 wraps to zero from holes after the wrap, and send Hole definitions in 1427 different HOLESTOFILL packets, with Flag 14 set to mark them as 1428 incomplete. Any Hole straddling a sequence wrap MUST be broken into 1429 two separate Holes, with the second Hole starting at zero. The 1430 timestamps in HOLESTOFILL packets carrying any pre-wrap holes should 1431 be earlier than the timestamp in later packets, and should repeat the 1432 timestamp of the last DATA packet seen for that offset sequence 1433 before the following wrap to zero occurred. 1435 5. The Directory Entry 1437 Directory Entries have two uses within Saratoga: 1439 1. Within a METADATA packet, a Directory Entry is used to give 1440 information about the file being transferred, in order to 1441 facilitate proper reassembly of the file and to help the file- 1442 receiver understand how recently the file may have been created 1443 or modified. 1445 2. When a peer requests a directory listing via a _getdir_ REQUEST, 1446 the other peer generates a file containing a series of one or 1447 more concatenated Directory Entry records, and transfers this 1448 file as it would transfer the response to a normal _get_ REQUEST, 1449 sending the records together within DATA packets. This file may 1450 be either temporary or within-memory and not actually a part of 1451 the host's file system itself. 1453 Directory Entry Format 1455 0 1 2 3 1456 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 1457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1458 [ Size (descriptor) ] 1459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1460 | Mtime | 1461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1462 | Ctime | 1463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1464 | Properties | / 1465 +-+-+-+-+-+-+-+-+ / 1466 / / 1467 / File Path (max 1024 octets,variable length) / 1468 / ... // 1469 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1471 where 1473 +------------+------------------------------------------------------+ 1474 | field | description | 1475 +------------+------------------------------------------------------+ 1476 | Size | the size of the file or directory in octets. | 1477 | Mtime | a timestamp showing when the file or directory was | 1478 | | modified. | 1479 | Ctime | the timestamp of the last status change for this | 1480 | | file or directory. | 1481 | Properties | if set, bit 7 of this field indicates that the entry | 1482 | | corresponds to a directory. Bit 6, if set, | 1483 | | indicates that the file is "special". A special | 1484 | | file may not be directly transferable as it | 1485 | | corresponds to a symbolic link, a named pipe, a | 1486 | | device node, or some other "special" filesystem | 1487 | | object. A file-sender may simply choose not to | 1488 | | include these types of files in the results of a | 1489 | | _getdir_ request. | 1490 | File Path | contains the file's name relative within the | 1491 | | requested path of the _getdir_ transaction, a | 1492 | | maximum of 1024-octet UTF-8 string, that is | 1493 | | null-terminated to indicate the beginning of the | 1494 | | next directory entry in _getdir_ results | 1495 +------------+------------------------------------------------------+ 1497 +-------+-------+---------------------+ 1498 | Bit 6 | Bit 7 | Properties conveyed | 1499 +-------+-------+---------------------+ 1500 | 0 | 0 | normal file. | 1501 | 0 | 1 | normal directory. | 1502 | 1 | 0 | special file. | 1503 | 1 | 1 | special directory. | 1504 +-------+-------+---------------------+ 1506 Whether a particular Directory Entry is being interpreted as the 1507 contents of a METADATA packet, or as the result of a _getdir_ 1508 transaction, the width of the Size field is the same as that used for 1509 all lengths and offsets within the transfer, given by the METADATA 1510 and DATA Flags bits 8 and 9. 1512 Streams listed in a directory should be marked as special. 1514 It is expected that files are only listed in Directory Entries if 1515 they can be transferred to the requester. An implementation only 1516 capable of receiving small files using 16-bit descriptors will only 1517 see small files capable of being transferred to it when browsing the 1518 filesystem of an implementation capable of larger sizes. Directory 1519 sizes are not sent, and a Size of 0 is given instead for directories. 1521 The "epoch" format used in the timestamps for Mtime and Ctime in file 1522 object records is the number of seconds since January 1, 2000 in UTC, 1523 which is the same epoch used in the DTN Bundle Protocol for 1524 timestamps and postpones wrapping for 30 years beyond typical 1970- 1525 based timestamps. This should include all leapseconds. 1527 A file-receiver should preserve the timestamp information received in 1528 the METADATA for its own copy of the file, to allow newer versions of 1529 files to propagate and supercede older versions. 1531 6. Behavior of a Saratoga Peer 1533 This section describes some details of Saratoga implementations and 1534 uses the RFC 2119 standards language to describe which portions are 1535 needed for interoperability. 1537 6.1. Saratoga Transactions 1539 Following are descriptions of the packet exchanges between two peers 1540 for each type of transaction. 1542 6.1.1. The _get_ Transaction 1544 1. A peer (the file-receiver) sends a REQUEST packet to its peer 1545 (the file-sender). The Flags bits are set to indicate that this 1546 is not a _delete_ request, nor does the File Path indicate a 1547 directory. Each _get_ transaction corresponds to a single file, 1548 and fetching multiple files requires sending multiple REQUEST 1549 packets and using multiple transaction Ids. If a specific file is 1550 being requested, then its name is filled into the File Path 1551 field, otherwise it is left null and the file-sender will send a 1552 file of its choice. 1554 2. If the request is rejected, then a HOLESTOFILL packet containing 1555 an error code in the Status field is sent and the transaction is 1556 terminated. This HOLESTOFILL packet MUST be sent to reject and 1557 terminate the transaction. The error code MAY make use of the 1558 "Unspecified Error" value for security reasons. Some REQUESTs 1559 might also be rejected for specifying files that are too large to 1560 have their lengths encoded within the maximum integer field width 1561 advertised by bits 8 and 9 of the REQUEST. 1563 3. If the request is accepted, then a HOLESTOFILL packet MUST be 1564 sent with an error code of 0x00 and an In-Response-To field of 1565 zero. 1567 4. Otherwise, if the request is granted, then the file-sender 1568 generates and sends a METADATA packet along with the contents of 1569 the file as a series of DATA packets. In the absence of 1570 HOLESTOFILL packets, if the file-sender believes it has finished 1571 sending the file, it MUST send the last DATA packet with the 1572 Flags bit set requesting a HOLESTOFILL response from the file- 1573 receiver. This can be followed by empty DATA packets with the 1574 Flags bit set requesting a HOLESTOFILL until either a HOLESTOFILL 1575 packet is received, or the inactivity timer expires. All of the 1576 DATA packets MUST use field widths for the file offset descriptor 1577 fields that match what the Flags of the METADATA packet 1578 specified. Some arbitrarily selected DATA packets may have the 1579 Flags bit set that requests a HOLESTOFILL packet. The file- 1580 receiver MAY voluntarily send HOLESTOFILL packets at other times, 1581 where the In-Response-To field MUST set to zero. The file- 1582 receiver SHOULD voluntarily send a HOLESTOFILL packet in response 1583 to the first DATA packet. 1585 5. As the file-receiver takes in the DATA packets, it writes them 1586 into the file locally. The file-receiver keeps track of missing 1587 data in a hole list. Periodically the file sender will set the 1588 ack flag bit in a DATA packet and request a HOLESTOFILL packet 1589 from the file-receiver, with a copy of this hole list. File- 1590 receivers MUST send a HOLESTOFILL packet immediately in response 1591 to receiving a DATA packet with the Flags bit set requesting a 1592 HOLESTOFILL. 1594 6. If the file-sender receives a HOLESTOFILL packet with a non-zero 1595 number of holes, it re-fetches the file data at the specified 1596 offsets and re-transmits it. If the METADATA packet requires 1597 retransmission, this is indicated by a bit in the HOLESTOFILL 1598 packet, and the METADATA packet is retransmitted. The file- 1599 sender MUST retransmit data from any holes reported by the file- 1600 receiver before proceeding further with new DATA packets. 1602 7. When the file-receiver has fully received the file data and the 1603 METADATA packet, then it sends a HOLESTOFILL packet indicating 1604 that the transaction is complete, and it terminates the 1605 transaction locally, although it MUST persist in responding to 1606 DATA packets requesting HOLESTOFILLs from the file-sender for 1607 some reasonable amount of time. 1609 Given that there may be a high degree of asymmetry in link bandwidth 1610 between the file-sender and file-receiver, the HOLESTOFILL packets 1611 should be carefully generated so as to not congest the feedback path. 1612 This means that both a file-sender should be cautious in setting the 1613 DATA Flags bit requesting HOLESTOFILLs, and also that a file-receiver 1614 should be cautious in gratuitously generating HOLESTOFILL packets of 1615 its own volition. On unidirectional links, a file-sender cannot 1616 reasonably expect to receive HOLESTOFILL packets, so should never 1617 request them. 1619 6.1.2. The _getdir_ Transaction 1621 A _getdir_ transaction proceeds through the same states as the _get_ 1622 transaction. The two differences are that the REQUEST has the 1623 directory bit set in its Flags field, and that, rather than 1624 transferring the contents of a file from the file-receiver to the 1625 file-sender, a set of records representing the contents of a 1626 directory are transferred. These can be parsed and dealt with by the 1627 file-receiver as desired. There is no requirement that a Saratoga 1628 peer send the full contents of a directory listing; a peer may filter 1629 the results to only those entries that are actually accessible to the 1630 requesting peer. 1632 For _getdir_ transactions, the METADATA's bits 8 and 9 in the Flags 1633 field specify both the width of the offset and length fields used 1634 within the transfers DATA and HOLESTOFILL packets, and also the width 1635 of file Size fields within Directory Entries in the interpreted 1636 _getdir_ results. These Flags bits are set to the minimum of the 1637 file-sender's locally-supported maximum width and the advertised 1638 maximum width within the REQUEST packet, and any file system entries 1639 that would normally be contained in the results, but that have sizes 1640 greater than this width can convey, MUST be filtered out. 1642 6.1.3. The _delete_ Transaction 1644 1. A peer sends a REQUEST packet with the bit set indicating that it 1645 is a deletion request and the path to be deleted is filled into 1646 the File Path field. The File Path MUST be filled in for 1647 _delete_ transactions, unlike for _get_ transactions. 1649 2. The other peer replies with a feedback HOLESTOFILL packet having 1650 a Status code that indicates whether the deletion was granted and 1651 occurred successfully (indicated by the 0x00 Status field in a 1652 success HOLESTOFILL), or whether some error occurred (indicated 1653 by the non-zero Status field in a failure HOLESTOFILL). This 1654 HOLESTOFILL packet MUST have no Holes and 16-bit width zero- 1655 valued Cumulative Acknowledgement and In-Response-To fields. 1657 6.1.4. The _put_ Transaction 1659 A _put_ transaction proceeds exactly as a _get_, except the file- 1660 sender and file-receiver roles are exchanged between peers, and no 1661 REQUEST packet is ever sent. The file-sending end senses that the 1662 transaction is in progress when it receives METADATA or DATA packets 1663 for which it has no knowledge of the Id field. If the file-receiver 1664 decides that it will store and handle this request (at least 1665 provisionally), then it MUST send a voluntary (ie, not requested) 1666 success HOLESTOFILL packet to the file-sender. Otherwise, it sends a 1667 failure HOLESTOFILL packet. After sending a failure HOLESTOFILL 1668 packet, it may ignore future packets with the same Id field from the 1669 file-sender, but it should, at a low rate, periodically regenerate 1670 the failure HOLESTOFILL packet if the flow of packets does not stop. 1672 6.2. Beacons 1674 Sending BEACON packets is not needed in any of the transactions 1675 discussed in this specification, but optional BEACONs can provide 1676 useful information in many situations. If a node periodically 1677 generates BEACON packets, then it should do so at a low rate which 1678 does not significantly affect in-progress data transfers. 1680 A node that supports multiple versions of Saratoga (e.g. version 1 1681 from this specification along with the older version 0), MAY send 1682 multiple BEACON packets showing different version numbers. The 1683 version number in a single BEACON should not be used to infer the 1684 larger set of protocol versions that a peer is compatible with. 1686 If a node receives BEACONs from a peer, then it SHOULD NOT attempt to 1687 start any _get_, _getdir_, or _delete_ transactions with that peer if 1688 bit 14 is not set in the latest received BEACONs. Likewise, if 1689 received BEACONs from a peer do not have bit 15 set, then _put_ 1690 transactions SHOULD NOT be attempted to that peer. Unlike the 1691 capabilities bits which prevent certain types of transactions from 1692 being attempted, the willingness bits are advisory, and transactions 1693 MAY be attempted even if the node is not advertising a willingness, 1694 as long as it advertises a capability. This avoids waiting for a 1695 willingness indication across long-delay links. 1697 6.3. Upper-Layer Interface 1699 No particular interface functionality is required in implementations 1700 of this specification. The means and degree of access to Saratoga 1701 configuration settings and transaction control that is offered to 1702 upper layers and applications is completely implementation-dependent. 1703 In general, it is expected that upper layers (or users) can set 1704 timeout values for transaction requests and for inactivity periods 1705 during the transaction, on a per-peer or per-transaction basis, but 1706 in some implementations where the Saratoga code is restricted to run 1707 only over certain interfaces with well-understood operational latency 1708 bounds, then these timers MAY be hard-coded. 1710 6.4. Inactivity Timer 1712 In order to determine the liveliness of a transaction, Saratoga nodes 1713 may implement an inactivity timer for each peer they are expecting to 1714 see packets from. For each packet received from a peer, its 1715 associated inactivity timer is reset. If no packets are received for 1716 some amount of time, and the inactivity timer expires, this serves as 1717 a signal to the node that it should abort (and optionally retry) any 1718 sessions that were in progress with the peer. Information from the 1719 link interface (i.e. link down) can override this timer for point-to- 1720 point links. 1722 The actual length of time that the inactivity timer runs for is a 1723 matter of both implementation and deployment situation. Relatively 1724 short timers (on the order of several round-trip times) allow nodes 1725 to quickly react to loss of contact, while longer timers allow for 1726 transaction robustness in the presence of transient link problems. 1727 This document deliberately does not specify a particular inactivity 1728 timer value nor any rules for setting the inactivity timer, because 1729 the protocol is intended to be used in both long- and short-delay 1730 regimes. 1732 Specifically, the inactivity timer is started on sending REQUEST or 1733 HOLESTOFILL packets. When sending packets not expected to elicit 1734 responses (BEACON, METADATA, or DATA without acknowledgement 1735 requests), there is no point to starting the local inactivity timer. 1737 For normal file transfers, there are simple rules for handling 1738 expiration of the inactivity timer during a _get_ or _put_ 1739 transaction. The file-sender SHOULD terminate the transaction state 1740 and cease to send DATA or METADATA packets. The file-receiver SHOULD 1741 stop sending HOLESTOFILL packets, and MAY choose to store the file in 1742 some cache location so that the transfer can be recovered. This is 1743 possible by waiting for an opportunity to re-attempt the transaction 1744 and immediately sending a HOLESTOFILL that only lists the parts of 1745 the file not yet received if the transaction is granted. In any 1746 case, a partially-received file MUST NOT be handled in any way that 1747 would allow another application to think it is complete. 1749 The file-sender may implement more complex timers to allow rate-based 1750 pacing or simple congestion control using information provided in 1751 HOLESTOFILL packets, but such possible timers and their effects are 1752 deliberately not specified here. 1754 7. Mailing list 1756 There is a mailing list for discussion of Saratoga and its 1757 implementations. Contact Lloyd Wood for details. 1759 8. Security Considerations 1761 The design of Saratoga provides limited, deliberately lightweight, 1762 services for authentication of session requests, and for 1763 authentication or encryption of data files via keyed metadata 1764 checksums. This document does not specify privacy or access control 1765 for data files transferred. Privacy, access, authentication and 1766 encryption issues may be addressed within an implementation or 1767 deployment in several ways that do not affect the file transfer 1768 protocol itself. As examples, IPsec may be used to protect Saratoga 1769 implementations from forged packets, to provide privacy, or to 1770 authenticate the identity of a peer. Other implementation-specific 1771 or configuration-specific mechanisms and policies might also be 1772 employed for authentication and authorization of requests. 1773 Protection of file data and meta-data can also be provided by a 1774 higher-level file encryption facility. If IPsec is not required, use 1775 of encryption before the file is given to Saratoga is preferable. 1776 Basic security practices like not accepting paths with "..", not 1777 following symbolic links, and using a chroot() system call, among 1778 others, should also be considered within an implementation. 1780 Note that Saratoga is intended solely for single-hop transfers 1781 between peers. A METADATA checksum using a previously shared key can 1782 be used to decrypt or authenticate delivered DATA files. Saratoga 1783 can only provide encryption across a single link, not end-to-end 1784 across concatenated links through untrusted peers, as checksum 1785 verification of file integrity is required at each node. End-to-end 1786 data encryption, if required, MUST be implemented by the application 1787 using Saratoga. 1789 9. IANA Considerations 1791 IANA has allocated port 7542 (tcp/udp) for use by Saratoga. 1793 saratoga 7542/tcp Saratoga Transfer Protocol 1794 saratoga 7542/udp Saratoga Transfer Protocol 1796 IANA has allocated a dedicated IPv4 all-hosts multicast address 1797 (224.0.0.108) and a dedicated IPv6 link-local multicast addresses 1798 (FF02:0:0:0:0:0:0:6c) for use by Saratoga. 1800 10. Acknowledgements 1802 Developing and deploying the on-orbit IP infrastructure of the 1803 Disaster Monitoring Constellation, in which Saratoga has proven 1804 useful, has taken the efforts of hundreds of people over more than a 1805 decade. We thank them all. 1807 Work on this document at NASA's Glenn Research Center was funded by 1808 NASA's Earth Science Technology Office (ESTO). 1810 We thank Stewart Bryant and Cathryn Peoples for their review 1811 comments. 1813 11. A Note on Naming 1815 Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier 1816 sunk at Bikini Atoll that is now a popular diving site. 1818 12. References 1820 12.1. Normative References 1822 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1823 August 1980. 1825 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1826 April 1992. 1828 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1829 Requirement Levels", BCP 14, RFC 2119, March 1997. 1831 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1832 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1833 September 2002. 1835 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1836 10646", STD 63, RFC 3629, November 2003. 1838 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and 1839 G. Fairhurst, "The Lightweight User Datagram Protocol 1840 (UDP-Lite)", RFC 3828, July 2004. 1842 12.2. Informative References 1844 [Hogie05] Hogie, K., Criscuolo, E., and R. Parise, "Using Standard 1845 Internet Protocols and Applications in Space", Computer 1846 Networks Special Issue on Interplanetary Internet, vol. 1847 47, no. 5, pp. 603-650, April 2005. 1849 [I-D.wood-dtnrg-http-dtn-delivery] 1850 Wood, L. and P. Holliday, "Using HTTP for delivery in 1851 Delay/Disruption-Tolerant Networks", 1852 draft-wood-dtnrg-http-dtn-delivery-03 (work in progress) , 1853 May 2009. 1855 [I-D.wood-dtnrg-saratoga] 1856 Wood, L., McKim, J., Eddy, W., Ivancic, W., and C. 1857 Jackson, "Using Saratoga with a Bundle Agent as a 1858 Convergence Layer for Delay-Tolerant Networking", 1859 draft-wood-dtnrg-saratoga-05 (work in progress) , 1860 May 2009. 1862 [Jackson04] 1863 Jackson, C., "Saratoga File Transfer Protocol", Surrey 1864 Satellite Technology Ltd internal technical document , 1865 2004. 1867 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 1868 STD 9, RFC 959, October 1985. 1870 [RFC3366] Fairhurst, G. and L. Wood, "Advice to link designers on 1871 link Automatic Repeat reQuest (ARQ)", BCP 62, RFC 3366, 1872 August 2002. 1874 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 1875 Specification", RFC 5050, November 2007. 1877 [Wood07a] Wood, L., Ivancic, W., Hodgson, D., Miller, E., Conner, 1878 B., Lynch, S., Jackson, C., da Silva Curiel, A., Cooke, 1879 D., Shell, D., Walke, J., and D. Stewart, "Using Internet 1880 Nodes and Routers Onboard Satellites", International 1881 Journal of Satellite Communications and Networking Special 1882 Issue on Space Networks, vol. 25, no. 2, pp. 195-216, 1883 March/April 2007. 1885 [Wood07b] Wood, L., Eddy, W., Ivancic, W., Miller, E., McKim, J., 1886 and C. Jackson, "Saratoga: a Delay-Tolerant Networking 1887 convergence layer with efficient link utilization", 1888 International Workshop on Satellite and Space 1889 Communications (IWSSC '07) Salzburg, September 2007. 1891 Authors' Addresses 1893 Lloyd Wood 1894 Cisco Systems 1895 11 New Square Park, Bedfont Lakes 1896 Feltham, Middlesex TW14 8HA 1897 United Kingdom 1899 Phone: +44-20-8824-4236 1900 Email: lwood@cisco.com 1901 Jim McKim 1902 RS Information Systems 1903 NASA Glenn Research Center 1904 21000 Brookpark Road, MS 142-1 1905 Cleveland, OH 44135 1906 USA 1908 Phone: +1-216-433-6536 1909 Email: James.H.McKim@grc.nasa.gov 1911 Wesley M. Eddy 1912 Verizon Federal Network Systems 1913 NASA Glenn Research Center 1914 21000 Brookpark Road, MS 54-5 1915 Cleveland, OH 44135 1916 USA 1918 Phone: +1-216-433-6682 1919 Email: weddy@grc.nasa.gov 1921 Will Ivancic 1922 NASA Glenn Research Center 1923 21000 Brookpark Road, MS 54-5 1924 Cleveland, OH 44135 1925 USA 1927 Phone: +1-216-433-3494 1928 Email: William.D.Ivancic@grc.nasa.gov 1930 Chris Jackson 1931 Surrey Satellite Technology Ltd 1932 Tycho House 1933 Surrey Space Centre 1934 20 Stephenson Road 1935 Guildford, Surrey GU2 7YE 1936 United Kingdom 1938 Phone: +44-1483-803-803 1939 Email: C.Jackson@sstl.co.uk