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