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