idnits 2.17.1 draft-wood-tsvwg-saratoga-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with multicast IPv4 addresses in the document. If these are generic example addresses, they should be changed to use the 233.252.0.x range defined in RFC 5771 == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: In accordance with the UDP Guidelines [RFC5405], congestion control MUST be supported if Saratoga is being used across the public Internet, and SHOULD be supported in environments where links are shared by traffic flows. Congestion control MAY NOT be supported across private, single-flow links engineered for performance: Saratoga's primary use case. -- 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 (September 26, 2011) is 4589 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-07 == Outdated reference: A later version (-14) exists of draft-wood-dtnrg-saratoga-09 -- Obsolete informational reference (is this intentional?): RFC 5405 (Obsoleted by RFC 8085) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Wood 3 Internet-Draft University of Surrey 4 Intended status: Experimental W. Eddy 5 Expires: March 29, 2012 MTI Systems 6 C. Smith 7 CSIRO 8 W. Ivancic 9 NASA 10 C. Jackson 11 SSTL 12 September 26, 2011 14 Saratoga: A Scalable Data Transfer Protocol 15 draft-wood-tsvwg-saratoga-10 17 Abstract 19 This document specifies the Saratoga transfer protocol. Saratoga was 20 originally developed to transfer remote-sensing imagery efficiently 21 from a low-Earth-orbiting satellite constellation, but is useful for 22 many other scenarios, including ad-hoc peer-to-peer communications, 23 delay-tolerant networking, and grid computing. Saratoga is a simple, 24 lightweight, content dissemination protocol that builds on UDP, and 25 optionally uses UDP-Lite. Saratoga is intended for use when moving 26 files or streaming data between peers which may have permanent, 27 sporadic or intermittent connectivity, and is capable of transferring 28 very large amounts of data reliably under adverse conditions. The 29 Saratoga protocol is designed to cope with highly asymmetric link or 30 path capacity between peers, and can support fully-unidirectional 31 data transfer if required. In scenarios with dedicated links, 32 Saratoga focuses on high link utilization to make the most of limited 33 connectivity times, while standard congestion control mechanisms can 34 be implemented for operation over shared links. Loss recovery is 35 implemented via a simple negative-ack ARQ mechanism. The protocol 36 specified in this document is considered to be appropriate for 37 experimental use on private IP networks. 39 Status of this Memo 41 This Internet-Draft is submitted to IETF in full conformance with the 42 provisions of BCP 78 and BCP 79. This document may not be modified, 43 and derivative works of it may not be created, except to format it 44 for publication as an RFC and to translate it into languages other 45 than English. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at http://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on March 29, 2012. 59 Copyright Notice 61 Copyright (c) 2011 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (http://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Background and Introduction . . . . . . . . . . . . . . . . . 4 77 2. Overview of Saratoga File Transfer . . . . . . . . . . . . . . 6 78 3. Optional Parts of Saratoga . . . . . . . . . . . . . . . . . . 11 79 3.1. Optional but useful functions in Saratoga . . . . . . . . 11 80 3.2. Optional congestion control . . . . . . . . . . . . . . . 12 81 3.3. Optional functionality requiring other protocols . . . . . 12 82 4. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 4.1. BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 16 84 4.2. REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.3. METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 24 86 4.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 87 4.5. STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . 32 88 5. The Directory Entry . . . . . . . . . . . . . . . . . . . . . 39 89 6. Behaviour of a Saratoga Peer . . . . . . . . . . . . . . . . . 42 90 6.1. Saratoga Transactions . . . . . . . . . . . . . . . . . . 42 91 6.2. Beacons . . . . . . . . . . . . . . . . . . . . . . . . . 46 92 6.3. Upper-Layer Interface . . . . . . . . . . . . . . . . . . 46 93 6.4. Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 46 94 7. Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . 47 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 97 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 48 98 11. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 49 99 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 100 12.1. Normative References . . . . . . . . . . . . . . . . . . . 49 101 12.2. Informative References . . . . . . . . . . . . . . . . . . 49 102 Appendix A. Timestamp/Nonce field considerations . . . . . . . . 51 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 105 1. Background and Introduction 107 Saratoga is a file transfer and content dissemination protocol 108 capable of efficiently sending both small and very large files as 109 well as streaming continuous content. Saratoga was originally 110 designed for the purpose of large file transfer from small low-Earth- 111 orbit satellites. It has been used in daily operations since 2004 to 112 move mission imaging data files of the order of several hundred 113 megabytes each from the Disaster Monitoring Constellation (DMC) 114 remote-sensing satellites to ground stations. 116 The DMC satellites, built at the University of Surrey by Surrey 117 Satellite Technology Ltd (SSTL), all use IP for payload 118 communications and delivery of Earth imagery. At the time of this 119 writing, in September 2011, nine DMC satellites have been launched 120 into orbit since 2003, seven of those are currently operational in 121 orbit, and three more are planned. The DMC satellites use Saratoga 122 to provide Earth imagery under the aegis of the International Charter 123 on Space and Major Disasters. A pass of connectivity between a 124 satellite and ground station offers an 8-12 minute time window in 125 which to transfer imagery files using a minimum of an 8.1 Mbps 126 downlink and a 9.6 kbps uplink. The latest operational DMC 127 satellites have faster downlinks, capable of 20, 40, 80, 105 or 201 128 Mbps. Newer satellites are expected to use downlinks to 400 Mbps, 129 without significant increases in uplink rates. This high degree of 130 asymmetry, with the need to fully utilize the available downlink 131 capacity to move the volume of data required within the limited time 132 available, motivates much of Saratoga's design. 134 Further details on how these DMC satellites use IP to communicate 135 with the ground and the terrestrial Internet are discussed elsewhere 136 [Hogie05][Wood07a]. Saratoga is also being implemented for use in 137 high-speed private ground networks supporting radio astronomy sensors 138 [Wood11]. 140 Store-and-forward delivery relies on reliable hop-by-hop transfers of 141 files, removing the need for the final receiver to talk to the 142 original sender across long delays and allowing for the possibility 143 that an end-to-end path may never exist between sender and receiver 144 at any given time. Breaking an end-to-end path into multiple hops 145 allows data to be transferred as quickly as possible across each 146 link; congestion on a longer Internet path is then not detrimental to 147 the transfer rate on a space downlink. Use of store-and-forward hop- 148 by-hop delivery is typical of scenarios in space exploration for both 149 near-Earth and deep-space missions, and useful for other scenarios, 150 such as underwater networking, ad-hoc sensor networks, and some 151 message-ferrying relay scenarios. Saratoga is intended to be useful 152 for relaying data in these scenarios, and can optionally also be used 153 to carry the Bundle Protocol "bundles" that are proposed for use in 154 Delay and Disruption-Tolerant Networking (DTN) by the IRTF DTN 155 Research Group [RFC5050]. This has been tested from orbit using the 156 UK-DMC satellite [Ivancic10]. How Saratoga can optionally function 157 as a "bundle convergence layer" alongside a DTN bundle agent is 158 specified in a companion document [I-D.wood-dtnrg-saratoga]. 160 Saratoga contains a Selective Negative Acknowledgement (SNACK) 161 'holestofill' mechanism to provide reliable retransmission of data. 162 This is intended to correct losses of corrupted link-layer frames due 163 to channel noise over a space link. Packet losses in the DMC are due 164 to corruption introducing non-recoverable errors in the frame. The 165 DMC design uses point-to-point links and scheduling of applications 166 in order, so that the link is dedicated to one application transfer 167 at a time, meaning that packet loss cannot be due to congestion when 168 applications compete for link capacity simultaneously. In other 169 wireless environments that may be shared by many nodes and 170 applications, allocation of channel resources to nodes becomes a MAC- 171 layer function. Forward Error Coding (FEC) to get the most reliable 172 transmission through a channel is best left near the physical layer 173 so that it can be tailored for the channel. Use of FEC complements 174 Saratoga's transport-level negative-acknowledgement approach to 175 provide a reliable ARQ mechanism [RFC3366]. 177 Saratoga is scalable in that it is capable of efficiently 178 transferring small or large files, by choosing a width of file offset 179 descriptor appropriate for the filesize, and advertising accepted 180 offset descriptor sizes. 16-bit, 32-bit, 64-bit and 128-bit 181 descriptors can be selected, for maximum file sizes of 64KiB-1 (<64 182 kilobytes), 4GiB-1 (<4 gigabytes), 16EiB-1 (<16 exabytes) and 256 183 EiEiB-1 (<256 exa-exabytes) respectively. 185 Earth imaging files currently transferred by Saratoga are mostly up 186 to a few gigabytes in size. Some implementations do transfer more 187 than 4 GiB in size, and so require offset descriptors larger than 32 188 bits. We believe that supporting a 128-bit descriptor can satisfy 189 all future needs, but we expect current implementations to only 190 support up to 32-bit or 64-bit descriptors, depending on their 191 application needs. The 16-bit descriptor is useful for small 192 messages, including messages from 8-bit devices, and is always 193 supported. The 128-bit descriptor can be used for moving very large 194 files stored on a 128-bit filesystem, such as on OpenSolaris ZFS. 196 As a UDP-based protocol, Saratoga can be used with either IPv4 or 197 IPv6. Compatibility between Saratoga and the wide variety of links 198 that can already carry IP traffic is assured. 200 High link utilization is important during periods of limited 201 connectivity. Given that Saratoga was originally developed for 202 scheduled peer-to-peer communications over dedicated links in private 203 networks, where each application has the entire link for the duration 204 of its transfer, many Saratoga implementations deliberately lack any 205 form of congestion control and send at line rate to maximise 206 throughput and link utilisation in their limited, carefully 207 controlled, environments. In accordance with UDP Guidelines 208 [RFC5405] for protocols able to traverse the public Internet, newer 209 implementations may perform TCP-Friendly Rate Control (TFRC) 210 [RFC5348] or other congestion control mechanisms. This is described 211 further in [wood-tsvwg-saratoga-congestion-control]. 213 Saratoga was originally implemented as outlined in [Jackson04], but 214 the specification given here differs substantially, as we have added 215 a number of features while cleaning up the initial Saratoga 216 specification. The original Saratoga code uses a version number of 217 0, while code that implements this version of the protocol advertises 218 a version number of 1. Further discussion of the history and 219 development of Saratoga is given in [Wood07b]. 221 This document contains an overview of the transfer process and 222 transactions using Saratoga in Section 2, followed by a formal 223 definition of the packet types used by Saratoga in Section 4, and the 224 details of the various protocol mechanisms in Section 6. 226 Here, Saratoga transaction types are labelled with underscores around 227 lowercase names (such as a "_get_" transaction), while Saratoga 228 packet types are labelled in all capitals (such as a "REQUEST" 229 packet) in order to distinguish between the two. 231 The remainder of this specification uses 'file' as a shorthand for 232 'binary object', which may be a DTN bundle, or other type of data. 233 This specification uses 'file' when also discussing streaming of data 234 of indeterminate length. Saratoga uses unsigned integers in its 235 fields, and does not use signed types. 237 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 238 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 239 document are to be interpreted as described in RFC 2119. [RFC2119] 241 2. Overview of Saratoga File Transfer 243 Saratoga is a peer-to-peer protocol in the sense that multiple files 244 may be transferred in both directions simultaneously between two 245 communicating Saratoga peers, and there is not intended to be a 246 strict client-to-server relationship. 248 Saratoga nodes can act as simple file servers. Saratoga supports 249 several types of operations on files including "pull" downloads, 250 "push" uploads, directory listing, and deletion requests. Each 251 operation is handled as a distinct "transaction" between the peers. 253 Saratoga nodes MAY advertise their presence, capabilities, and 254 desires by sending BEACON packets. These BEACONs are sent to either 255 a reserved, unforwardable, multicast address when using IPv4, or a 256 link-local all-Saratoga-peers multicast address when using IPv6. A 257 BEACON might also be unicast to another known node as a sort of 258 "keepalive". Saratoga nodes may dynamically discover other Saratoga 259 nodes, either through listening for BEACONs, through pre- 260 configuration, via some other trigger from a user, lower-layer 261 protocol, or another process. The BEACON is useful in many 262 situations, such as ad-hoc networking, as a simple, explicit, 263 confirmation that another node is present; a BEACON is not required 264 in order to begin a Saratoga transaction. BEACONs have been used by 265 the DMC satellites to indicate to ground stations that a link has 266 become functional, a solid-state data recorder is online, and the 267 software is ready to transfer any requested files. 269 A Saratoga transaction begins with either a _get_, _put_, _getdir_, 270 or _delete_ transaction REQUEST packet corresponding to a desired 271 download, upload, directory listing, or deletion operation. _put_ 272 transactions may instead begin directly with METADATA and DATA, 273 without an initial REQUEST/OKAY STATUS exchange; these are known as 274 'blind puts'. The most common envisioned transaction is the _get_, 275 which begins with a single Saratoga REQUEST packet sent from the peer 276 wishing to receive the file, to the peer who currently has the file. 277 If the transaction is rejected, then a brief STATUS packet that 278 conveys rejection is generated. If the file-serving peer accepts the 279 transaction, an OKAY STATUS can be optional; the peer can immediately 280 generate and send a more useful descriptive METADATA packet, along 281 with some number of DATA packets constituting the requested file. 283 These DATA packets are finished by (and can intermittently include) a 284 DATA packet with a flag bit set that demands the file-receiver send a 285 reception report in the form of a STATUS packet. The STATUS packet 286 can include 'holestofill' Selective Negative Acknowledgement (SNACK) 287 information listing spans of octets within the file that have not yet 288 been received, as well as whether or not the METADATA packet was 289 received. Based on the information in this STATUS packet, the file- 290 sender can begin a cycle of selective retransmissions of missing DATA 291 packets, until it sees a STATUS packet that acknowledges total 292 reception of all file data. 294 In the example scenario in Figure 1, a _get_ request is granted. The 295 reliable file delivery experiences loss of a single DATA packet due 296 to channel-induced errors. 298 File-Receiver File-Sender 300 GET REQUEST ---------------------> 301 (indicates acceptance) <------- STATUS 302 <------- METADATA 303 <---------------------- DATA #1 304 STATUS -----------------> (voluntarily sent at start) 305 (lost) <------ DATA #2 306 <---------------------- DATA #3 (bit set 307 requesting STATUS) 308 STATUS -----------------> 309 (indicating that range in DATA #2 was lost) 310 <----------------------- DATA #2 (bit set 311 requesting STATUS) 312 STATUS -----------------> 313 (complete file and METADATA received) 315 Figure 1: Example _get_ transaction sequence 317 A _put_ is similar to _get_, although once the OKAY STATUS is 318 received, DATA is sent from the peer that originated the _put_ 319 request. A 'blind _put_' does not require an REQUEST and OKAY STATUS 320 to be exchanged before sending DATA packets, and is efficient for 321 long-delay or unidirectional links. 323 A _getdir_ request proceeds similarly, though the DATA transfer 324 contains a directory record with one or more directory entries, 325 described later, rather than a given file's bytes. _getdir_ is the 326 only request to also apply to directories, where one or more 327 directory entries for individual files is received. 329 The STATUS and DATA packets are allowed to be sent at any time within 330 the scope of a transaction, in order for the file-sending node to 331 optimize buffer management and transmission order. For example, if 332 the file-receiver already has the first part of a file from a 333 previous disrupted transfer, it may send a STATUS at the beginning of 334 the transaction indicating that it has the first part of the file, 335 and so only needs the last part of the file. Thus, efficient 336 recovery from interrupted sessions between peers becomes possible, 337 similar to ranged FTP and HTTP requests. (Note that METADATA with a 338 checksum is useful to verify that the parts are of the same file and 339 that the file is reassembled correctly.) 341 The Saratoga 'blind _put_' transaction is initiated by the file- 342 sender sending an optional METADATA packet followed by immediate DATA 343 packets, without requiring a REQUEST or waiting for a STATUS 344 response. This can be considered an "optimistic" mode of protocol 345 operation, as it assumes the implicit transaction request will be 346 granted. If the sender of a PUT request sees a STATUS packet 347 indicating that the request was declined, it MUST stop sending any 348 DATA packets within that transaction immediately. Since this type of 349 _put_ is open-loop for some period of time, it should not be used in 350 scenarios where congestion is a valid concern; in these cases, the 351 file-sender should wait on its METADATA to be acknowledged by a 352 STATUS before sending DATA packets within the transaction. 354 Figure 2 illustrates the sequence of packets in an example _put_ 355 transaction, beginning directly with METADATA and DATA as in a blind 356 put, where the second DATA packet is lost. Other than the way that 357 it is initiated, the mechanics of data delivery of a blind _put_ 358 transaction are similar to a _get_ transaction. 360 File-Sender File-Receiver 362 METADATA ----------------> 363 DATA #1 ----------------> 364 (transfer accepted) <---------- STATUS 365 DATA #2 ---> (lost) 366 DATA #3 (bit set ------------> 367 requesting STATUS) 368 (DATA #2 lost) <---------- STATUS 369 DATA #2 (bit set ------------> 370 requesting STATUS) 371 (transfer complete) <---------- STATUS 373 Figure 2: Example PUT transaction sequence 375 In deep-space scenarios, the large propagation delays and round-trip 376 times involved discourage use of ping-pong packet exchanges (such as 377 TCP's SYN/ACK) for starting transactions, and unidirectional 378 transfers via these optimistic 'blind _put_s' are desirable. Blind 379 _puts_ are the only mode of transfer suitable for unidirectional 380 links. Senders sending on unidirectional links SHOULD send a copy of 381 the METADATA in advance of DATA packets, and MAY resend METADATA at 382 intervals. 384 The _delete_ transactions are simple single packet requests that 385 trigger a STATUS packet with a status code that indicates whether the 386 file was deleted or not. If the file is not able to be deleted for 387 some reason, this reason can be conveyed in the Status field of the 388 STATUS packet. 390 A _get_ REQUEST packet that does not specify a filename (i.e. the 391 request contains a zero-length File Path field) is specially defined 392 to be a request for any chosen file that the peer wishes to send it. 393 This 'blind _get_' allows a Saratoga peer to request any files that 394 the other Saratoga peer has ready for it, without prior knowledge of 395 the directory listing, and without requiring the ability to examine 396 files or decode remote file names/paths for meaningful information 397 such as final destination. 399 If a file is larger than Saratoga can be expected to transfer during 400 a time-limited contact, there are at least two feasible options: 402 (1) The application can use proactive fragmentation to create 403 multiple smaller-sized files. Saratoga can transfer some number of 404 these smaller files fully during a contact. 406 (2) To avoid file fragmentation, a Saratoga file-receiver can retain 407 a partially-transferred file and request transfer of the unreceived 408 bytes during a later contact. This uses a STATUS packet to make 409 clear how much of the file has been successfully received and where 410 transfer should be resumed from, and relies on use of METADATA to 411 identify the file. On resumption of a transfer, the new METADATA 412 (including file length, file timestamps, and possibly a file 413 checksum) MUST match that of the previous METADATA in order to re- 414 establish the transfer. Otherwise, the file-receiver MUST assume 415 that the file has changed and purge the DATA payload received during 416 previous contacts. 418 Like the BEACON packets, a _put_ or a response to a _get_ MAY be sent 419 to the dedicated IPv4 Saratoga multicast address (allocated to 420 224.0.0.108) or the dedicated IPv6 link-local multicast address 421 (allocated to FF02:0:0:0:0:0:0:6C) for multiple file-receivers on the 422 link to hear. This is at the discretion of the file-sender, if it 423 believes that there is interest from multiple receivers. In-progress 424 DATA transfers MAY also be moved seamlessly from unicast to multicast 425 if the file-sender learns during a transfer, from receipt of further 426 unicast _get_ REQUEST packets, that multiple nodes are interested in 427 the file. The associated METADATA packet is multicast when this 428 transition takes place, and is then repeated periodically while the 429 DATA stream is being sent, to inform newly-arrived listeners about 430 the file being multicast. Acknowledgements MUST NOT be demanded by 431 multicast DATA packets, to prevent ack implosion at the file-sender, 432 and instead status SNACK information is aggregated and sent 433 voluntarily by all file-receivers. File-receivers respond to 434 multicast DATA with multicast STATUS packets. File-receivers SHOULD 435 introduce a short random delay before sending a multicast STATUS 436 packet, to prevent ack implosion after a channel-induced loss, and 437 MUST listen for STATUS packets from others, to avoid duplicating fill 438 requests. The file-sender SHOULD repeat any initial unicast portion 439 of the transfer as multicast last of all, and may repeat and cycle 440 through multicast of the file several times while file-receivers 441 express interest via STATUS or _get_ packets. Once in multicast and 442 with METADATA being repeated periodically, new file-receivers do not 443 need to send individual REQUEST packets. If a transfer has been 444 started using UDP-Lite and new receivers indicate UDP-only 445 capability, multicast transfers MUST switch to using UDP to 446 accommodate them. 448 3. Optional Parts of Saratoga 450 Implementing support for some parts of Saratoga is optional. These 451 parts are grouped into three sections, namely useful capabilities in 452 Saratoga that are likely to be supported by implementations, 453 congestion control that is needed in shared networks and across the 454 public Internet, and functionality requiring other protocols that is 455 less likely to be supported. 457 3.1. Optional but useful functions in Saratoga 459 These are useful capabilities in Saratoga that implementations SHOULD 460 support, but may not, depending on scenarios: 462 - sending and parsing BEACONs. 464 - sending and parsing METADATA. However, sending and receiving 465 METADATA is considered extremely useful, is strongly recommended, and 466 SHOULD be done. 468 - streaming data, including real-time streaming of content of unknown 469 length. This streaming can be unreliable (without resend requests) 470 or reliable (with resend requests). Session protocols such as http 471 expect reliable streaming, and can be used in delay-tolerant networks 472 [I-D.wood-dtnrg-http-dtn-delivery]. Although Saratoga data delivery 473 is inherently one-way, where a stream of DATA packets elicits a 474 stream of STATUS packets, bidirectional duplex communication can be 475 established by using two Saratoga transfers flowing in opposite 476 directions. 478 - multicast DATA transfers, if judged useful for the environment in 479 which Saratoga is deployed, when multiple receivers are participating 480 and are receiving the same file or stream. 482 - sending and parsing STATUS messages, which are expected for 483 bidirectional communication, but cannot be sent on and are not 484 required for sending over unidirectional links. 486 - sending and responding to packet timestamps in DATA and STATUS 487 packets. These timestamps are useful for streaming and for giving a 488 file-sender an indication of path latency for rate control. There is 489 no need for a file-receiver to understand the format used for these 490 timestamps for it to be able to receive them from and reflect them 491 back to the file-sender. 493 - support for descriptor sizes greater than 16 bits, for handling 494 small files, is optional, as is support for descriptor sizes greater 495 than 32 bits, and support for descriptor sizes greater than 64 bits. 496 If a decriptor size is implemented, all sizes below that size MUST be 497 implemented. 499 3.2. Optional congestion control 501 Saratoga can be implemented to perform congestion control at the 502 sender, based on feedback from acknowledgement STATUS packets 503 [wood-tsvwg-saratoga-congestion-control], or have the sender 504 configured to use simple open-loop rate control to only use a fixed 505 amount of link capacity. Congestion control is expected to be 506 undesirable for many of Saratoga's use cases and expected 507 environmental conditions in private networks, where sending as 508 quickly as possible or simple rate control at a fixed output speed 509 are considered useful. 511 In accordance with the UDP Guidelines [RFC5405], congestion control 512 MUST be supported if Saratoga is being used across the public 513 Internet, and SHOULD be supported in environments where links are 514 shared by traffic flows. Congestion control MAY NOT be supported 515 across private, single-flow links engineered for performance: 516 Saratoga's primary use case. 518 3.3. Optional functionality requiring other protocols 520 The functionality listed here is useful in rare cases, but requires 521 use of other, optional, protocols. This functionality MAY be 522 supported by Saratoga implementations: 524 - support for working with the Bundle Protocol for Delay-Tolerant 525 Networking. Saratoga can optionally also be used to carry the Bundle 526 Protocol "bundles" that is proposed for use in Delay and Disruption- 527 Tolerant Networking (DTN) by the IRTF DTN Research Group [RFC5050]. 528 The bundle agent acts as an application driving Saratoga. Use of a 529 filesystem is expected. This approach has been tested from orbit 530 using the UK-DMC satellite [Ivancic10]. How Saratoga can optionally 531 function as a "bundle convergence layer" alongside a DTN bundle agent 532 is specified in a companion document [I-D.wood-dtnrg-saratoga]. 534 - transfers permitting some errors in content delivered, using UDP- 535 Lite [RFC3828]. These can be useful for decreasing delivery time 536 over unreliable channels, especially for unidirectional links, or in 537 decreasing computational overhead for the UDP Lite checksum. Error 538 tolerance requires that lower-layer frames permit delivery of 539 unreliable data to be really useful. 541 If a file contains separate parts that require reliable transmission 542 without errors or that can tolerate errors in delivered content, 543 proactive fragmentation can be used to split the file into separate 544 reliable and unreliable files that can be transferred separately, 545 using UDP or UDP-Lite. 547 If parts of a file require reliability but the rest can be sent by 548 unreliable transfer, the file-sender can use its knowledge of the 549 internal file structure and vary DATA packet size so that the 550 reliable parts always start after the offset field and are covered by 551 the UDP-Lite checksum. 553 A file that permits unreliable delivery can be transferred onwards 554 using UDP. If the current sender does not understand the internal 555 file format to be able to decide what parts must be protected with 556 payload checksum coverage, the current sender or receiver does not 557 support UDP-Lite, or the current protocol stack only implements 558 error-free frame delivery below the UDP layer, then the file MAY be 559 delivered using UDP. 561 4. Packet Types 563 Saratoga is defined for use with UDP over either IPv4 or IPv6 564 [RFC0768]. UDP checksums, which are mandatory with IPv6, MUST be 565 used with IPv4. Within either version of IP datagram, a Saratoga 566 packet appears as a typical UDP header followed by an octet 567 indicating how the remainder of the packet is to be interpreted: 569 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 570 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 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 | UDP source port | UDP destination port | 573 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 574 | UDP length | UDP checksum | 575 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 576 |Ver|Packet Type| other Saratoga fields ... // 577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 579 Saratoga data transfers can also be carried out using UDP-Lite 580 [RFC3828]. If Saratoga can be carried over UDP-Lite, the 581 implementation MUST also support UDP. All packet types except DATA 582 MUST be sent using UDP with checksums turned on. For reliable 583 transfers, DATA packets are sent using UDP with checksums turned on. 584 For files where unreliable transfer has been indicated as desired and 585 possible, the sender MAY send DATA packets unreliably over UDP-Lite, 586 where UDP-Lite protects only the Saratoga headers and parts of the 587 file that must be transmitted reliably. 589 The three-bit Saratoga version field ("Ver") identifies the version 590 of the Saratoga protocol that the packet conforms to. The value 001 591 should be used in this field for implementations conforming to the 592 specification in this document, which specifies version 1 of 593 Saratoga. The value 000 was used in earlier implementations, prior 594 to the formal specification and public submission of the protocol 595 design, and is incompatible with version 001 in many respects. 597 The six-bit Saratoga "Packet Type" field indicates how the remainder 598 of the packet is intended to be decoded and processed: 600 +---+----------+----------------------------------------------------+ 601 | # | Type | Use | 602 +---+----------+----------------------------------------------------+ 603 | 0 | BEACON | Beacon packet indicating peer status. | 604 | 1 | REQUEST | Commands peer to start a transfer. | 605 | 2 | METADATA | Carries file transfer metadata. | 606 | 3 | DATA | Carries octets of file data. | 607 | 4 | STATUS | responds to REQUEST or DATA. Can signal list of | 608 | | | unreceived data to sender during a transfer. | 609 +---+----------+----------------------------------------------------+ 611 Several of these packet types include a Flags field, for which only 612 some of the bits have defined meanings and usages in this document. 613 Other, undefined, bits may be reserved for future use. Following the 614 principle of being conservative in what you send and liberal in what 615 you accept, a packet sender MUST set any undefined bits to zero, and 616 a packet recipient MUST NOT rely on these undefined bits being zero 617 on reception. 619 The specific formats for the different types of packets are given in 620 this section. Some packet types contain file offset descriptor 621 fields, which contain unsigned integers. The lengths of the offset 622 descriptors are fixed within a transfer, but vary between file 623 transfers. The size is set for each particular transfer, depending 624 on the choice of offset descriptor width made in the METADATA packet, 625 which in turn depends on the size of file being transferred. 627 In this document, all of the packet structure figures illustrating a 628 packet format assume 32-bit lengths for these offset descriptor 629 fields, and indicate the transfer-dependent length of the fields by 630 using a "(descriptor)" designation within the [field] in all packet 631 diagrams. That is: 633 The example 32-bit descriptors shown in all diagrams here 635 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 636 [ (descriptor) ] 637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 639 are suitable for files of up to 4GiB - 1 octets in length, and may be 640 replaced in a file transfer by descriptors using a different length, 641 depending on the size of file to be transferred: 643 16-bit descriptor for short files of up to 64KB - 1 octets in size 644 (MUST be supported) 646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 647 [ (descriptor) ] 648 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 650 64-bit descriptor for longer files of up to 16EiB - 1 octets in size 651 (optional) 653 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 654 [ (descriptor) / 655 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 656 / (descriptor, continued) ] 657 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 659 128-bit descriptor for very long files of up to 256 EiEiB - 1 octets 660 in size (optional) 662 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 663 [ (descriptor) / 664 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 665 / (descriptor, continued) / 666 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 667 / (descriptor, continued) / 668 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 669 / (descriptor, continued) ] 670 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 672 Descriptors are used for the descriptor size less one octet, e.g. 16- 673 bit for files up to 64KB - 1 octets in size, before switching to the 674 larger descriptor, e.g. using the 32-bit descriptor for a 64KB file 675 and larger. 677 For offset descriptors and types of content being transferred, the 678 related flag bits in BEACON and REQUEST indicate capabilities, while 679 in METADATA and DATA those flag bits are used slightly differently, 680 to indicate the content being transferred. 682 Saratoga packets are intended to fit within link MTUs to avoid the 683 inefficiencies and overheads of lower-layer fragmentation. A 684 Saratoga implementation itself does not perform any form of MTU 685 discovery, but is assumed to be configured with knowledge of usable 686 maximum IP MTUs for the link interfaces it uses. 688 4.1. BEACON 690 BEACON packets may be multicast periodically by nodes willing to act 691 as Saratoga peers, or unicast to individual peers to indicate 692 properties for that peer. Some implementations have sent BEACONS 693 every 100 milliseconds, but this rate is arbitrary, and should be 694 chosen to be appropriate for the environment and implementation. 696 The main purpose for sending BEACONs is to announce the presence of 697 the node to potential peers (e.g. satellites, ground stations) to 698 provide automatic service discovery, and also to confirm the activity 699 or presence of the peer. 701 The Endpoint Identifier (EID) in the BEACON serves to uniquely 702 identify the Saratoga peer. Whenever the Saratoga peer begins using 703 a new IP address, it SHOULD issue a BEACON on it and repeat the 704 BEACON periodically, to enable listeners to associate the IP address 705 with the EID and the peer. 707 Format 709 0 1 2 3 710 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 711 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 712 |0 0 1| Type | Flags | 713 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 714 [[ Available free space (optional) ]] 715 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 716 | Endpoint identifier... // 717 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 719 where 720 +------------+------------------------------------------------------+ 721 | Field | Description | 722 +------------+------------------------------------------------------+ 723 | Type | 0 | 724 | Flags | convey whether or not the peer is ready to | 725 | | send/receive, what the maximum supported file size | 726 | | range and descriptor is, and whether and how free | 727 | | space is indicated. | 728 | Available | This optional field can be used to indicate the | 729 | free space | current free space available for storage. | 730 | Endpoint | This can be used to uniquely identify the sending | 731 | identifier | Saratoga peer, or the administrative node that the | 732 | | BEACON-sender is associated with. If Saratoga is | 733 | | being used with a bundle agent, a bundle endpoint ID | 734 | | (EID) can be used here. | 735 +------------+------------------------------------------------------+ 737 The Flags field is used to provide some additional information about 738 the peer. The first two octets of the Flags field is currently in 739 use. The later octet is for future use, and MUST be set to zero. 741 The two highest-order bits (bits 8 and 9 above) indicate the maximum 742 supported file size parameters that the peer's Saratoga 743 implementation permits. Other Saratoga packet types contain 744 variable-length fields that convey file sizes or offsets into a file 745 -- the file offset descriptors. These descriptors may be 16-bit, 32- 746 bit, 64-bit, or 128-bit in length, depending on the size of the file 747 being transferred and/or the integer types supported by the sending 748 peer. The indicated bounds for the possible values of these bits are 749 summarized below: 751 +-------+-------+-------------------------+-------------------+ 752 | Bit 8 | Bit 9 | Supported Field Sizes | Maximum File Size | 753 +-------+-------+-------------------------+-------------------+ 754 | 0 | 0 | 16 bits | 2^16 - 1 octets. | 755 | 0 | 1 | 16 or 32 bits | 2^32 - 1 octets. | 756 | 1 | 0 | 16, 32, or 64 bits | 2^64 - 1 octets. | 757 | 1 | 1 | 16, 32, 64, or 128 bits | 2^128 - 1 octets. | 758 +-------+-------+-------------------------+-------------------+ 760 If a Saratoga peer advertises it is capable of receiving a certain 761 size of file, then it MUST also be capable of receiving files sent 762 using smaller descriptor values. This avoids overhead on small 763 files, while increasing interoperability between peers. 765 It is likely when sending unbounded streams that a larger offset 766 descriptor field size will be preferred to minimise problems with 767 offset sequence numbers wrapping. Protecting against sequence number 768 wrapping is discussed in the STATUS section. 770 +-----+-------+-----------------------------------------------------+ 771 | Bit | Value | Meaning | 772 +-----+-------+-----------------------------------------------------+ 773 | 10 | 0 | not able to pass bundles to a local bundle agent; | 774 | | | handles files only. | 775 | 10 | 1 | handles files, but can also pass marked bundles to | 776 | | | a local bundle agent. | 777 +-----+-------+-----------------------------------------------------+ 779 Bit 10 is reserved for DTN bundle agent use, indicating whether the 780 sender is capable of handling bundles via a local bundle agent. This 781 is described in [I-D.wood-dtnrg-saratoga]. 783 +-----+-------+--------------------------------------+ 784 | Bit | Value | Meaning | 785 +-----+-------+--------------------------------------+ 786 | 11 | 0 | not capable of supporting streaming. | 787 | 11 | 1 | capable of supporting streaming. | 788 +-----+-------+--------------------------------------+ 790 Bit 11 is used to indicate whether the sender is capable of sending 791 and receiving continuous streams. 793 +--------+--------+------------------------------------------------+ 794 | Bit 12 | Bit 13 | Capability and willingness to send files | 795 +--------+--------+------------------------------------------------+ 796 | 0 | 0 | cannot send files at all. | 797 | 0 | 1 | invalid. | 798 | 1 | 0 | capable of sending, but not willing right now. | 799 | 1 | 1 | capable of and willing to send files. | 800 +--------+--------+------------------------------------------------+ 802 +-------+-------+---------------------------------------------------+ 803 | Bit | Bit | Capability and willingness to receive files | 804 | 14 | 15 | | 805 +-------+-------+---------------------------------------------------+ 806 | 0 | 0 | cannot receive files at all. | 807 | 0 | 1 | invalid. | 808 | 1 | 0 | capable of receiving, but unwilling. Will reject | 809 | | | METADATA or DATA packets. | 810 | 1 | 1 | capable of and willing to receive files. | 811 +-------+-------+---------------------------------------------------+ 813 Also in the Flags field, bits 12 and 14 act as capability bits, while 814 bits 13 and 15 augment those flags with bits indicating current 815 willingness to use the capability. 817 Bits 12 and 13 deal with sending, while bits 14 and 15 deal with 818 receiving. If bit 12 is set, then the peer has the capability to 819 send files. If bit 14 is set, then the peer has the capability to 820 receive files. Bits 13 and 15 indicate willingness to send and 821 receive files, respectively. 823 A peer that is able to act as a file-sender MUST set the capability 824 bit 12 in all BEACONs that it sends, regardless of whether it is 825 willing to send any particular files to a particular peer at a 826 particular time. Bit 13 indicates the current presence of data to 827 send and a willingness to send it in general, in order to augment the 828 capability advertised by bit 12. 830 If bit 14 is set, then the peer is capable of acting as a receiver, 831 although it still might not currently be ready or willing to receive 832 files (for instance, it may be low on free storage). This bit MUST 833 be set in any BEACON packets sent by nodes capable of acting as file- 834 receivers. Bit 15 augments this by expresses a current general 835 willingness to receive and accept files. 837 +-----+-------+-----------------------------------------------------+ 838 | Bit | Value | Meaning | 839 +-----+-------+-----------------------------------------------------+ 840 | 16 | 0 | supports DATA transfers over UDP only. | 841 | 16 | 1 | supports DATA transfers over both UDP and UDP-Lite. | 842 +-----+-------+-----------------------------------------------------+ 844 Bit 16 is used to indicate whether the sender is capable of sending 845 and receiving unreliable transfers via UDP-Lite. 847 +-----+-------+-----------------------------------------------------+ 848 | Bit | Value | Meaning | 849 +-----+-------+-----------------------------------------------------+ 850 | 17 | 0 | available free space is not advertised in this | 851 | | | BEACON. | 852 | 17 | 1 | available free space is advertised in this BEACON. | 853 +-----+-------+-----------------------------------------------------+ 855 Bit 17 is used to indicate whether the sender is indicating how much 856 free space is indicated in an optional field in this BEACON packet. 857 If bit 17 is set, then bits 18 and 19 are used to indicate the size 858 in bits of the optional free-space-size field. If bit 17 is not set, 859 then bits 18 and 19 are zero. 861 +--------+--------+--------------------------+ 862 | Bit 18 | Bit 19 | Size of free space field | 863 +--------+--------+--------------------------+ 864 | 0 | 0 | 16 bits. | 865 | 0 | 1 | 32 bits. | 866 | 1 | 0 | 64 bits. | 867 | 1 | 1 | 128 bits. | 868 +--------+--------+--------------------------+ 870 The free space field size can vary as indicated by a varying-size 871 field indicated in bits 18 and 19 of the flags field. Unlike other 872 offset descriptor use where the value in the descriptor indicates a 873 byte or octet position for retransmission, or gives a file size in 874 bytes, this particular field indicates the available free space in 875 KILOBYTES (KiB, multiples of 1024 octets), rather than octets. 876 (Kilobytes are used as storage can be in local memory.) Available 877 free space is rounded down to the nearest KiB, so advertising zero 878 means that less than 1KiB is free and available. Advertising the 879 maximum size possible in the field means that more free space than 880 that is available. While this field is intended to be scalable, it 881 is expected that 32 bits (up to 4TiB) will be most common in use. 883 A BEACON unicast to an individual peer MAY choose to indicate the 884 free space available for use by that particular peer, and MAY 885 indicate capabilities only available to that particular peer, 886 overriding or supplementing the properties advertised to all local 887 peers by multicast BEACONs. 889 Any type of host identifier can be used in the endpoint identifier 890 field, as long as it is a reasonably unique string within the range 891 of operational deployment. This field encompasses the remainder of 892 the packet, and might contain non-UTF-8 and/or null characters. 894 4.2. REQUEST 896 A REQUEST packet is an explicit command to perform either a _get_, 897 _getdir_, or _delete_ transaction. 899 Format 901 0 1 2 3 902 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 903 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 904 |0 0 1| Type | Flags | Request Type | 905 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 906 | Id | 907 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 908 | variable-length File Path ... / 909 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 910 / / 911 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 912 / | null byte | / 913 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 914 / variable-length Authentication Field (optional) | 915 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 917 where 919 +---------+---------------------------------------------------------+ 920 | Field | Description | 921 +---------+---------------------------------------------------------+ 922 | Type | 1 | 923 | Flags | provide additional information about the requested | 924 | | file/operation; see table below for definition. | 925 | Request | identifies the type of request being made; see table | 926 | Type | further below for request values. | 927 | Id | uniquely identifies the transaction between two peers. | 928 | File | the path of the requested file/directory following the | 929 | Path | rules described below. | 930 +---------+---------------------------------------------------------+ 932 The Id that is used during transactions serves to uniquely associate 933 a given packet with a particular transaction. This enables multiple 934 simultaneous data transfer or request/status transactions between two 935 peers, with each peer deciding how to multiplex and prioritise the 936 parallel flows it sends. The Id for a transaction is selected by the 937 initiator so as to not conflict with any other in-progress or recent 938 transactions with the same host. This Id should be unique and 939 generated using properties of the file, which will remain constant 940 across a host reboot. The 3-tuple of both host identifiers and a 941 carefully-generated transaction Id field can be used to uniquely 942 index a particular transaction's state. 944 In the Flags field, the bits labelled 8 and 9 in the figure above 945 indicate the maximum supported file length fields that the peer can 946 handle, and are interpreted exactly as the bits 8 and 9 in the BEACON 947 packet described above. Bits 12 and 13, and 14 and 15, indicate 948 capability and willingness to send and receive files, as described 949 above. Making a _get_ request would require that the requester is 950 capable and willing to receive files. The remaining defined 951 individual bits are as summarised as follows: 953 +-----+-------+-----------------------------------------------------+ 954 | Bit | Value | Meaning | 955 +-----+-------+-----------------------------------------------------+ 956 | 10 | 0 | The requester cannot handle bundles locally. | 957 | 10 | 1 | The requester can handle bundles. | 958 | 11 | 0 | The requester cannot receive streams. | 959 | 11 | 1 | The requester is also able to receive streams. | 960 | 16 | 0 | The requester is able to receive DATA over UDP | 961 | | | only. | 962 | 16 | 1 | The requester is also able to receive DATA over | 963 | | | UDP-Lite. | 964 +-----+-------+-----------------------------------------------------+ 966 The Request Type field is an octet that contains a value indicated 967 the type of request being made. Possible values are: 969 +-------+-----------------------------------------------------------+ 970 | Value | Meaning | 971 +-------+-----------------------------------------------------------+ 972 | 0 | No action is to be taken; similar to a BEACON. | 973 | 1 | A _get_ transaction is requested. The File Path field | 974 | | holds the name of the file to be sent. | 975 | 2 | A _put_ transaction is requested. The File Path field | 976 | | suggests the name of the file that will be delivered only | 977 | | after an OK STATUS is received from the file receiver. | 978 | 3 | A _get_ transaction is requested, and once received | 979 | | successfully, the original copy should be deleted. The | 980 | | File Path field holds the name of the file to be sent. | 981 | | (This get+delete is known as a 'take'.) | 982 | 4 | A _put_ transaction is requested, and once sent | 983 | | successfully, the original copy will be deleted. The | 984 | | File Path field holds the name of the file to be sent. | 985 | | (This put+delete is known as a 'give'.) | 986 | 5 | A _delete_ transaction is requested, and the File Path | 987 | | field specifies the name of the file to be deleted. | 988 | 6 | A _getdir_ transaction is requested. The File Path field | 989 | | holds the name of the directory or file on which the | 990 | | directory record is created. | 991 +-------+-----------------------------------------------------------+ 993 The File Path portion of a _get_ packet is a null-terminated UTF-8 994 encoded string [RFC3629] that represents the path and base file name 995 on the file-sender of the file (or directory) that the file-receiver 996 wishes to perform the _get_, _getdir_, or _delete_ operation on. 997 Implementations SHOULD only send as many octets of File Path as are 998 needed for carrying this string, although some implementations MAY 999 choose to send a fixed-size File Path field in all REQUEST packets 1000 that is filled with null octets after the last UTF-8 encoded octet of 1001 the path. A maximum of 1024 octets for this field, and for the File 1002 Path fields in other Saratoga packet types, is used to limit the 1003 total packet size to within a single IPv6 minimum MTU (minus some 1004 padding for network layer headers), and thus avoid the need for 1005 fragmentation. The 1024-octet maximum applies after UTF-8 encoding 1006 and null termination. 1008 As in the standard Internet File Transfer Protocol (FTP) [RFC0959], 1009 for path separators, Saratoga allows the local naming convention on 1010 the peers to be used. There are security implications to processing 1011 these strings without some intelligent filtering and checking on the 1012 filesystem items they refer to, as discussed in the Security 1013 Considerations section later within this document. 1015 If the File Path field is empty, i.e. is a null-terminated zero- 1016 length string one octet long, then this indicates that the file- 1017 receiver is ready to receive any file that the file-sender would like 1018 to send it, rather than requesting a particular file. This allows 1019 the file-sender to determine the order and selection of files that it 1020 would like to forward to the receiver in more of a "push" manner. Of 1021 course, file retrieval could also follow a "pull" manner, with the 1022 file-receiving host requesting specific files from the file-sender. 1023 This may be desirable at times if the file-receiver is low on storage 1024 space, or other resources. The file-receiver could also use the 1025 Saratoga _getdir_ transaction results in order to select small files, 1026 or make other optimizations, such as using its local knowledge of 1027 contact times to pick files of a size likely to be able to be 1028 delivered completely. File transfer through pushing sender-selected 1029 files implements delivery prioritization decisions made solely at the 1030 Saratoga file-sending node. File transfer through pulling specific 1031 receiver-selected files implements prioritization involving more 1032 participation from the Saratoga file-receiver. This is how Saratoga 1033 implements Quality of Service (QoS). 1035 The null-terminated File Path string MAY be followed by an optional 1036 Authentication Field that can be used to validate the REQUEST packet. 1037 Any value in the Authentication Field is the result of a computation 1038 of packet contents that SHOULD include, at a minimum, source and 1039 destination IP addresses and port numbers and packet length in a 1040 'pseudo-header', as well as the content of all Saratoga fields from 1041 Version to File Path, excluding the predictable null-termination 1042 octet. This Authentication Field can be used to allow the REQUEST 1043 receiver to discriminate between other peers, and permit and deny 1044 various REQUEST actions as appropriate. The format of this field is 1045 unspecified for local use. 1047 Combined get+delete (take) and put+delete (give) requests should only 1048 have the delete carried out once the deleting peer is certain that 1049 the file-receiver has a good copy of the file. This may require the 1050 file receiver to verify checksums before sending a final STATUS 1051 message acknowledging successful delivery of the final DATA segment, 1052 or aborting the transfer if the checksum fails. If the transfer 1053 fails and an error STATUS is sent for any reason, the file should not 1054 be deleted. 1056 REQUEST packets may be sent multicast, to learn about all listening 1057 nodes. A multicast _get_ request for a file that elicits multiple 1058 METADATA or DATA responses should be followed by unicast STATUS 1059 packets with status errors cancelling all but one of the proposed 1060 transfers. File timestamps in the Directory Entry can be used to 1061 select the most recent version of an offered file, and the host to 1062 fetch it from. 1064 If the receiver already has the file at the expected file path and is 1065 requesting an update to that file, REQUEST can be sent after a 1066 METADATA advertising that file, to allow the sender to determine 1067 whether a replacement for the file should be sent. 1069 Delete requests are ignored for files currently being transferred. 1071 4.3. METADATA 1073 METADATA packets are sent as part of a data transfer transaction 1074 (_get_, _getfile_, and _put_). A METADATA packet says how large the 1075 file is and what its name is, as well as what size of file offset 1076 descriptor is chosen for the session. METADATA packets are optional. 1077 They are normally sent at the start of a DATA transfer, but may be 1078 repeated if requested. 1080 Format 1082 0 1 2 3 1083 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1084 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1085 |0 0 1| Type | Flags |Sumleng|Sumtype| 1086 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1087 | Id | 1088 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1089 | / 1090 / / 1091 / example error-detection checksum (128-bit MD5 shown) / 1092 / / 1093 / | 1094 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1095 | / 1096 / single Directory Entry describing file / 1097 / (variable length) / 1098 / // 1099 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1101 where 1103 +-----------+-------------------------------------------------------+ 1104 | Field | Description | 1105 +-----------+-------------------------------------------------------+ 1106 | Type | 2 | 1107 | Flags | indicate additional boolean metadata about a file. | 1108 | Sumleng | indicates the length of a checksum, as a multiple of | 1109 | | 32 bits. | 1110 | Sumtype | indicates whether a checksum is present after the Id, | 1111 | | and what type it is. | 1112 | Id | identifies the transaction that this packet | 1113 | | describes. | 1114 | Checksum | an example included checksum covering file contents. | 1115 | Directory | describes file system information about the file, | 1116 | Entry | including file length, file timestamps, etc.; the | 1117 | | format is specified in Section 5. | 1118 +-----------+-------------------------------------------------------+ 1120 The first octet of the Flags field is currently specified for use. 1121 The later two octets are reserved for future use, and MUST be set to 1122 zero. 1124 In the Flags field, the bits labelled 8 and 9 in the figure above 1125 indicate the exact size of the offset descriptor fields used in this 1126 particular packet and are interpreted exactly as the bits 8 and 9 in 1127 the BEACON packet described above. The value of these bits 1128 determines the size of the File Length field in the current packet, 1129 as well as indicating the size of the offset fields used in DATA and 1130 STATUS packets within the session that will follow this packet. 1132 +--------+--------+-------------------------------------------------+ 1133 | Bit 10 | Bit 11 | Type of transfer | 1134 +--------+--------+-------------------------------------------------+ 1135 | 0 | 0 | a file is being sent. | 1136 | 0 | 1 | the file being sent should be interpreted as a | 1137 | | | Directory Record. | 1138 | 1 | 0 | a bundle is being sent. | 1139 | 1 | 1 | an indefinite-length stream is being sent. | 1140 +--------+--------+-------------------------------------------------+ 1142 Also inside the Flags field, bits 10 and 11 indicate what is being 1143 transferred - a file, special directory record file that contains one 1144 or more directory entries, bundle, or stream. The value 01 indicates 1145 that the METADATA and DATA packets are being generated in response to 1146 a _getdir_ REQUEST, and that the assembled DATA contents should be 1147 interpreted as a Directory Record containing directory entries, as 1148 defined in Section 5. 1150 +-----+-------+-----------------------------------------------------+ 1151 | Bit | Value | Meaning | 1152 +-----+-------+-----------------------------------------------------+ 1153 | 12 | 0 | This transfer is in progress. | 1154 | 12 | 1 | This transfer is no longer in progress, and has | 1155 | | | been terminated. | 1156 +-----+-------+-----------------------------------------------------+ 1158 Bit 12 indicates whether the transfer is in progress, or has been 1159 terminated by the sender. It is normally set to 1 only when METADATA 1160 is resent to indicate that a stream transfer has been ended. 1162 +--------+----------------------------------------------------------+ 1163 | Bit 13 | Use | 1164 +--------+----------------------------------------------------------+ 1165 | 0 | This file's content MUST be delivered reliably without | 1166 | | errors using UDP. | 1167 | 1 | This file's content MAY be delivered unreliably, or | 1168 | | partly unreliably, where errors are tolerated, using | 1169 | | UDP-Lite. | 1170 +--------+----------------------------------------------------------+ 1172 Bit 13 indicates whether the file must be sent reliably or can be 1173 sent at least partly unreliably, using UDP-Lite. This flag SHOULD 1174 only be set if the originator of the file knows that at least some of 1175 the file content is suitable for sending unreliably and is robust to 1176 errors. This flag reflects a property of the file itself. This flag 1177 may still be set if the immediate file-receiver is only capable of 1178 UDP delivery, on the assumption that this preference will be 1179 preserved for later transfers where UDP-Lite transfers may be taken 1180 advantage of by senders with knowledge of the internal file 1181 structure. The file-sender may know that the receiver is capable of 1182 handling UDP-Lite, either from a _get_ REQUEST, from exchange of 1183 BEACONs, or a-priori. 1185 The high four bits of the Flags field, bits 28-31, are used to 1186 indicate if an error-detection checksum has been included in the 1187 METADATA for the file to be transferred. Here, bits 0000 indicate 1188 that no checksum is present, with the implicit assumption that the 1189 application will do its own end-to-end check. Other values indicate 1190 the type of checksum to use. The choice of checksum depends on the 1191 available computing power and the length of the file to be 1192 checksummed. Longer files require stronger checksums to ensure 1193 error-free delivery. The checksum of the file to be transferred is 1194 carried as shown, with a fixed-length field before the varying-length 1195 File Length and File Name information fields. 1197 Assigned values for the checksum type field are: 1199 +-----------+-------------------------------------------------------+ 1200 | Value | Use | 1201 | (0-15) | | 1202 +-----------+-------------------------------------------------------+ 1203 | 0 | No checksum is provided. | 1204 | 1 | 32-bit CRC32 checksum, suitable for small files. | 1205 | 2 | 128-bit MD5 checksum, suitable for larger files. | 1206 | 3 | 160-bit SHA-1 checksum, suitable for larger files but | 1207 | | slower to process than MD5. | 1208 +-----------+-------------------------------------------------------+ 1210 The length of the checksum cannot be inferred from the checksum type 1211 field, particularly for unknown checksum types. The next-highest 1212 four bits of the 32-bit word holding the Flags, bits 24-27, indicate 1213 the length of the checksum bit field, as a multiple of 32 bits. 1215 +----------------------+--------------------------------------+ 1216 | Example Value (0-15) | Use | 1217 +----------------------+--------------------------------------+ 1218 | 0 | No checksum is provided. | 1219 | 1 | 32-bit checksum field, e.g. CRC32. | 1220 | 4 | 128-bit checksum field, e.g. MD5. | 1221 | 5 | 160-bit checksum field, e.g. SHA-1. | 1222 +----------------------+--------------------------------------+ 1224 For a 32-bit CRC, the length field holds 1 and the type field holds 1225 1. For MD5, the length field holds 4 and the type field holds 2. 1226 For SHA-1, the length field holds 5 and the type field holds 3. 1228 It is expected that higher values will be allocated to new and 1229 stronger checksums able to better protect larger files. These 1230 checksums can be expected to be longer, with larger checksum length 1231 fields. 1233 A checksum SHOULD be included for files being transferred. The 1234 checksum SHOULD be as strong as possible. Streaming of an 1235 indefinite-length stream MUST set the checksum type field to zero. 1237 It is expected that a minimum of the MD5 checksum will be used, 1238 unless the Saratoga implementation is used exclusively for small 1239 transfers at the low end of the 16-bit file descriptor range, such as 1240 on low-performing hardware, where the weaker CRC-32c checksum can 1241 suffice. 1243 The CRC32 checksum is computed as described for the CRC-32c algorithm 1244 given in [RFC3309]. 1246 The MD5 Sum field is generated via the MD5 algorithm [RFC1321], 1247 computed over the entire contents of the file being transferred. The 1248 file-receiver can compute the MD5 result over the reassembled 1249 Saratoga DATA packet contents, and compare this to the METADATA's MD5 1250 Sum field in order to gain confidence that there were no undetected 1251 protocol errors or UDP checksum weaknesses encountered during the 1252 transfer. Although MD5 is known to be less than optimal for security 1253 uses, it remains excellent for non-security use in error detection 1254 (as is done here in Saratoga), and has better performance 1255 implications than cryptographically-stronger alternatives given the 1256 limited available processing of many use cases [RFC6151]. 1258 Checksums may be privately keyed for local use, to allow transmission 1259 of authenticated or encrypted files delivered in DATA packets. This 1260 has limitations, discussed further in Section 8 at end. 1262 Use of the checksum to ensure that a file has been correctly relayed 1263 to the receiving node is important. A provided checksum MUST be 1264 checked against the received data file. If checksum verification 1265 fails, either due to corruption or due to the receiving node not 1266 having the right key for a keyed checksum), the file MUST be 1267 discarded. If the file is to be relayed onwards later to another 1268 Saratoga peer, the metadata, including the checksum, MUST be retained 1269 with the file and SHOULD be retransmitted onwards unchanged with the 1270 file for end-to-end coverage. If it is necessary to recompute the 1271 checksum or encrypted data for the new peer, either because a 1272 different key is in use or the existing checksum algorithm is not 1273 supported, the new checksum MUST be computed before the old checksum 1274 is verified, to ensure overlapping checksum coverage and detect 1275 errors introduced in file storage. 1277 METADATA can be used as an indication to update copies of files. If 1278 the METADATA is in response to a _get_ REQUEST including a file 1279 record, and the record information for the held file matches what the 1280 requester already has, as has been indicated by a previously-received 1281 METADATA advertisement from the requester, then only the METADATA is 1282 sent repeating this information and verifying that the file is up to 1283 date. If the record information does not match and a newer file can 1284 be supplied, the METADATA begins a transfer with following DATA 1285 packets to update the file. 1287 4.4. DATA 1289 A series of DATA packets form the main part of a data transfer 1290 transaction (_get_, _put_, or _getdir_). The payloads constitute the 1291 actual file data being transferred. 1293 Format 1295 0 1 2 3 1296 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 1297 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1298 |0 0 1| Type | Flags | 1299 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1300 | Id | 1301 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1302 | / 1303 / Timestamp/nonce information (optional) / 1304 / / 1305 / | 1306 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1307 [ Offset (descriptor) ] 1308 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1309 | Payload data... // 1310 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1312 where 1313 +-----------------+-------------------------------------------------+ 1314 | Field | Description | 1315 +-----------------+-------------------------------------------------+ 1316 | Type | 3 | 1317 | Flags | are described below. | 1318 | Id | identifies the transaction to which this packet | 1319 | | belongs. | 1320 | Timestamp/nonce | is an optional 128-bit field providing timing | 1321 | | or identification information unique to this | 1322 | | packet. See Appendix A for details. | 1323 | Offset | the offset in octets to the location where the | 1324 | | first byte of this packet's payload is to be | 1325 | | written. | 1326 +-----------------+-------------------------------------------------+ 1328 The DATA packet has a minimum size of ten octets, using sixteen-bit 1329 descriptors and no timestamps. 1331 DATA packets are normally checked by the UDP checksum to prevent 1332 errors in either the header or the payload content. However, for 1333 transfers that can tolerate content errors, DATA packets MAY be sent 1334 using UDP-Lite. If UDP-Lite is used, the file-sender must know that 1335 the file-receiver is capable of handling UDP-Lite, and the file 1336 contents to be transferred should be resilient to errors. The UDP- 1337 Lite checksum MUST protect the Saratoga headers, up to and including 1338 the offset descriptor, and MAY protect more of each packet's payload, 1339 depending on the file-sender's knowledge of the internal structure of 1340 the file and the file's reliability requirements. 1342 +-------+-------+--------------------------------------------------+ 1343 | Bit 8 | Bit 9 | Type of transfer | 1344 +-------+-------+--------------------------------------------------+ 1345 | 0 | 0 | 16-bit descriptors are in use in this transfer. | 1346 | 0 | 1 | 32-bit descriptors are in use in this transfer. | 1347 | 1 | 0 | 64-bit descriptors are in use in this transfer. | 1348 | 1 | 1 | 128-bit descriptors are in use in this transfer. | 1349 +-------+-------+--------------------------------------------------+ 1351 Flag bits 8 and 9 are set to indicate the size of the offset 1352 descriptor as described for BEACON and METADATA packets, so that each 1353 DATA packet is self-describing. This allows the DATA packet to be 1354 used to construct a file even when an initial METADATA is lost and 1355 must be resent. The flag values for bits 8 and 9 MUST be the same as 1356 indicated in any expected METADATA packet. 1358 +--------+--------+-------------------------------------------------+ 1359 | Bit 10 | Bit 11 | Type of transfer | 1360 +--------+--------+-------------------------------------------------+ 1361 | 0 | 0 | a file is being sent. | 1362 | 0 | 1 | the file being sent should be interpreted as a | 1363 | | | directory record. | 1364 | 1 | 0 | a bundle is being sent. | 1365 | 1 | 1 | an indefinite-length stream is being sent. | 1366 +--------+--------+-------------------------------------------------+ 1368 Also inside the Flags field, bits 10 and 11 indicate what is being 1369 transferred - a file, special file that contains a Directory Records, 1370 bundle, or stream. The value 01 indicates that the METADATA and DATA 1371 packets are being generated in response to a _getdir_ REQUEST, and 1372 that the assembled DATA contents should be interpreted as a Directory 1373 Record containing directory entries, as defined in Section 5. The 1374 flag values for bits 10 and 11 MUST be the same as indicated in the 1375 initial METADATA packet. 1377 +-----+-------+-----------------------------------------------------+ 1378 | Bit | Value | Meaning | 1379 +-----+-------+-----------------------------------------------------+ 1380 | 12 | 0 | This packet does not include an optional | 1381 | | | timestamp/nonce field. | 1382 | 12 | 1 | This packet includes an optional timestamp/nonce | 1383 | | | field. | 1384 +-----+-------+-----------------------------------------------------+ 1386 Flag bit 12 indicates that an optional packet timestamp/nonce is 1387 carried in the packet before the offset field. This packet 1388 timestamp/nonce field is always sixteen octets (128 bits) long. 1389 Timestamps can be useful to the sender even when the receiver does 1390 not understand them, as the receiver can simply echo any provided 1391 timestamps back, as specified for STATUS packets, to allow the sender 1392 to monitor flow conditions. Packet timestamps are particularly 1393 useful when streaming. Packet timestamps are discussed further in 1394 Appendix A. 1396 +-----+-------+-------------------------------+ 1397 | Bit | Value | Meaning | 1398 +-----+-------+-------------------------------+ 1399 | 15 | 0 | No response is requested. | 1400 | 15 | 1 | A STATUS packet is requested. | 1401 +-----+-------+-------------------------------+ 1403 Within the Flags field, if bit 15 of the packet is set, the file- 1404 receiver is expected to immediately generate a STATUS packet to 1405 provide the file-sender with up-to-date information regarding the 1406 status of the file transfer. This flag is set carefully and rarely. 1407 This flag may be set periodically, but infrequently. Asymmetric 1408 links with constrained backchannels can only carry a limited amount 1409 of STATUS packets before ack congestion becomes a problem. This flag 1410 SHOULD NOT be set if an unreliable stream is being transferred, or if 1411 multicast is in use. This flag SHOULD be set periodically for 1412 reliable file transfers, or reliable streaming. The file-receiver 1413 MUST respond to the flag by generating a STATUS packet, unless it 1414 knows that doing so will lead to local congestion, in which case it 1415 may choose to send a later voluntary STATUS message. 1417 +-----+-------+----------------------------------+ 1418 | Bit | Value | Meaning | 1419 +-----+-------+----------------------------------+ 1420 | 16 | 0 | Normal use. | 1421 | 16 | 1 | The EOD End of Data flag is set. | 1422 +-----+-------+----------------------------------+ 1424 The End of Data flag is set in DATA packets carrying the last byte of 1425 a transfer. This is particularly useful for streams and for Saratoga 1426 implementations that do not support METADATA. 1428 Immediately following the DATA header is the payload, which consumes 1429 the remainder of the packet and whose length is implicitly defined by 1430 the end of the packet. The payload octets are directly formed from 1431 the continuous octets starting at the specified Offset in the file 1432 being transferred. No special coding is performed. A zero-octet 1433 payload length is allowable. 1435 The length of the Offset fields used within all DATA packets for a 1436 given transaction MUST be consistent with the length indicated by 1437 bits 8 and 9 of any accompanying METADATA packet. If the METADATA 1438 packet has not yet been received, a file-receiver SHOULD request it 1439 via a STATUS packet, and MAY choose to enqueue received DATA packets 1440 for later processing after the METADATA arrives. 1442 4.5. STATUS 1444 The STATUS packet type is the single acknowledgement method that is 1445 used for feedback from a Saratoga receiver to a Saratoga sender to 1446 indicate transaction progress, both as a response to a REQUEST, and 1447 as a response to a DATA packet when demanded or volunteered. 1449 When responding to a DATA packet, the STATUS packet MAY, as needed, 1450 include selective acknowledgement (SNACK) 'hole' information to 1451 enable transmission (usually re-transmission) of specific sets of 1452 octets within the current transaction (called "holes"). This 1453 'holestofill' information can be used to clean up losses (or indicate 1454 no losses) at the end of, or during, a transaction, or to efficiently 1455 resume a transfer that was interrupted in a previous transaction. 1457 Format 1459 0 1 2 3 1460 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 1461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1462 |0 0 1| Type | Flags | Status | 1463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1464 | Id | 1465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1466 | / 1467 / Timestamp/nonce information (optional) / 1468 / / 1469 / | 1470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1471 [ Progress Indicator (descriptor) ] 1472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1473 [ In-Response-To (descriptor) ] 1474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1475 | (possibly, several Hole fields) / 1476 / ... / 1477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1479 where 1481 +----------------+--------------------------------------------------+ 1482 | Field | Description | 1483 +----------------+--------------------------------------------------+ 1484 | Type | 4 | 1485 | Flags | are defined below. | 1486 | Id | identifies the transaction that this packet | 1487 | | belongs to. | 1488 | Status | a value of 00 indicates the transfer is | 1489 | | sucessfully proceeding. All other values are | 1490 | | errors terminating the transfer, explained | 1491 | | below. | 1492 | Zero-Pad | an octet fixed at 00 to allow later fields to be | 1493 | | conveniently aligned for processing. | 1494 | Timestamp | an optional fixed 128-bit field, that is only | 1495 | (optional) | present and used to return a packet timestamp if | 1496 | | the timestamp flag is set. If the STATUS packet | 1497 | | is voluntary and the voluntary flag is set, this | 1498 | | should repeat the timestamp of the DATA packet | 1499 | | containing the highest offset seen. If the | 1500 | | STATUS packet is in response to a mandatory | 1501 | | request, this will repeat the timestamp of the | 1502 | | requesting DATA packet. The file-sender may use | 1503 | | these timestamps to estimate latency. Packet | 1504 | | timestamps are particularly useful when | 1505 | | streaming. There are special considerations for | 1506 | | streaming, to protect against the ambiguity of | 1507 | | wrapped offset descriptor sequence numbers, | 1508 | | discussed below. Packet timestamps are | 1509 | | discussed further in Appendix A. | 1510 | Progress | the offset of the lowest-numbered octet of the | 1511 | Indicator | file not yet received, and expected. | 1512 | (descriptor) | | 1513 | In-Response-To | the offset of the octet following the DATA | 1514 | (descriptor) | packet that generated this STATUS packet, or the | 1515 | | offset of the next expected octet following the | 1516 | | highest DATA packet seen if this STATUS is | 1517 | | generated voluntarily and the voluntary flag is | 1518 | | set. | 1519 | Holes | indications of offset ranges of missing data, | 1520 | | defined below. | 1521 +----------------+--------------------------------------------------+ 1523 The STATUS packet has a minimum size of twelve octets, using sixteen- 1524 bit descriptors, a progress indicator but no Hole fields, and no 1525 timestamps. The progress indicator is always zero when responding to 1526 requests that may initiate a transfer. 1528 The Id field is needed to associate the STATUS packet with the 1529 transaction that it refers to. 1531 The Progress Indicator and In-Response-To fields mark the 'left edge' 1532 and 'right edge' of the incomplete working area where holes are being 1533 filled in. If there are no holes, these fields will hold the same 1534 value. At the start of a transfer, both fields begin by expecting 1535 octet zero. When a transfer has completed successfully, these fields 1536 will contain the length of the file. 1538 Flags bits 8 and 9 are set to indicate the size of the offset 1539 descriptor as described for BEACON and METADATA packets, so that each 1540 STATUS packet is self-describing. The flag values here MUST be the 1541 same as indicated in the initial METADATA and DATA packets. 1543 Other bits in the Flags field are defined as: 1545 +-----+-------+---------------------------------------------------+ 1546 | Bit | Value | Meaning | 1547 +-----+-------+---------------------------------------------------+ 1548 | 12 | 0 | This packet does not include a timestamp field. | 1549 | 12 | 1 | This packet includes an optional timestamp field. | 1550 +-----+-------+---------------------------------------------------+ 1552 Flag bit 12 indicates that an optional sixteen-byte packet timestamp/ 1553 nonce field is carried in the packet before the Progress Indicator 1554 descriptor, as discussed for the DATA packet format. Packet 1555 timestamps are discussed further in Appendix A. 1557 +-----+-------+----------------------------------------+ 1558 | Bit | Value | Meaning | 1559 +-----+-------+----------------------------------------+ 1560 | 13 | 0 | file's METADATA has been received. | 1561 | 13 | 1 | file's METADATA has not been received. | 1562 +-----+-------+----------------------------------------+ 1564 If bit 13 of a STATUS packet has been set to indicate that the 1565 METADATA has not yet been received, then the METADATA should be 1566 resent. This flag should normally be clear. 1568 A receiver SHOULD tolerate lost METADATA that is later resent, but 1569 MAY insist on receiving METADATA at the start of a transfer. This is 1570 done by responding to early DATA packets with a voluntary STATUS 1571 packet that sets this flag bit, reports a status error code 10, sets 1572 the Progress Indicator field to zero, and does not include 1573 HOLESTOFILL information. 1575 +-----+-------+-----------------------------------------------------+ 1576 | Bit | Value | Meaning | 1577 +-----+-------+-----------------------------------------------------+ 1578 | 14 | 0 | this packet contains the complete current set of | 1579 | | | holes at the file-receiver. | 1580 | 14 | 1 | this packet contains incomplete hole-state; holes | 1581 | | | shown in this packet should supplement other | 1582 | | | incomplete hole-state known to the file-sender. | 1583 +-----+-------+-----------------------------------------------------+ 1585 Bit 14 of a 'holestofill' STATUS packet is only set when there are 1586 too many holes to fit within a single STATUS packet due to MTU 1587 limitations. This causes the hole list to be spread out over 1588 multiple STATUS packets, each of which conveys distinct sets of 1589 holes. This could occur, for instance, in a large file _put_ 1590 scenario with a long-delay feedback loop and poor physical layer 1591 conditions. These multiple STATUS packets will share In-Response-To 1592 information. When losses are light and/or hole reporting and repair 1593 is relatively frequent, all holes should easily fit within a single 1594 STATUS packet, and this flag will be clear. Bit 14 should normally 1595 be clear. 1597 In some rare cases of high loss, there may be too many holes in the 1598 received data to convey within a single STATUS's size, which is 1599 limited by the link MTU size. In this case, multiple STATUS packets 1600 may be generated, and Flags bit 14 should be set on each STATUS 1601 packet accordingly, to indicate that each packet holds incomplete 1602 results. The complete group of STATUS packets, each containing 1603 incomplete information, will share common In-Response-To information 1604 to distinguish them from any earlier groups. 1606 +-----+-------+-----------------------------------------------+ 1607 | Bit | Value | Meaning | 1608 +-----+-------+-----------------------------------------------+ 1609 | 15 | 0 | This STATUS was requested by the file-sender. | 1610 | 15 | 1 | This STATUS is sent voluntarily. | 1611 +-----+-------+-----------------------------------------------+ 1613 Flag bit 15 indicates whether the STATUS is sent voluntarily or due 1614 to a request by the sender. It affects content of the In-Response-To 1615 timestamp and descriptor fields. 1617 In the case of a transfer proceeding normally, immediately following 1618 the STATUS packet header shown above, is a set of "Hole" definitions 1619 indicating any lost packets. Each Hole definition is a pair of 1620 unsigned integers. For a 32-bit offset descriptor, each Hole 1621 definition consists of two four-octet unsigned integers: 1623 Hole Definition Format 1625 0 1 2 3 1626 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 1627 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1628 [ offset to start of hole (descriptor) ] 1629 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1630 [ offset to end of hole (descriptor) ] 1631 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1633 The start of the hole means the offset of the first unreceived byte 1634 in that hole. The end of the hole means the last unreceived byte in 1635 that hole. 1637 For 16-bit descriptors, each Hole definition holds two two-octet 1638 unsigned integers, while Hole definitions for 64- and 128-bit 1639 descriptors require two eight- and two sixteen-octet unsigned 1640 integers respectively. 1642 Holes MUST be listed in order, lowest values first. 1644 Since each Hole definition takes up eight octets when 32-bit offset 1645 lengths are used, we expect that well over 100 such definitions can 1646 fit in a single STATUS packet, given the IPv6 minimum MTU. (There 1647 may be cases where there is a very constrained backchannel compared 1648 to the forward channel streaming DATA packets. For these cases, 1649 implementations might deliberately request large holes that span a 1650 number of smaller holes and intermediate areas where DATA has already 1651 been received, so that previously-received DATA is deliberately 1652 resent. This aggregation of separate holes keeps the backchannel 1653 STATUS packet size down to avoid backchannel congestion.) 1655 A 'voluntary' STATUS can be sent at the start of each transaction. 1656 This indicates that the receiver is ready to receive the file, or 1657 indicates an error or rejection code, described below. A STATUS 1658 indicating a successfully established transfer has a Progress 1659 Indicator of zero and an In-Response-To field of zero. 1661 On receiving a STATUS packet, the sender SHOULD prioritize sending 1662 the necessary data to fill those holes, in order to advance the 1663 Progress Indicator at the receiver. 1665 The sender infers a completely-received transfer from the reported 1666 receiver window position. In the final STATUS packet sent by the 1667 receiver once the file to be transferred has been completely 1668 received, bit 14 MUST be 0 (indicating a complete set of holes in 1669 this packet), there MUST NOT be any holestofill offset pairs 1670 indicating holes, the In-Response-To and Progress Indicator fields 1671 contain the length of the file (i.e. point to the next octet after 1672 the file), and the voluntary flag MUST be set. This 'completed' 1673 STATUS may be repeated, depending on subsequent sender behaviour, 1674 while internal state about the transfer remains available to the 1675 receiver. 1677 Because METADATA is optional in implementations, the file receiver 1678 may not know the length of a file if METADATA is never sent. The 1679 sender MUST set the EOD End of Data flag in each DATA packet that 1680 sends the last byte of the file, and SHOULD request a STATUS 1681 acknowledgement when the EOD flag is set. If METADATA has been sent 1682 and the EOD comes earlier than a previously reported length of a 1683 file, an unspecified error 0x01, as described below, is returned in 1684 the STATUS message responding to that DATA packet and EOD flag. If a 1685 stream is being marked EOD, the receiver acknowledges this with a 1686 Success 0x00 code. 1688 In the case of an error causing a transfer to be aborted, the Status 1689 field holds a code that can be used to explain the cause of the error 1690 to the other peer. A zero value indicates that there have been no 1691 significant errors (this is called a "success STATUS" within this 1692 document), while any non-zero value means the transaction should be 1693 aborted (this is called a "failure STATUS"). 1695 +----------------+--------------------------------------------------+ 1696 | Error Code | Meaning | 1697 | Status Value | | 1698 +----------------+--------------------------------------------------+ 1699 | 0x00 | Success, No Errors. | 1700 | 0x01 | Unspecified Error. | 1701 | 0x02 | Unable to send file due to resource constraints. | 1702 | 0x03 | Unable to receive file due to resource | 1703 | | constraints. | 1704 | 0x04 | File not found. | 1705 | 0x05 | Access Denied. | 1706 | 0x06 | Unknown Id field for transaction. | 1707 | 0x07 | Did not delete file. | 1708 | 0x08 | File length is longer than receiver can support. | 1709 | 0x09 | File offset descriptors do not match expected | 1710 | | use or file length. | 1711 | 0x0A | Unsupported Saratoga packet type received. | 1712 | 0x0B | Unsupported Request Type received. | 1713 | 0x0C | REQUEST is now terminated due to an internal | 1714 | | timeout. | 1715 | 0x0D | DATA flag bits describing transfer have changed | 1716 | | unexpectedly. | 1717 | 0x0E | Receiver is no longer interested in receiving | 1718 | | this file. | 1719 | 0x0F | File is in use. | 1720 | 0x10 | METADATA required before transfer can be | 1721 | | accepted. | 1722 | 0x11 | A STATUS error message has been received | 1723 | | unexpectedly, so REQUEST is terminated. | 1724 +----------------+--------------------------------------------------+ 1726 The recipient of a failure STATUS MUST NOT try to process the 1727 Progress Indicator, In-Response-To, or Hole offsets, because, in some 1728 types of error conditions, the packet's sender may not have any way 1729 of setting them to the right length for the transaction. 1731 When sending an indefinite-length stream, the possibility of offset 1732 sequence numbers wrapping back to zero must be considered. This can 1733 be protected against by using large offsets, and by the stream 1734 receiver. The receiver MUST separate out holes before the offset 1735 wraps to zero from holes after the wrap, and send Hole definitions in 1736 different STATUS packets, with Flag 14 set to mark them as 1737 incomplete. Any Hole straddling a sequence wrap MUST be broken into 1738 two separate Holes, with the second Hole starting at zero. The 1739 timestamps in STATUS packets carrying any pre-wrap holes should be 1740 earlier than the timestamp in later packets, and should repeat the 1741 timestamp of the last DATA packet seen for that offset sequence 1742 before the following wrap to zero occurred. Receivers indicate that 1743 they no longer wish to receive streams by sending Status Code 0C. 1745 5. The Directory Entry 1747 Directory Entries have two uses within Saratoga: 1749 1. Within a METADATA packet, a Directory Entry is used to give 1750 information about the file being transferred, in order to 1751 facilitate proper reassembly of the file and to help the file- 1752 receiver understand how recently the file may have been created 1753 or modified. 1755 2. When a peer requests a directory record via a _getdir_ REQUEST, 1756 the other peer generates a file containing a series of one or 1757 more concatenated Directory Entry records, and transfers this 1758 file as it would transfer the response to a normal _get_ REQUEST, 1759 sending the records together within DATA packets. This file may 1760 be either temporary or within-memory and not actually a part of 1761 the host's file system itself. 1763 Directory Entry Format 1765 0 1 2 3 1766 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 1767 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1768 |1| Properties [ Size (descriptor) ] 1769 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1770 | File modification time (using year 2000 epoch) | 1771 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1772 | File creation time (using year 2000 epoch) | 1773 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1774 | / 1775 + / 1776 / / 1777 / File Path (max 1024 octets,variable length) / 1778 / ... // 1779 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1781 where 1782 +------------+------------------------------------------------------+ 1783 | field | description | 1784 +------------+------------------------------------------------------+ 1785 | Properties | if set, bit 7 of this field indicates that the entry | 1786 | | corresponds to a directory. Bit 6, if set, | 1787 | | indicates that the file is "special". A special | 1788 | | file may not be directly transferable as it | 1789 | | corresponds to a symbolic link, a named pipe, a | 1790 | | device node, or some other "special" filesystem | 1791 | | object. A file-sender may simply choose not to | 1792 | | include these types of files in the results of a | 1793 | | _getdir_ request. Bits 8 and 9 are flags that | 1794 | | indicate the width of the following descriptor field | 1795 | | that gives file size. Bit 10 indicates that the | 1796 | | file is to be handled by Saratoga as a bundle, and | 1797 | | passed to a bundle agent. | 1798 | Size | the size of each file or directory in octets. This | 1799 | | is a descriptor, varying as needed in each entry for | 1800 | | the size of the file. For convenience in the | 1801 | | figure, it is shown here as a 16-bit descriptor for | 1802 | | a small file. | 1803 | Mtime | a timestamp showing when the file or directory was | 1804 | | modified. | 1805 | Ctime | a timestamp of the last status change for this file | 1806 | | or directory. | 1807 | File Path | contains the file's name relative within the | 1808 | | requested path of the _getdir_ transaction, a | 1809 | | maximum of 1024-octet UTF-8 string, which is | 1810 | | null-terminated to indicate its end. The File Path | 1811 | | may contain additional null padding in the null | 1812 | | termination to allow Directory Entries to each be | 1813 | | allocated a fixed amount of space or to place an | 1814 | | integer number of Directory Entries in each DATA | 1815 | | packet for debugging purposes. | 1816 +------------+------------------------------------------------------+ 1818 The first bit of the Directory Entry is always 1, to indicate the 1819 start of the record and the end of any padding from previous 1820 Directory Entries. 1822 +-------+-------+---------------------+ 1823 | Bit 6 | Bit 7 | Properties conveyed | 1824 +-------+-------+---------------------+ 1825 | 0 | 0 | normal file. | 1826 | 0 | 1 | normal directory. | 1827 | 1 | 0 | special file. | 1828 | 1 | 1 | special directory. | 1829 +-------+-------+---------------------+ 1831 Streams listed in a directory should be marked as special. If a 1832 stream is being transferred, its size is unknown -- otherwise it 1833 would be a file. The size property of a Directory Entry for a stream 1834 is therefore expected to be zero. 1836 +-------+-------+-------------------------------------------------+ 1837 | Bit 8 | Bit 9 | Properties conveyed | 1838 +-------+-------+-------------------------------------------------+ 1839 | 0 | 0 | File size is indicated in a 16-bit descriptor. | 1840 | 0 | 1 | File size is indicated in a 32-bit descriptor. | 1841 | 1 | 0 | File size is indicated in a 64-bit descriptor. | 1842 | 1 | 1 | File size is indicated in a 128-bit descriptor. | 1843 +-------+-------+-------------------------------------------------+ 1845 Flag bits 8 and 9 of Properties are descriptor size flags, with 1846 similar meaning as elsewhere, describing the size of the File Size 1847 descriptor that follows the Properties field. When a single 1848 Directory Entry appears in the METADATA packet, these flags SHOULD 1849 match flag bits 8 and 9 in the METADATA header. (A smaller 1850 descriptor size may be indicated in the Directory Entry when doing 1851 test transfers of small files using large descriptors.) 1853 +--------+------------------------------------+ 1854 | Bit 10 | Properties conveyed | 1855 +--------+------------------------------------+ 1856 | 0 | File really is a file. | 1857 | 1 | File is to be treated as a bundle. | 1858 +--------+------------------------------------+ 1860 Bit 10 of Directory Entry Properties is a bundle flag, as indicated 1861 in and matching the METADATA header. Use of Saratoga with bundles is 1862 discussed further in [I-D.wood-dtnrg-saratoga]. 1864 +--------+----------------------------------------------------------+ 1865 | Bit 13 | Use | 1866 +--------+----------------------------------------------------------+ 1867 | 0 | This file's content MUST be delivered reliably without | 1868 | | errors using UDP. | 1869 | 1 | This file's content MAY be delivered unreliably, or | 1870 | | partly unreliably, where errors are tolerated, using | 1871 | | UDP-Lite. | 1872 +--------+----------------------------------------------------------+ 1874 Bit 13 indicates whether the file must be sent reliably or can be 1875 sent at least partly unreliably, using UDP-Lite. This matches 1876 METADATA flag use. 1878 Undefined or unused flag bits of the Properties field default to 1879 zero. Bit 0 is always 1, to indicate the start of a Directory Entry. 1880 In general, bits 1-7 of Properties are for matters related to the 1881 sender's filesystem, while bits 8-15 are for matters related to 1882 transport over Saratoga. 1884 It may be reasonable that files are visible in Directory Entries only 1885 when they can be transferred to the requester - this may depend on 1886 e.g. having appropriate access permissions or being able to handle 1887 large filesizes. But requesters only capable of handling small files 1888 MUST be able to skip through large descriptors for large file sizes. 1889 Directory sizes are not calculated or sent, and a Size of 0 is given 1890 instead for directories, which are considered zero-length files. 1892 The "epoch" format used in file creation and modification timestamps 1893 in directory entries indicates the unsigned number of seconds since 1894 the start of January 1, 2000 in UTC. The times MUST include all leap 1895 seconds. Using unsigned 32-bit values means that these time fields 1896 will not wrap until after the year 2136. 1898 Converting from unix CTime/MTime holding a time past January 1, 2000 1899 but with the traditional 1970 epoch means subtracting the fixed value 1900 of 946 684 822 seconds, which includes the 22 leap seconds that were 1901 added to UTC between 1 January 1970 and 1 January 2000. A unix time 1902 before 2000 is rounded to January 1, 2000. 1904 A file-receiver should preserve the timestamp information received in 1905 the METADATA for its own copy of the file, to allow newer versions of 1906 files to propagate and supercede older versions. 1908 6. Behaviour of a Saratoga Peer 1910 This section describes some details of Saratoga implementations and 1911 uses the RFC 2119 standards language to describe which portions are 1912 needed for interoperability. 1914 6.1. Saratoga Transactions 1916 Following are descriptions of the packet exchanges between two peers 1917 for each type of transaction. Exchanges rely on use of the Id field 1918 to match responses to requests, as described earlier in Section 4.2. 1920 6.1.1. The _get_ Transaction 1922 1. A peer (the file-receiver) sends a REQUEST packet to its peer 1923 (the file-sender). The Flags bits are set to indicate that this 1924 is not a _delete_ request, nor does the File Path indicate a 1925 directory. Each _get_ transaction corresponds to a single file, 1926 and fetching multiple files requires sending multiple REQUEST 1927 packets and using multiple different transaction Ids so that 1928 responses can be differentiated and matched to REQUESTs based on 1929 the Id field. If a specific file is being requested, then its 1930 name is filled into the File Path field, otherwise it is left 1931 null and the file-sender will send a file of its choice. 1933 2. If the _get_ request is rejected, then a STATUS packet containing 1934 an error code in the Status field is sent and the transaction is 1935 terminated. This STATUS packet MUST be sent to reject and 1936 terminate the transaction. The error code MAY make use of the 1937 "Unspecified Error" value for security reasons. Some REQUESTs 1938 might also be rejected for specifying files that are too large to 1939 have their lengths encoded within the maximum integer field width 1940 advertised by bits 8 and 9 of the REQUEST. 1942 3. If the _get_ request is accepted, then a STATUS packet MAY be 1943 sent with an error code of 00 and an In-Response-To field of 1944 zero, to indicate acceptance. Sending other packets (METADATA or 1945 DATA) also indicates acceptance. The file-sender SHOULD generate 1946 and send a METADATA packet. The sender MUST send the contents of 1947 the file or stream as a series of DATA packets. In the absence 1948 of STATUS packets being requested from the receiver, if the file- 1949 sender believes it has finished sending the file and is not on a 1950 unidirectional link, it MUST send the last DATA packet with the 1951 Flags bit set requesting a STATUS response from the file- 1952 receiver. The last DATA packet MUST always have its End of Data 1953 (EOD) bit set. This can be followed by empty DATA packets with 1954 the Flags bits set with EOD and requesting a STATUS until either 1955 a STATUS packet is received, or the inactivity timer expires. 1956 All of the DATA packets MUST use field widths for the file offset 1957 descriptor fields that match what the Flags of the METADATA 1958 packet specified. Some arbitrarily selected DATA packets may 1959 have the Flags bit set that requests a STATUS packet. The file- 1960 receiver MAY voluntarily send STATUS packets at other times, 1961 where the In-Response-To field MUST set to zero. The file- 1962 receiver SHOULD voluntarily send a STATUS packet in response to 1963 the first DATA packet. 1965 4. As the file-receiver takes in the DATA packets, it writes them 1966 into the file locally. The file-receiver keeps track of missing 1967 data in a hole list. Periodically the file sender will set the 1968 ack flag bit in a DATA packet and request a STATUS packet from 1969 the file-receiver. The STATUS packet can include a copy of this 1970 hole list if there are holes. File-receivers MUST send a STATUS 1971 packet immediately in response to receiving a DATA packet with 1972 the Flags bit set requesting a STATUS. 1974 5. If the file-sender receives a STATUS packet with a non-zero 1975 number of holes, it re-fetches the file data at the specified 1976 offsets and re-transmits it. If the METADATA packet requires 1977 retransmission, this is indicated by a bit in the STATUS packet, 1978 and the METADATA packet is retransmitted. The file-sender MUST 1979 retransmit data from any holes reported by the file-receiver 1980 before proceeding further with new DATA packets. 1982 6. When the file-receiver has fully received the file data and the 1983 METADATA packet, then it sends a STATUS packet indicating that 1984 the transaction is complete, and it terminates the transaction 1985 locally, although it MUST persist in responding to any further 1986 DATA packets received from the file-sender with 'completed' 1987 STATUSes, as described in Section 4.5, for some reasonable amount 1988 of time. Starting a timer on sending a completed STATUS and 1989 resetting it whenever a received DATA/sent 'completed' STATUS 1990 transaction takes place, then removing all session state on timer 1991 expiry, is one approach to this. 1993 Given that there may be a high degree of asymmetry in link bandwidth 1994 between the file-sender and file-receiver, the STATUS packets should 1995 be carefully generated so as to not congest the feedback path. This 1996 means that both a file-sender should be cautious in setting the DATA 1997 Flags bit requesting STATUSes, and also that a file-receiver should 1998 be cautious in gratuitously generating STATUS packets of its own 1999 volition. When sending on known unidirectional links, a file-sender 2000 cannot reasonably expect to receive STATUS packets, so should never 2001 request them. 2003 6.1.2. The _getdir_ Transaction 2005 A _getdir_ transaction to obtain a Directory Record proceeds through 2006 the same states as the _get_ transaction. Rather than transferring 2007 the contents of a file from the file-receiver to the file-sender, a 2008 set of records representing the contents of a directory are 2009 transferred. These can be parsed and dealt with by the file-receiver 2010 as desired. There is no requirement that a Saratoga peer send the 2011 full contents of a directory listing; a peer may filter the results 2012 to only those entries that are actually accessible to the requesting 2013 peer. 2015 For _getdir_ transactions, the METADATA's bits 8 and 9 in the Flags 2016 field specify both the width of the offset and length fields used 2017 within the transfers DATA and STATUS packets, and also the width of 2018 file Size fields within Directory Entries in the interpreted _getdir_ 2019 results. These Flags bits are set to the minimum of the file- 2020 sender's locally-supported maximum width and the advertised maximum 2021 width within the REQUEST packet, and any file system entries that 2022 would normally be contained in the results, but that have sizes 2023 greater than this width can convey, MUST be filtered out. 2025 6.1.3. The _delete_ Transaction 2027 1. A peer sends a REQUEST packet with the bit set indicating that it 2028 is a deletion request and the path to be deleted is filled into 2029 the File Path field. The File Path MUST be filled in for 2030 _delete_ transactions, unlike for _get_ transactions. 2032 2. The other peer replies with a feedback STATUS packet whose Id 2033 matches the Id field of the _delete_ REQUEST. This STATUS has a 2034 Status code that indicates that the file is not currently present 2035 on the filesystem (indicated by the 00 Status field in a success 2036 STATUS), or whether some error occurred (indicated by the non- 2037 zero Status field in a failure STATUS). This STATUS packet MUST 2038 have no Holes and 16-bit width zero-valued Progress Indicator and 2039 In-Response-To fields. 2041 If a request is received to delete a file that is already deleted, a 2042 STATUS with Status code 00 and other fields as described above is 2043 sent back in acknowledgement. This response indicates that the 2044 indicated file is not present, not the exact action sequence that led 2045 to a not-present file. This idempotent behaviour ensures that loss 2046 of STATUS acknowledgements and repeated _delete_ requests are handled 2047 properly. 2049 6.1.4. The _put_ Transaction 2051 A _put_ transaction proceeds as a _get_ does, except the file-sender 2052 and file-receiver roles are exchanged between peers. In a _put_ a 2053 PUT REQUEST is sent. 2055 However, in a 'blind _put_', no REQUEST packet is ever sent. The 2056 file-sending end senses that the transaction is in progress when it 2057 receives METADATA or DATA packets for which it has no knowledge of 2058 the Id field. 2060 If the file-receiver decides that it will store and handle the _put_ 2061 request (at least provisionally), then it MUST send a voluntary (ie, 2062 not requested) success STATUS packet to the file-sender. Otherwise, 2063 it sends a failure STATUS packet. After sending a failure STATUS 2064 packet, it may ignore future packets with the same Id field from the 2065 file-sender, but it should, at a low rate, periodically regenerate 2066 the failure STATUS packet if the flow of packets does not stop. 2068 6.2. Beacons 2070 Sending BEACON packets is not required in any of the transactions 2071 discussed in this specification, but optional BEACONs can provide 2072 useful information in many situations. If a node periodically 2073 generates BEACON packets, then it should do so at a low rate which 2074 does not significantly affect in-progress data transfers. 2076 A node that supports multiple versions of Saratoga (e.g. version 1 2077 from this specification along with the older version 0), MAY send 2078 multiple BEACON packets showing different version numbers. The 2079 version number in a single BEACON should not be used to infer the 2080 larger set of protocol versions that a peer is compatible with. 2081 Similarly, a node capable of communicating via IPv4 and IPv6 MAY send 2082 separate BEACONs via both protocols, or MAY only send BEACONs on its 2083 preferred protocol. 2085 If a node receives BEACONs from a peer, then it SHOULD NOT attempt to 2086 start any _get_, _getdir_, or _delete_ transactions with that peer if 2087 bit 14 is not set in the latest received BEACONs. Likewise, if 2088 received BEACONs from a peer do not have bit 15 set, then _put_ 2089 transactions SHOULD NOT be attempted to that peer. Unlike the 2090 capabilities bits which prevent certain types of transactions from 2091 being attempted, the willingness bits are advisory, and transactions 2092 MAY be attempted even if the node is not advertising a willingness, 2093 as long as it advertises a capability. This avoids waiting for a 2094 willingness indication across long-delay links. 2096 6.3. Upper-Layer Interface 2098 No particular application interface functionality is required in 2099 implementations of this specification. The means and degree of 2100 access to Saratoga configuration settings, and transaction control 2101 that is offered to upper layers and applications, are completely 2102 implementation-dependent. In general, it is expected that upper 2103 layers (or users) can set timeout values for transaction requests and 2104 for inactivity periods during the transaction, on a per-peer or per- 2105 transaction basis, but in some implementations where the Saratoga 2106 code is restricted to run only over certain interfaces with well- 2107 understood operational latency bounds, then these timers MAY be hard- 2108 coded. 2110 6.4. Inactivity Timer 2112 In order to determine the liveliness of a transaction, Saratoga nodes 2113 may implement an inactivity timer for each peer they are expecting to 2114 see packets from. For each packet received from a peer, its 2115 associated inactivity timer is reset. If no packets are received for 2116 some amount of time, and the inactivity timer expires, this serves as 2117 a signal to the node that it should abort (and optionally retry) any 2118 sessions that were in progress with the peer. Information from the 2119 link interface (i.e. link down) can override this timer for point-to- 2120 point links. 2122 The actual length of time that the inactivity timer runs for is a 2123 matter of both implementation and deployment situation. Relatively 2124 short timers (on the order of several round-trip times) allow nodes 2125 to quickly react to loss of contact, while longer timers allow for 2126 transaction robustness in the presence of transient link problems. 2127 This document deliberately does not specify a particular inactivity 2128 timer value nor any rules for setting the inactivity timer, because 2129 the protocol is intended to be used in both long- and short-delay 2130 regimes. 2132 Specifically, the inactivity timer is started on sending REQUEST or 2133 STATUS packets. When sending packets not expected to elicit 2134 responses (BEACON, METADATA, or DATA without acknowledgement 2135 requests), there is no point to starting the local inactivity timer. 2137 For normal file transfers, there are simple rules for handling 2138 expiration of the inactivity timer during a _get_ or _put_ 2139 transaction. Once the timer expires, the file-sender SHOULD 2140 terminate the transaction state and cease to send DATA or METADATA 2141 packets. The file-receiver SHOULD stop sending STATUS packets, and 2142 MAY choose to store the file in some cache location so that the 2143 transfer can be recovered. This is possible by waiting for an 2144 opportunity to re-attempt the transaction and immediately sending a 2145 STATUS that only lists the parts of the file not yet received if the 2146 transaction is granted. In any case, a partially-received file MUST 2147 NOT be handled in any way that would allow another application to 2148 think it is complete. 2150 The file-sender may implement more complex timers to allow rate-based 2151 pacing or simple congestion control using information provided in 2152 STATUS packets, but such possible timers and their effects are 2153 deliberately not specified here. 2155 7. Mailing list 2157 There is a mailing list for discussion of Saratoga and its 2158 implementations. Contact Lloyd Wood for details. 2160 8. Security Considerations 2162 The design of Saratoga provides limited, deliberately lightweight, 2163 services for authentication of session requests, and for 2164 authentication or encryption of data files via keyed metadata 2165 checksums. This document does not specify privacy or access control 2166 for data files transferred. Privacy, access, authentication and 2167 encryption issues may be addressed within an implementation or 2168 deployment in several ways that do not affect the file transfer 2169 protocol itself. As examples, IPSec may be used to protect Saratoga 2170 implementations from forged packets, to provide privacy, or to 2171 authenticate the identity of a peer. Other implementation-specific 2172 or configuration-specific mechanisms and policies might also be 2173 employed for authentication and authorization of requests. 2174 Protection of file data and meta-data can also be provided by a 2175 higher-level file encryption facility. If IPsec is not required, use 2176 of encryption before the file is given to Saratoga is preferable. 2177 Basic security practices like not accepting paths with "..", not 2178 following symbolic links, and using a chroot() system call, among 2179 others, should also be considered within an implementation. 2181 Note that Saratoga is intended for single-hop transfers between 2182 peers. A METADATA checksum using a previously shared key can be used 2183 to decrypt or authenticate delivered DATA files. Saratoga can only 2184 provide payload encryption across a single Saratoga transfer, not 2185 end-to-end across concatenated separate hop-by-hop transfers through 2186 untrusted peers, as checksum verification of file integrity is 2187 required at each node. End-to-end data encryption, if required, MUST 2188 be implemented by the application using Saratoga. 2190 9. IANA Considerations 2192 IANA has allocated port 7542 (tcp/udp) for use by Saratoga. 2194 saratoga 7542/tcp Saratoga Transfer Protocol 2195 saratoga 7542/udp Saratoga Transfer Protocol 2197 IANA has allocated a dedicated IPv4 all-hosts multicast address 2198 (224.0.0.108) and a dedicated IPv6 link-local multicast addresses 2199 (FF02:0:0:0:0:0:0:6c) for use by Saratoga. 2201 10. Acknowledgements 2203 Developing and deploying the on-orbit IP-based infrastructure of the 2204 Disaster Monitoring Constellation, in which Saratoga has proven 2205 useful, has taken the efforts of hundreds of people over more than a 2206 decade. We thank them all. 2208 We thank James H. McKim as an early contributor to Saratoga 2209 implementations and specifications, while working for RSIS 2210 Information Systems at NASA Glenn. We regard Jim as an author of 2211 this document, but are prevented by the boilerplate five-author limit 2212 from naming him earlier. 2214 We thank Stewart Bryant, Dale Mellor, Cathryn Peoples, Abu Zafar 2215 Shahriar and Dave Stewart for their review comments. 2217 Work on this document at NASA's Glenn Research Center was funded by 2218 NASA's Earth Science Technology Office (ESTO). 2220 11. A Note on Naming 2222 Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier 2223 sunk at Bikini Atoll that is now a popular diving site. 2225 12. References 2227 12.1. Normative References 2229 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 2230 August 1980. 2232 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2233 April 1992. 2235 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2236 Requirement Levels", BCP 14, RFC 2119, March 1997. 2238 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 2239 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 2240 September 2002. 2242 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2243 10646", STD 63, RFC 3629, November 2003. 2245 12.2. Informative References 2247 [Hogie05] Hogie, K., Criscuolo, E., and R. Parise, "Using Standard 2248 Internet Protocols and Applications in Space", Computer 2249 Networks, Special Issue on Interplanetary Internet, vol. 2250 47, no. 5, pp. 603-650, April 2005. 2252 [I-D.wood-dtnrg-http-dtn-delivery] 2253 Wood, L. and P. Holliday, "Using HTTP for delivery in 2254 Delay/Disruption-Tolerant Networks", 2255 draft-wood-dtnrg-http-dtn-delivery-07 (work in progress), 2256 May 2011. 2258 [I-D.wood-dtnrg-saratoga] 2259 Wood, L., McKim, J., Eddy, W., Ivancic, W., and C. 2260 Jackson, "Using Saratoga with a Bundle Agent as a 2261 Convergence Layer for Delay-Tolerant Networking", 2262 draft-wood-dtnrg-saratoga-09 (work in progress), May 2011. 2264 [Ivancic10] 2265 Ivancic, W., Eddy, W., Stewart, D., Wood, L., Northam, J., 2266 and C. Jackson, "Experience with delay-tolerant networking 2267 from orbit", International Journal of Satellite 2268 Communications and Networking, Special Issue on best 2269 papers of the Fourth Advanced Satellite Mobile Systems 2270 Conference (ASMS 2008), vol. 28, issues 5-6, pp. 335-351, 2271 September-December 2010. 2273 [Jackson04] 2274 Jackson, C., "Saratoga File Transfer Protocol", Surrey 2275 Satellite Technology Ltd internal technical document , 2276 2004. 2278 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 2279 STD 9, RFC 959, October 1985. 2281 [RFC3366] Fairhurst, G. and L. Wood, "Advice to link designers on 2282 link Automatic Repeat reQuest (ARQ)", BCP 62, RFC 3366, 2283 August 2002. 2285 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and 2286 G. Fairhurst, "The Lightweight User Datagram Protocol 2287 (UDP-Lite)", RFC 3828, July 2004. 2289 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 2290 Specification", RFC 5050, November 2007. 2292 [RFC5348] Floyd, S., Handley, M., Padhye, J., and J. Widmer, "TCP 2293 Friendly Rate Control (TFRC): Protocol Specification", 2294 RFC 5348, September 2008. 2296 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 2297 for Application Designers", BCP 145, RFC 5405, 2298 November 2008. 2300 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 2301 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 2302 RFC 6151, March 2011. 2304 [Wood07a] Wood, L., Ivancic, W., Hodgson, D., Miller, E., Conner, 2305 B., Lynch, S., Jackson, C., da Silva Curiel, A., Cooke, 2306 D., Shell, D., Walke, J., and D. Stewart, "Using Internet 2307 Nodes and Routers Onboard Satellites", International 2308 Journal of Satellite Communications and 2309 Networking, Special Issue on Space Networks, vol. 25, no. 2310 2, pp. 195-216, March/April 2007. 2312 [Wood07b] Wood, L., Eddy, W., Ivancic, W., Miller, E., McKim, J., 2313 and C. Jackson, "Saratoga: a Delay-Tolerant Networking 2314 convergence layer with efficient link utilization", 2315 International Workshop on Satellite and Space 2316 Communications (IWSSC '07) Salzburg, September 2007. 2318 [Wood11] Wood, L., Smith, C., Eddy, W., Ivancic, W., and C. 2319 Jackson, "Taking Saratoga from space-based ground sensors 2320 to ground-based space sensors", IEEE Aerospace 2321 Conference Big Sky, Montana, March 2011. 2323 [wood-tsvwg-saratoga-congestion-control] 2324 Wood, L., Eddy, W., and W. Ivancic, "Congestion control 2325 for the Saratoga protocol", 2326 draft-wood-tsvwg-saratoga-congestion-control-00 (work in 2327 progress) , September 2011. 2329 Appendix A. Timestamp/Nonce field considerations 2331 Timestamps are useful in DATA packets when the time that the packet 2332 or its payload was generated is of importance; this can be necessary 2333 when streaming sensor data recorded and packetized in real time. The 2334 format of the optional timestamp, whose presence is indicated by a 2335 flag bit, is implementation-dependent within the available fixed- 2336 length 128-bit field. How the contents of this timestamp field are 2337 used and interpreted depends on local needs and conventions and the 2338 local implementation. 2340 However, one simple suggested format for timestamps is to begin with 2341 a POSIX time_t representation of time, in network byte order. This 2342 is either a 32-bit or 64-bit signed integer representing the number 2343 of seconds since 1970. The remainder of this field can be used 2344 either for a representation of elapsed time within the current 2345 second, if that level of accuracy is required, or as a nonce field 2346 uniquely identifying the packet or including other information. Any 2347 locally-meaningful flags identifying a type of timestamp or timebase 2348 can be included before the end of the field. Unused parts of this 2349 field MUST be set to zero. 2351 There are many different representations of timestamps and timebases, 2352 and this draft is too short to cover them in detail. One suggested 2353 flag representation of different timestamp fields is to use the least 2354 significant bits at the end of the timestamp/nonce field as: 2356 +---------+---------------------------------------------------------+ 2357 | Status | Meaning | 2358 | Value | | 2359 +---------+---------------------------------------------------------+ 2360 | 00 | No flags set, local interpretation of field. | 2361 | 01 | 32-bit timestamp at start of field indicating whole | 2362 | | seconds from epoch. | 2363 | 02 | 64-bit timestamp at start of field indicating whole | 2364 | | seconds elapsed from epoch. | 2365 | 03 | 32-bit timestamp, as in 01, followed by 32-bit | 2366 | | timestamp indicating fraction of the second elapsed. | 2367 | 04 | 64-bit timestamp, as in 02, followed by 32-bit | 2368 | | timestamp indicating fraction of the second elapsed. | 2369 +---------+---------------------------------------------------------+ 2371 Other values may indicate specific epochs or timebases, as local 2372 requirements dictate. There are many ways to define and use time 2373 usefully. 2375 Echoing timestamps back to the file-sender is also useful for 2376 tracking flow conditions. This does not require the echoing receiver 2377 to understand the timestamp format or values in use. The use of 2378 timestamp values may assist in developing algorithms for flow control 2379 (including TCP-Friendly Rate Control 2380 [wood-tsvwg-saratoga-congestion-control]) or other purposes. 2381 Timestamp values provide a useful mechanism for Saratoga peers to 2382 measure path and round-trip latency. 2384 Authors' Addresses 2386 Lloyd Wood 2387 Centre for Communication Systems Research, University of Surrey 2388 Guildford, Surrey GU2 7XH 2389 United Kingdom 2391 Phone: +44-1483-689123 2392 Email: L.Wood@surrey.ac.uk 2393 Wesley M. Eddy 2394 MTI Systems 2395 MS 500-ASRC 2396 NASA Glenn Research Center 2397 21000 Brookpark Road 2398 Cleveland, OH 44135 2399 USA 2401 Phone: +1-216-433-6682 2402 Email: wes@mti-systems.com 2404 Charles Smith 2405 Commonwealth Scientific and Industrial Research Organisation 2406 Cnr Vimiera and Pembroke Roads 2407 Marsfield, New South Wales 2122 2408 Australia 2410 Phone: +61-404-058974 2411 Email: charles.smith@csiro.au 2413 Will Ivancic 2414 NASA Glenn Research Center 2415 21000 Brookpark Road, MS 54-5 2416 Cleveland, OH 44135 2417 USA 2419 Phone: +1-216-433-3494 2420 Email: William.D.Ivancic@grc.nasa.gov 2422 Chris Jackson 2423 Surrey Satellite Technology Ltd 2424 Tycho House 2425 Surrey Space Centre 2426 20 Stephenson Road 2427 Guildford, Surrey GU2 7YE 2428 United Kingdom 2430 Phone: +44-1483-803803 2431 Email: C.Jackson@sstl.co.uk