idnits 2.17.1 draft-wood-tsvwg-saratoga-07.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 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 (December 6, 2010) is 4887 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 (-10) exists of draft-ietf-ledbat-congestion-03 == Outdated reference: A later version (-09) exists of draft-wood-dtnrg-http-dtn-delivery-06 == Outdated reference: A later version (-14) exists of draft-wood-dtnrg-saratoga-08 Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Wood 3 Internet-Draft University of Surrey 4 Intended status: Experimental W. Eddy 5 Expires: June 9, 2011 MTI Systems 6 C. Smith 7 CSIRO 8 W. Ivancic 9 NASA 10 C. Jackson 11 SSTL 12 December 6, 2010 14 Saratoga: A Scalable File Transfer Protocol 15 draft-wood-tsvwg-saratoga-07 17 Abstract 19 This document specifies the Saratoga transfer protocol. Saratoga was 20 originally developed to efficiently transfer remote-sensing imagery 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 June 9, 2011. 59 Copyright Notice 61 Copyright (c) 2010 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 4. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 4.1. BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 15 81 4.2. REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 4.3. METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 22 83 4.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 84 4.5. STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . 30 85 5. The Directory Entry . . . . . . . . . . . . . . . . . . . . . 36 86 6. Behaviour of a Saratoga Peer . . . . . . . . . . . . . . . . . 38 87 6.1. Saratoga Transactions . . . . . . . . . . . . . . . . . . 38 88 6.2. Beacons . . . . . . . . . . . . . . . . . . . . . . . . . 42 89 6.3. Upper-Layer Interface . . . . . . . . . . . . . . . . . . 42 90 6.4. Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 42 91 7. Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . 43 92 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 94 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 44 95 11. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 45 96 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 97 12.1. Normative References . . . . . . . . . . . . . . . . . . . 45 98 12.2. Informative References . . . . . . . . . . . . . . . . . . 45 99 Appendix A. Timestamp/Nonce field considerations . . . . . . . . 47 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 102 1. Background and Introduction 104 Saratoga is a file transfer and content dissemination protocol 105 capable of efficiently sending both small and very large files as 106 well as streaming continuous content. Saratoga was originally 107 designed for the purpose of large file transfer from small low-Earth- 108 orbit satellites. It has been used in daily operations since 2004 to 109 move mission imaging data files of the order of several hundred 110 megabytes each from the Disaster Monitoring Constellation (DMC) 111 remote-sensing satellites to ground stations. 113 The DMC satellites, built at the University of Surrey by Surrey 114 Satellite Technology Ltd (SSTL), all use IP for payload 115 communications and delivery of Earth imagery. At the time of this 116 writing, in early December 2010, seven DMC satellites have been 117 launched into orbit, five of those are currently operational in 118 orbit, and two further DMC satellites are being readied for launch. 119 The DMC satellites use Saratoga to provide Earth imagery under the 120 aegis of the International Charter on Space and Major Disasters. A 121 pass of connectivity between a satellite and ground station offers an 122 8-12 minute time window in which to transfer imagery files using a 123 minimum of an 8.1 Mbps downlink and a 9.6 kbps uplink. The latest 124 operational DMC satellites have faster downlinks, capable of 20, 40 125 or 80 Mbps. Newer satellites are expected to provide 200 Mbps or 126 more, without significant increases in uplink rates. This high 127 degree of asymmetry, with the need to fully utilize the available 128 downlink capacity to move the volume of data required within the 129 limited time available, motivates much of Saratoga's design. 131 Further details on how these DMC satellites use IP to communicate 132 with the ground and the terrestrial Internet are discussed in other 133 documents [Hogie05][Wood07a][Ivancic10]. 135 Store-and-forward delivery relies on reliable hop-by-hop transfers of 136 files, removing the need for the final receiver to talk to the 137 original sender across long delays and allowing for the possibility 138 that an end-to-end path may never exist between sender and receiver 139 at any given time. Use of store-and-forward hop-by-hop delivery is 140 typical of scenarios in space exploration for both near-Earth and 141 deep-space missions, and useful for other scenarios, such as 142 underwater networking, ad-hoc sensor networks, and some message- 143 ferrying relay scenarios. Saratoga is intended to be useful for 144 relaying data in these scenarios, and can optionally also be used to 145 carry the Bundle Protocol "bundles" that is proposed for use in Delay 146 and Disruption-Tolerant Networking (DTN) by the IRTF DTN Research 147 Group [RFC5050]. This has been tested from orbit using the UK-DMC 148 satellite [Ivancic10]. How Saratoga can optionally function as a 149 "bundle convergence layer" alongside a DTN bundle agent is specified 150 in a companion document [I-D.wood-dtnrg-saratoga]. 152 High link utilization is important during periods of limited 153 connectivity. Given that Saratoga was originally developed for 154 scheduled peer-to-peer communications over dedicated links in private 155 networks, where each application has the entire link for the duration 156 of its transfer, early Saratoga implementations deliberately lack any 157 form of congestion control and send at line rate to maximise 158 throughput and link utilisation. Newer implementations may perform 159 TCP-Friendly Rate Control (TFRC) [RFC5348] or other congestion 160 control mechanisms such as LEDBAT [I-D.ietf-ledbat-congestion], if 161 appropriate for the environment, and where simultaneous sharing of 162 capacity with other traffic and applications is required. 164 Saratoga contains a Selective Negative Acknowledgement (SNACK) 165 'holestofill' mechanism to provide reliable retransmission of data. 166 This is intended to correct losses of corrupted link-layer frames due 167 to channel noise over a space link. Packet losses in the DMC are due 168 to corruption introducing non-recoverable errors in the frame. The 169 DMC design uses point-to-point links and scheduling of applications 170 in order, so that the link is dedicated to one application transfer 171 at a time, meaning that packet loss cannot be due to congestion when 172 applications compete for link capacity simultaneously. In other 173 wireless environments that may be shared by many nodes and 174 applications, allocation of channel resources to nodes becomes a MAC- 175 layer function. Forward Error Coding (FEC) to get the most reliable 176 transmission through a channel is best left near the physical layer 177 so that it can be tailored for the channel. Use of FEC complements 178 Saratoga's transport-level negative-acknowledgement approach to 179 provide a reliable ARQ mechanism [RFC3366]. 181 Saratoga is scalable in that it is capable of efficiently 182 transferring small or large files, by choosing a width of file offset 183 descriptor appropriate for the filesize, and advertising accepted 184 offset descriptor sizes. 16-bit, 32-bit, 64-bit and 128-bit 185 descriptors can be selected, for maximum file sizes of 64KiB-1, 186 4GiB-1, 2^64-1 and 2^128-1 octets. Earth imaging files currently 187 transferred by Saratoga are mostly up to a few gigabytes in size. 188 Some implementations do transfer more than 4 GiB in size, and so 189 require offset descriptors larger than 32 bits. We expect that a 190 128-bit descriptor will satisfy all future needs, but we expect 191 current implementations to only support up to 32-bit or 64-bit 192 descriptors, depending on their application needs. The 16-bit 193 descriptor is useful for small messages, including messages from 194 8-bit devices, and is always supported. The 128-bit descriptor is 195 useful for moving very large files stored on a 128-bit filesystem, 196 such as on OpenSolaris ZFS. 198 As a UDP-based protocol, Saratoga can be used with either IPv4 or 199 IPv6. Compatibilit between Saratoga and the wide variety of links 200 that can already carry IP traffic is assured. 202 Saratoga was originally implemented as outlined in [Jackson04], but 203 the specification given here differs substantially, as we have added 204 a number of features, while cleaning up the initial Saratoga 205 specification. The original Saratoga code uses a version number of 206 0, while code that implements this version of the protocol advertises 207 a version number of 1. Further discussion of the history and 208 development of Saratoga is given in [Wood07b]. 210 This document contains an overview of the transfer process and 211 transactions using Saratoga in Section 2, followed by a formal 212 definition of the packet types used by Saratoga in Section 4, and the 213 details of the various protocol mechanisms in Section 6. 215 Here, Saratoga transaction types are labelled with underscores around 216 lowercase names (such as a "_get_" transaction), while Saratoga 217 packet types are labelled in all capitals (such as a "REQUEST" 218 packet) in order to distinguish between the two. 220 The remainder of this specification uses 'file' as a shorthand for 221 'binary object', which may be a DTN bundle, or other type of data. 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 225 document are to be interpreted as described in RFC 2119. [RFC2119] 227 2. Overview of Saratoga File Transfer 229 Saratoga is a peer-to-peer protocol in the sense that multiple files 230 may be transferred in both directions simultaneously between two 231 communicating Saratoga peers, and there is not intended to be a 232 strict client-to-server relationship. 234 Saratoga nodes can act as simple file servers. Saratoga supports 235 several types of operations on files including "pull" downloads, 236 "push" uploads, directory listing, and deletion requests. Each 237 operation is handled as a distinct "transaction" between the peers. 239 Saratoga nodes MAY advertise their presence, capabilities, and 240 desires by sending BEACON packets. These BEACONs are sent to either 241 a reserved, unforwardable, multicast address when using IPv4, or a 242 link-local all-Saratoga-peers multicast address when using IPv6. A 243 BEACON might also be unicast to another known node as a sort of 244 "keepalive". Saratoga nodes may dynamically discover other Saratoga 245 nodes, either through listening for BEACONs, through pre- 246 configuration, or via some other trigger from a user, lower-layer 247 protocol, or another process. The BEACON is simply useful in low- 248 delay ad-hoc networking or as explicit confirmation that another node 249 is present; it is not required in order to begin a Saratoga 250 transaction. BEACONs have been used by the DMC satellites to 251 indicate to ground stations that a link has become functional, a 252 solid-state data recorder is online, and the software is ready to 253 transfer any requested files. 255 A Saratoga transaction begins with either a _get_, _put_, _getdir_, 256 or _delete_ transaction REQUEST packet corresponding to a desired 257 download, upload, directory listing, or deletion operation. _put_ 258 transactions can begin directly with METADATA and DATA. The most 259 common envisioned transaction is the _get_, which begins with a 260 single Saratoga REQUEST packet sent from the peer wishing to receive 261 the file, to the peer who currently has the file. If the transaction 262 is rejected, then a brief STATUS packet that conveys rejection is 263 generated. If the file-serving peer accepts the transaction, it 264 generates and can send a more useful descriptive METADATA packet, 265 along with some number of DATA packets constituting the requested 266 file. 268 These DATA packets are finished by (and can intermittently include) a 269 DATA packet with a flag bit set that demands the file-receiver send a 270 reception report in the form of a STATUS packet. The STATUS packet 271 can include 'holestofill' Selective Negative Acknowledgement (SNACK) 272 information listing spans of octets within the file that have not yet 273 been received, as well as whether or not the METADATA packet was 274 received. Based on the information in this STATUS packet, the file- 275 sender can begin a cycle of selective retransmissions of missing DATA 276 packets, until it sees a STATUS packet that acknowledges total 277 reception of all file data. 279 In the example scenario in Figure 1, a _get_ request is granted. The 280 reliable file delivery experiences loss of a single DATA packet due 281 to channel-induced errors. 283 File-Receiver File-Sender 285 GET REQUEST ---------------------> 286 (indicates acceptance) <------- METADATA 287 <---------------------- DATA #1 288 STATUS -----------------> (voluntarily sent at start) 289 (lost) <------ DATA #2 290 <---------------------- DATA #3 (bit set 291 requesting STATUS) 292 STATUS -----------------> 293 (indicating that range in DATA #2 was lost) 294 <----------------------- DATA #2 (bit set 295 requesting STATUS) 296 STATUS -----------------> 297 (complete file and METADATA received) 299 Figure 1: Example _get_ transaction sequence 301 A _getdir_ request proceeds similarly, though the DATA packets 302 contain the contents of a directory listing, described later, rather 303 than a given file's bytes. _getdir_ is the only request to apply to 304 directories. 306 The STATUS and DATA packets are allowed to be sent at any time within 307 the scope of a transaction, in order for the file-sending node to 308 optimize buffer management and transmission order. For example, if 309 the file-receiver already has the first half of a file from a 310 previous disrupted transfer, it may send a STATUS at the beginning of 311 the transaction indicating that it has the first half of the file, 312 and so only needs the last half of the file. Thus, efficient 313 recovery from interrupted sessions between peers becomes possible, 314 similar to ranged FTP and HTTP requests. 316 The Saratoga _put_ transaction is initiated by the file-sender 317 sending an optional METADATA packet followed by immediate DATA 318 packets, without waiting for a STATUS response. This can be 319 considered an "optimistic" mode of protocol operation, as it assumes 320 the transaction request will be granted. If the sender of a PUT 321 request sees a STATUS packet indicating that the request was 322 declined, it MUST stop sending any DATA packets within that 323 transaction immediately. Since this type of _put_ is open-loop for 324 some period of time, it should not be used in scenarios where 325 congestion is a valid concern; in these cases, the file-sender should 326 wait on its METADATA to be acknowledged by a STATUS before sending 327 DATA packets within the transaction. 329 Figure 2 illustrates the sequence of packets in an example _put_ 330 transaction, beginning directly with METADATA and DATA, where the 331 second DATA packet is lost. Other than the way that it is initiated, 332 a _put_ transaction is identical to a _get_ transaction. 334 File-Sender File-Receiver 336 METADATA ----------------> 337 DATA #1 ----------------> 338 (transfer accepted) <---------- STATUS 339 DATA #2 ---> (lost) 340 DATA #3 (bit set ------------> 341 requesting STATUS) 342 (DATA #2 lost) <---------- STATUS 343 DATA #2 (bit set ------------> 344 requesting STATUS) 345 (transfer complete) <---------- STATUS 347 Figure 2: Example PUT transaction sequence 349 In deep-space scenarios, the large propagation delays and round-trip 350 times involved discourage use of ping-pong packet exchanges (such as 351 TCP's SYN/ACK) for starting transactions, and unidirectional 352 transfers via these optimistic 'blind _put_s' are desirable. Blind 353 _puts_ are the only mode of transfer suitable for unidirectional 354 links. Senders sending on unidirectional links SHOULD send a copy of 355 the METADATA in advance of DATA packets, and MAY resend METADATA at 356 intervals. 358 The _delete_ transactions are simple single packet requests that 359 trigger a STATUS packet with a status code that indicates whether the 360 file was deleted or not. If the file is not able to be deleted for 361 some reason, this reason can be conveyed in the Status field of the 362 STATUS packet. 364 A _get_ REQUEST packet that does not specify a filename (i.e. the 365 request contains a zero-length File Path field) is specially defined 366 to be a request for any chosen file that the peer wishes to send it. 367 This 'blind _get_' allows a Saratoga peer to request any files that 368 the other Saratoga peer has ready for it, without prior knowledge of 369 the directory listing, and without requiring the ability to examine 370 files or decode remote file names/paths for meaningful information 371 such as final destination. 373 If a file is larger than Saratoga can be expected to transfer during 374 a time-limited contact, there are at least two feasible options: 376 (1) The application can use proactive fragmentation to create 377 multiple smaller-sized files. Saratoga can transfer some number of 378 these smaller files fully during a contact. 380 (2) To avoid file fragmentation, a Saratoga file-receiver can retain 381 a partially-transferred file and request transfer of the unreceived 382 bytes during a later contact. This uses a STATUS packet to make 383 clear how much of the file has been successfully received and where 384 transfer should be resumed from, and relies on use of METADATA to 385 identify the file. On resumption of a transfer, the new METADATA 386 (including file length, file timestamps, and possibly MD5 sum) MUST 387 match that of the previous METADATA in order to re-establish the 388 transfer. Otherwise, the file-receiver MUST assume that the file has 389 changed and purge the DATA payload received during previous contacts. 391 If a file contains separate parts that require reliable transmission 392 without errors or that can tolerate errors in delivered content, 393 proactive fragmentation can be used to split the file into separate 394 reliable and unreliable files that can be transferred separately, 395 using UDP or UDP-Lite. 397 If parts of a file require reliability but the rest can be sent by 398 unreliable transfer, the file-sender can use its knowledge of the 399 internal file structure and vary DATA packet size so that the 400 reliable parts always start after the offset field and are covered by 401 the UDP-Lite checksum. 403 A file that permits unreliable delivery may be transferred onwards 404 using UDP, although the METADATA flag indicating that unreliable 405 transmission is permitted is retained for later hops, which may 406 revert to using UDP-Lite. If the current sender does not understand 407 the internal file format to be able to decide what parts must be 408 protected, the current sender or receiver does not support UDP-Lite, 409 or the current protocol stack only implements error-free frame 410 delivery below the UDP layer, then the file MAY be delivered using 411 UDP. 413 Like the BEACON packets, a _put_ or a response to a _get_ MAY be sent 414 to the dedicated IPv4 Saratoga multicast address (allocated to 415 224.0.0.108) or the dedicated IPv6 link-local multicast address 416 (allocated to FF02:0:0:0:0:0:0:6C) for multiple file-receivers on the 417 link to hear. This is at the discretion of the file-sender, if it 418 believes that there is interest from multiple receivers. In-progress 419 DATA transfers MAY also be moved seamlessly from unicast to multicast 420 if the file-sender learns during a transfer, from receipt of further 421 unicast _get_ REQUEST packets, that multiple nodes are interested in 422 the file. The associated METADATA packet is multicast when this 423 transition takes place, and is then repeated periodically while the 424 DATA stream is being sent, to inform newly-arrived listeners about 425 the file being multicast. Acknowledgements MUST NOT be demanded by 426 multicast DATA packets, to prevent ack implosion at the file-sender, 427 and instead status SNACK information is aggregated and sent 428 voluntarily by all file-receivers. File-receivers respond to 429 multicast DATA with multicast STATUS packets. File-receivers SHOULD 430 introduce a short random delay before sending a multicast STATUS 431 packet, to prevent ack implosion after a channel-induced loss, and 432 MUST listen for STATUS packets from others, to avoid duplicating fill 433 requests. The file-sender SHOULD repeat any initial unicast portion 434 of the transfer as multicast last of all, and may repeat and cycle 435 through multicast of the file several times while file-receivers 436 express interest via STATUS or _get_ packets. Once in multicast and 437 with METADATA being repeated periodically, new file-receivers do not 438 need to send individual REQUEST packets. If a transfer has been 439 started using UDP-Lite and new receivers indicate UDP-only 440 capability, multicast transfers MUST switch to using UDP to 441 accommodate them. 443 3. Optional Parts of Saratoga 445 Implementing support for some parts of Saratoga is optional. These 446 parts are: 448 - sending and parsing BEACONs. 450 - sending and parsing METADATA. However, sending and receiving 451 METADATA is considered useful, and this SHOULD be done. 453 - support for working with DTN bundles and a bundle agent as an 454 application driving Saratoga. Use of a filesystem is expected. 456 - transfers permitting some errors in content delivered, using UDP- 457 Lite. These can be useful for decreasing delivery time over 458 unreliable channels, especially for unidirectional links, or in 459 decreasing computational overheard for the UDP Lite checksum. Error 460 tolerance requires that lower-layer frames permit delivery of 461 unreliable data to be really useful. 463 - streaming data, including real-time streaming of content of unknown 464 length. This streaming can be unreliable (without resend requests) 465 or reliable (with resend requests). Session protocols such as http 466 expect reliable streaming, and can be used in delay-tolerant networks 467 [I-D.wood-dtnrg-http-dtn-delivery]. Although Saratoga data delivery 468 is inherently one-way, where a stream of DATA packets elicits a 469 stream of STATUS packets, bidirectional duplex communication can be 470 established by using two Saratoga transfers flowing in opposite 471 directions. 473 - sending and responding to packet timestamps in DATA and STATUS 474 packets. These timestamps are useful for streaming and for giving a 475 file-sender an indication of path latency for rate control. There is 476 no need for a file-receiver to understand the format used for these 477 timestamps for it to be able to receive and reflect them. 479 - performing congestion control at the sender, based on feedback from 480 acknowledgement STATUS packets, or having the sender configured to 481 use simple open-loop rate control to only use a fixed amount of link 482 capacity. Congestion control is expected to be undesirable for 483 Saratoga's use cases and expected environmental conditions, while 484 simple rate control is considered useful. 486 - multicast DATA transfers, if judged useful for the environment in 487 which Saratoga is deployed, when multiple receivers are participating 488 and are receiving the same file or stream. 490 - sending and parsing STATUS messages, which are expected for 491 bidirectional communication, but cannot be sent on and are not 492 required for sending over unidirectional links. 494 4. Packet Types 496 Saratoga is defined for use with UDP over either IPv4 or IPv6 497 [RFC0768]. UDP checksums, which are mandatory with IPv6, MUST be 498 used with IPv4. Within either version of IP datagram, a Saratoga 499 packet appears as a typical UDP header followed by an octet 500 indicating how the remainder of the packet is to be interpreted: 502 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 503 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 504 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 505 | UDP source port | UDP destination port | 506 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 507 | UDP length | UDP checksum | 508 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 509 |Ver|Packet Type| other Saratoga fields ... // 510 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 512 Saratoga data transfers can also be carried out using UDP-Lite 513 [RFC3828]. If Saratoga can be carried over UDP-Lite, the 514 implementation MUST also support UDP. All packet types except DATA 515 MUST be sent using UDP with checksums turned on. For reliable 516 transfers, DATA packets are sent using UDP with checksums turned on. 517 For files where unreliable transfer has been indicated as desired and 518 possible, the sender MAY send DATA packets unreliably over UDP-Lite, 519 where UDP-Lite protects only the Saratoga headers and parts of the 520 file that must be transmitted reliably. 522 The two-bit Saratoga version field ("Ver") identifies the version of 523 the Saratoga protocol that the packet conforms to. The value 01 524 should be used in this field for implementations conforming to the 525 specification in this document, which specifies version 1 of 526 Saratoga. The value 00 was used in earlier implementations, prior to 527 the formal specification and public submission of the protocol 528 design, and is incompatible with version 01 in several respects. 530 The six-bit Saratoga "Packet Type" field indicates how the remainder 531 of the packet is intended to be decoded and processed: 533 +---+----------+----------------------------------------------------+ 534 | # | Type | Use | 535 +---+----------+----------------------------------------------------+ 536 | 0 | BEACON | Beacon packet indicating peer status | 537 | 1 | REQUEST | Commands peer to start a transfer | 538 | 2 | METADATA | Carries file transfer metadata | 539 | 3 | DATA | Carries octets of file data | 540 | 4 | STATUS | responds to REQUEST or DATA. Can signal list of | 541 | | | unreceived data to sender during a transfer. | 542 +---+----------+----------------------------------------------------+ 544 Several of these packet types include a Flags field, for which only 545 some of the bits have defined meanings and usages in this document. 546 Other, undefined, bits may be reserved for future use. Following the 547 principle of being conservative in what you send and liberal in what 548 you accept, a packet sender MUST set any undefined bits to zero, and 549 a packet recipient MUST NOT rely on these undefined bits being zero 550 on reception. 552 The specific formats for the different types of packets are given in 553 this section. Some packet types contain file offset descriptor 554 fields, which contain unsigned integers. The lengths of the offset 555 descriptors are fixed within a transfer, but vary between file 556 transfers. The size is set for each particular transfer, depending 557 on the choice of offset descriptor width made in the METADATA packet, 558 which in turn depends on the size of file being transferred. 560 In this document, all of the packet structure figures illustrating a 561 packet format assume 32-bit lengths for these offset descriptor 562 fields, and indicate the transfer-dependent length of the fields by 563 using a "(descriptor)" designation within the [field] in all packet 564 diagrams. That is: 566 The example 32-bit descriptors shown in all diagrams here 568 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 569 [ (descriptor) ] 570 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 are suitable for files of up to 4GiB - 1 octets in length, and may be 573 replaced in a file transfer by descriptors using a different length, 574 depending on the size of file to be transferred: 576 16-bit descriptor for short files (MUST be supported) 578 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 579 [ (descriptor) ] 580 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 582 64-bit descriptor for longer files (optional) 584 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 585 [ (descriptor) / 586 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 587 / (descriptor, continued) ] 588 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 590 128-bit descriptor for very long files (optional) 592 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 593 [ (descriptor) / 594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 595 / (descriptor, continued) / 596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 597 / (descriptor, continued) / 598 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 599 / (descriptor, continued) ] 600 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 602 For offset descriptors and types of content being transferred, the 603 related flag bits in BEACON and REQUEST indicate capabilities, while 604 in METADATA and DATA those flag bits are used slightly differently, 605 to indicate the content being transferred. 607 Saratoga packets are intended to fit within link MTUs to avoid the 608 inefficiencies and overheads of lower-layer fragmentation. A 609 Saratoga implementation itself does not perform any form of MTU 610 discovery, but is assumed to be configured with knowledge of usable 611 maximum IP MTUs for the link interfaces it uses. 613 4.1. BEACON 615 BEACON packets may be multicast periodically by nodes willing to act 616 as Saratoga peers, or unicast to individual peers to indicate 617 properties for that peer. Some implementations have sent BEACONS 618 every 100 milliseconds, but this rate is arbitrary, and should be 619 chosen to be appropriate for the environment and implementation. 621 The main purpose for sending BEACONs is to announce the presence of 622 the node to potential peers (e.g. satellites, ground stations) to 623 provide automatic service discovery, and also to confirm the activity 624 or presence of the peer. 626 The Endpoint Identifier (EID) in the BEACON serves to uniquely 627 identify the Saratoga peer. Whenever the Saratoga peer begins using 628 a new IP address, it SHOULD issue a BEACON on it and repeat the 629 BEACON periodically, to enable listeners to associate the IP address 630 with the EID and the peer. 632 Format 634 0 1 2 3 635 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 636 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 637 |0 1| Type | Flags | 638 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 639 [[ Available free space (optional) ]] 640 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 641 | Endpoint identifier... // 642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 644 where 646 +------------+------------------------------------------------------+ 647 | Field | Description | 648 +------------+------------------------------------------------------+ 649 | Type | 0 | 650 | Flags | convey whether or not the peer is ready to | 651 | | send/receive, what the maximum supported file size | 652 | | range and descriptor is, and whether and how free | 653 | | space is indicated. | 654 | Available | This optional field can be used to indicate the | 655 | free space | current free space available for storage. | 656 | Endpoint | This can be used to uniquely identify the sending | 657 | identifier | Saratoga peer, or the administrative node that the | 658 | | BEACON-sender is associated with. If Saratoga is | 659 | | being used with a bundle agent, a bundle endpoint ID | 660 | | (EID) can be used here. | 661 +------------+------------------------------------------------------+ 663 The Flags field is used to provide some additional information about 664 the peer. The first two octets of the Flags field is currently in 665 use. The later octet is for future use, and MUST be set to zero. 667 The two highest-order bits (bits 8 and 9 above) indicate the maximum 668 supported file size parameters that the peer's Saratoga 669 implementation permits. Other Saratoga packet types contain 670 variable-length fields that convey file sizes or offsets into a file 671 -- the file offset descriptors. These descriptors may be 16-bit, 32- 672 bit, 64-bit, or 128-bit in length, depending on the size of the file 673 being transferred and/or the integer types supported by the sending 674 peer. The indicated bounds for the possible values of these bits are 675 summarized below: 677 +-------+-------+-------------------------+-------------------+ 678 | Bit 8 | Bit 9 | Supported Field Sizes | Maximum File Size | 679 +-------+-------+-------------------------+-------------------+ 680 | 0 | 0 | 16 bits | 2^16 - 1 octets. | 681 | 0 | 1 | 16 or 32 bits | 2^32 - 1 octets. | 682 | 1 | 0 | 16, 32, or 64 bits | 2^64 - 1 octets. | 683 | 1 | 1 | 16, 32, 64, or 128 bits | 2^128 - 1 octets. | 684 +-------+-------+-------------------------+-------------------+ 686 If a Saratoga peer advertises it is capable of receiving a certain 687 size of file, then it MUST also be capable of receiving files sent 688 using smaller descriptor values. This avoids overhead on small 689 files, while increasing interoperability between peers. 691 It is likely when sending unbounded streams that a larger offset 692 descriptor field size will be preferred to minimise problems with 693 offset sequences wrapping. Protecting against sequence wrapping is 694 discussed in the STATUS section. 696 +-----+-------+-----------------------------------------------------+ 697 | Bit | Value | Meaning | 698 +-----+-------+-----------------------------------------------------+ 699 | 10 | 0 | not able to pass bundles to a local bundle agent; | 700 | | | handles files only. | 701 | 10 | 1 | handles files, but can also pass marked bundles to | 702 | | | a local bundle agent. | 703 +-----+-------+-----------------------------------------------------+ 704 Bit 10 is reserved for DTN bundle agent use, indicating whether the 705 sender is capable of handling bundles via a local bundle agent. This 706 is described in [I-D.wood-dtnrg-saratoga]. 708 +-----+-------+--------------------------------------+ 709 | Bit | Value | Meaning | 710 +-----+-------+--------------------------------------+ 711 | 11 | 0 | not capable of supporting streaming. | 712 | 11 | 1 | capable of supporting streaming. | 713 +-----+-------+--------------------------------------+ 715 Bit 11 is used to indicate whether the sender is capable of sending 716 and receiving continuous streams. 718 +--------+--------+------------------------------------------------+ 719 | Bit 12 | Bit 13 | Capability and willingness to send files | 720 +--------+--------+------------------------------------------------+ 721 | 0 | 0 | cannot send files at all. | 722 | 0 | 1 | invalid. | 723 | 1 | 0 | capable of sending, but not willing right now. | 724 | 1 | 1 | capable of and willing to send files. | 725 +--------+--------+------------------------------------------------+ 727 +-------+-------+---------------------------------------------------+ 728 | Bit | Bit | Capability and willingness to receive files | 729 | 14 | 15 | | 730 +-------+-------+---------------------------------------------------+ 731 | 0 | 0 | cannot receive files at all. | 732 | 0 | 1 | invalid. | 733 | 1 | 0 | capable of receiving, but unwilling. Will reject | 734 | | | METADATA or DATA packets. | 735 | 1 | 1 | capable of and willing to receive files. | 736 +-------+-------+---------------------------------------------------+ 738 Also in the Flags field, bits 12 and 14 act as capability bits, while 739 bits 13 and 15 augment those flags with bits indicating current 740 willingness to use the capability. 742 Bits 12 and 13 deal with sending, while bits 14 and 15 deal with 743 receiving. If bit 12 is set, then the peer has the capability to 744 send files. If bit 14 is set, then the peer has the capability to 745 receive files. Bits 13 and 15 indicate willingness to send and 746 receive files, respectively. 748 A peer that is able to act as a file-sender MUST set the capability 749 bit 12 in all BEACONs that it sends, regardless of whether it is 750 willing to send any particular files to a particular peer at a 751 particular time. Bit 13 indicates the current presence of data to 752 send and a willingness to send it in general, in order to augment the 753 capability advertised by bit 12. 755 If bit 14 is set, then the peer is capable of acting as a receiver, 756 although it still might not currently be ready or willing to receive 757 files (for instance, it may be low on free storage). This bit MUST 758 be set in any BEACON packets sent by nodes capable of acting as file- 759 receivers. Bit 15 augments this by expresses a current general 760 willingness to receive and accept files. 762 +-----+-------+-----------------------------------------------------+ 763 | Bit | Value | Meaning | 764 +-----+-------+-----------------------------------------------------+ 765 | 16 | 0 | supports DATA transfers over UDP only. | 766 | 16 | 1 | supports DATA transfers over both UDP and UDP-Lite. | 767 +-----+-------+-----------------------------------------------------+ 769 Bit 16 is used to indicate whether the sender is capable of sending 770 and receiving unreliable transfers via UDP-Lite. 772 +-----+-------+-----------------------------------------------------+ 773 | Bit | Value | Meaning | 774 +-----+-------+-----------------------------------------------------+ 775 | 17 | 0 | available free space is not advertised in this | 776 | | | BEACON. | 777 | 17 | 1 | available free space is advertised in this BEACON. | 778 +-----+-------+-----------------------------------------------------+ 780 Bit 17 is used to indicate whether the sender is indicating how much 781 free space is indicated in an optional field in this BEACON packet. 782 If bit 17 is set, then bits 18 and 19 are used to indicate the size 783 in bits of the optional free-space-size field. If bit 17 is not set, 784 then bits 18 and 19 are zero. 786 +--------+--------+--------------------------+ 787 | Bit 18 | Bit 19 | Size of free space field | 788 +--------+--------+--------------------------+ 789 | 0 | 0 | 16 bits. | 790 | 0 | 1 | 32 bits. | 791 | 1 | 0 | 64 bits. | 792 | 1 | 1 | 128 bits. | 793 +--------+--------+--------------------------+ 795 The free space field size can vary as indicated by a varying-size 796 field indicated in bits 18 and 19 of the flags field. Unlike other 797 offset descriptor use where the value in the descriptor indicates a 798 byte or octet position for retransmission, or gives a file size in 799 bytes, this particular field indicates the available free space in 800 KILOBYTES (KiB, 1024 byte multiples), rather than octets. (Kilobytes 801 are used as storage can be in local memory.) Available free space is 802 rounded down to the nearest KiB, so advertising zero means that less 803 than 1KiB is free and available. Advertising the maximum size 804 possible in the field means that more free space than that is 805 available. While this field is intended to be scalable, it is 806 expected that 32 bits (up to 4TiB) will be most common in use. 808 A BEACON unicast to an individual peer MAY choose to indicate the 809 free space available for use by that particular peer, and MAY 810 indicate capabilities only available to that particular peer, 811 overriding or supplementing the properties advertised to all local 812 peers by multicast BEACONs. 814 Any type of host identifier can be used in the endpoint identifier 815 field, as long as it is a reasonably unique string within the range 816 of operational deployment. This field encompasses the remainder of 817 the packet, and might contain non-UTF-8 and/or null characters. 819 4.2. REQUEST 821 A REQUEST packet is an explicit command to perform either a _get_, 822 _getdir_, or _delete_ transaction. 824 Format 826 0 1 2 3 827 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 828 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 829 |0 1| Type | Flags | 830 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 831 | Id | 832 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 833 | variable-length File Path ... / 834 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 835 / / 836 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 837 / | null byte | / 838 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 839 / variable-length Authentication Field (optional) | 840 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 842 where 843 +--------+----------------------------------------------------------+ 844 | Field | Description | 845 +--------+----------------------------------------------------------+ 846 | Type | 1 | 847 | Flags | provide additional information about the requested | 848 | | file/operation; see table below for definition. | 849 | Id | uniquely identifies the transaction between two peers. | 850 | File | the path of the requested file/directory following the | 851 | Path | rules described below. | 852 +--------+----------------------------------------------------------+ 854 The Id that is used during transactions serves to uniquely associate 855 a given packet with a particular transaction. This enables multiple 856 simultaneous data transfer or request/status transactions between two 857 peers, with each peer deciding how to multiplex and prioritise the 858 parallel flows it sends. The Id for a transaction is selected by the 859 initiator so as to not conflict with any other in-progress or recent 860 transactions with the same host. This Id should be unique and 861 generated using properties of the file, which will remain constant 862 across a host reboot. The 3-tuple of both host identifiers and a 863 carefully-generated transaction Id field can be used to uniquely 864 index a particular transaction's state. 866 In the Flags field, the bits labelled 8 and 9 in the figure above 867 indicate the maximum supported file length fields that the peer can 868 handle, and are interpreted exactly as the bits 8 and 9 in the BEACON 869 packet described above. The remaining defined bits are: 871 +-----+-------+-----------------------------------------------------+ 872 | Bit | Value | Meaning | 873 +-----+-------+-----------------------------------------------------+ 874 | 10 | 0 | The requester cannot handle bundles locally. | 875 | 10 | 1 | The requester can handle bundles. | 876 | 11 | 0 | The requester cannot receive streams. | 877 | 11 | 1 | The requester is also able to receive streams. | 878 | 14 | 0 | a _get_ or _getdir_ transaction is requested | 879 | 14 | 1 | a _delete_ transaction is requested | 880 | 15 | 0 | the File Path field holds a file for a _get_ or | 881 | | | _delete_ | 882 | 15 | 1 | the File Path field specifies a directory name for | 883 | | | a _getdir_ or _delete_ | 884 | 16 | 0 | The requester is able to receive DATA over UDP | 885 | | | only. | 886 | 16 | 1 | The requester is also able to receive DATA over | 887 | | | UDP-Lite. | 888 +-----+-------+-----------------------------------------------------+ 890 The File Path portion of a _get_ packet is a null-terminated UTF-8 891 encoded string [RFC3629] that represents the path and base file name 892 on the file-sender of the file (or directory) that the file-receiver 893 wishes to perform the _get_, _getdir_, or _delete_ operation on. 894 Implementations SHOULD only send as many octets of File Path as are 895 needed for carrying this string, although some implementations MAY 896 choose to send a fixed-size File Path field in all REQUEST packets 897 that is filled with null octets after the last UTF-8 encoded octet of 898 the path. A maximum of 1024 octets for this field, and for the File 899 Path fields in other Saratoga packet types, is used to limit the 900 total packet size to within a single IPv6 minimum MTU (minus some 901 padding for network layer headers), and thus avoid the need for 902 fragmentation. The 1024-octet maximum applies after UTF-8 encoding 903 and null termination. 905 As in the standard Internet File Transfer Protocol (FTP) [RFC0959], 906 for path separators, Saratoga allows the local naming convention on 907 the peers to be used. There are security implications to processing 908 these strings without some intelligent filtering and checking on the 909 filesystem items they refer to, as discussed in the Security 910 Considerations section later within this document. 912 If the File Path field is empty, i.e. is a null-terminated zero- 913 length string one octet long, then this indicates that the file- 914 receiver is ready to receive any file that the file-sender would like 915 to send it, rather than requesting a particular file. This allows 916 the file-sender to determine the order and selection of files that it 917 would like to forward to the receiver in more of a "push" manner. Of 918 course, file retrieval could also follow a "pull" manner, with the 919 file-receiving host requesting specific files from the file-sender. 920 This may be desirable at times if the file-receiver is low on storage 921 space, or other resources. The file-receiver could also use the 922 Saratoga _getdir_ transaction results in order to select small files, 923 or make other optimizations, such as using its local knowledge of 924 contact times to pick files of a size likely to be able to be 925 delivered completely. File transfer through pushing sender-selected 926 files implements delivery prioritization decisions made solely at the 927 Saratoga file-sending node. File transfer through pulling specific 928 receiver-selected files implements prioritization involving more 929 participation from the Saratoga file-receiver. This is how Saratoga 930 implements Quality of Service (QoS). 932 The null-terminated File Path string MAY be followed by an optional 933 Authentication Field that can be used to validate the REQUEST packet. 934 Any value in the Authentication Field is the result of a computation 935 of packet contents that SHOULD include, at a minimum, source and 936 destination IP addresses and port numbers and packet length in a 937 'pseudo-header', as well as the content of all Saratoga fields from 938 Version to File Path, excluding the predictable null-termination 939 octet. This Authentication Field can be used to allow the REQUEST 940 receiver to discriminate between other peers, and permit and deny 941 various REQUEST actions as appropriate. The format of this field is 942 unspecified for local use. 944 REQUEST packets may be sent multicast, to learn about all listening 945 nodes. A multicast _get_ request for a file that elicits multiple 946 METADATA or DATA responses should be followed by unicast STATUS 947 packets with status errors cancelling all but one of the proposed 948 transfers. File timestamps in the Directory Entry can be used to 949 select the most recent version of an offered file, and the host to 950 fetch it from. 952 If the receiver already has the file at the expected file path and is 953 requesting an update to that file, REQUEST can be sent after a 954 METADATA advertising that file, to allow the sender to determine 955 whether a replacement for the file should be sent. 957 Delete requests are ignored for files currently being transferred. 959 4.3. METADATA 961 METADATA packets are sent as part of a data transfer transaction 962 (_get_, _getfile_, and _put_). A METADATA packet says how large the 963 file is and what its name is, as well as what size of file offset 964 descriptor is chosen for the session. METADATA packets are optional. 965 They are normally sent at the start of a DATA transfer, but may be 966 repeated if requested. 968 Format 970 0 1 2 3 971 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 972 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 973 |0 1| Type | Flags |Sumtype| 974 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 975 | Id | 976 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 977 | / 978 / / 979 / example error-detection checksum (128-bit MD5 shown) / 980 / / 981 / | 982 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 983 | / 984 / single Directory Entry describing file / 985 / (variable length) / 986 / // 987 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 989 where 991 +-----------+-------------------------------------------------------+ 992 | Field | Description | 993 +-----------+-------------------------------------------------------+ 994 | Type | 2 | 995 | Flags | indicate additional boolean metadata about a file | 996 | Sumtype | indicates whether a checksum is present after the Id, | 997 | | and what type it is. | 998 | Id | identifies the transaction that this packet describes | 999 | Checksum | an example included checksum covering file contents | 1000 | Directory | describes file system information about the file, | 1001 | Entry | including file length, file timestamps, etc.; the | 1002 | | format is specified in Section 5 | 1003 +-----------+-------------------------------------------------------+ 1005 The first octet of the Flags field is currently specified for use. 1006 The later two octets are reserved for future use, and MUST be set to 1007 zero. 1009 In the Flags field, the bits labelled 8 and 9 in the figure above 1010 indicate the exact size of the offset descriptor fields used in this 1011 particular packet and are interpreted exactly as the bits 8 and 9 in 1012 the BEACON packet described above. The value of these bits 1013 determines the size of the File Length field in the current packet, 1014 as well as indicating the size of the offset fields used in DATA and 1015 STATUS packets within the session that will follow this packet. 1017 +--------+--------+-------------------------------------------------+ 1018 | Bit 10 | Bit 11 | Type of transfer | 1019 +--------+--------+-------------------------------------------------+ 1020 | 0 | 0 | a file is being sent. | 1021 | 0 | 1 | the file being sent should be interpreted as a | 1022 | | | directory record. | 1023 | 1 | 0 | a bundle is being sent. | 1024 | 1 | 1 | an indefinite-length stream is being sent. | 1025 +--------+--------+-------------------------------------------------+ 1027 Also inside the Flags field, bits 10 and 11 indicate what is being 1028 transferred - a file, special file that contains directory records, 1029 bundle, or stream. The value 01 indicates that the METADATA and DATA 1030 packets are being generated in response to a _getdir_ REQUEST, and 1031 that the assembled DATA contents should be interpreted as a sequence 1032 of Directory Records, as defined in Section 5. 1034 +-----+-------+-----------------------------------------------------+ 1035 | Bit | Value | Meaning | 1036 +-----+-------+-----------------------------------------------------+ 1037 | 12 | 0 | This transfer is in progress. | 1038 | 12 | 1 | This transfer is no longer in progress, and has | 1039 | | | been terminated. | 1040 +-----+-------+-----------------------------------------------------+ 1042 Bit 12 indicates whether the transfer is in progress, or has been 1043 terminated by the sender. It is normally set to 1 only when METADATA 1044 is resent to indicate that a stream transfer has been ended. 1046 +--------+----------------------------------------------------------+ 1047 | Bit 13 | Use | 1048 +--------+----------------------------------------------------------+ 1049 | 0 | This file's content MUST be delivered reliably without | 1050 | | errors using UDP. | 1051 | 1 | This file's content MAY be delivered unreliably, without | 1052 | | errors, or partly unreliably, where errors are | 1053 | | tolerated, using UDP-Lite. | 1054 +--------+----------------------------------------------------------+ 1056 Bit 13 indicates whether the file must be sent reliably or can be 1057 sent at least partly unreliably, using UDP-Lite. This flag SHOULD 1058 only be set if the originator of the file knows that at least some of 1059 the file content is suitable for sending unreliably and is robust to 1060 errors. This flag reflects a property of the file itself. This flag 1061 may still be set if the immediate file-receiver is only capable of 1062 UDP delivery, on the assumption that this preference will be 1063 preserved for later transfers where UDP-Lite transfers may be taken 1064 advantage of by senders with knowledge of the internal file 1065 structure. The file-sender may know that the receiver is capable of 1066 handling UDP-Lite, either from a _get_ REQUEST, from exchange of 1067 BEACONs, or a-priori. 1069 The high four bits of the Flags field, bits 28-31, are used to 1070 indicate if an error-detection checksum has been included in the 1071 METADATA for the file to be transferred. Here, bits 0000 indicate 1072 that no checksum is present, with the implicit assumption that the 1073 application will do its own end-to-end check. Other values indicate 1074 the type of checksum to use. The choice of checksum depends on the 1075 available computing power and the length of the file to be 1076 checksummed. Longer files require stronger checksums to ensure 1077 error-free delivery. The checksum of the file to be transferred is 1078 carried as shown, with a fixed-length field before the varying-length 1079 File Length and File Name information fields. 1081 Assigned values for the checksum type field are: 1083 +-----------+-------------------------------------------------------+ 1084 | Value | Use | 1085 | (0-15) | | 1086 +-----------+-------------------------------------------------------+ 1087 | 0 | No checksum is provided. | 1088 | 1 | 32-bit CRC32 checksum, suitable for small files. | 1089 | 2 | 128-bit MD5 checksum, suitable for larger files. | 1090 | 3 | 160-bit SHA-1 checksum, suitable for larger files but | 1091 | | slower to process than MD5. | 1092 +-----------+-------------------------------------------------------+ 1094 It is expected that higher values will be allocated to new and 1095 stronger checksums able to better protect larger files. A checksum 1096 SHOULD be included for files being transferred. The checksum SHOULD 1097 be as strong as possible. Streaming of an indefinite-length stream 1098 MUST set the checksum type field to zero. 1100 It is expected that a minimum of the MD5 checksum will be used, 1101 unless the Saratoga implementation is used exclusively for small 1102 transfers at the low end of the 16-bit file descriptor range, such as 1103 on low-performing hardware, where the weaker CRC-32c checksum can 1104 suffice. 1106 The CRC32 checksum is computed as described for the CRC-32c algorithm 1107 given in [RFC3309]. 1109 The MD5 Sum field is generated via the MD5 algorithm [RFC1321], 1110 computed over the entire contents of the file being transferred. The 1111 file-receiver can compute the MD5 result over the reassembled 1112 Saratoga DATA packet contents, and compare this to the METADATA's MD5 1113 Sum field in order to gain confidence that there were no undetected 1114 protocol errors or UDP checksum weaknesses encountered during the 1115 transfer. Although MD5 is known to be less than optimal for security 1116 uses, it remains excellent for non-security use in error detection 1117 (as is done here in Saratoga), and has better performance 1118 implications than cryptographically-stronger alternatives given the 1119 limited available processing of many use cases. 1121 Checksums may be privately keyed for local use, to allow transmission 1122 of authenticated or encrypted files delivered in DATA packets. This 1123 has limitations, discussed further in Section 8 at end. 1125 Use of the checksum to ensure that a file has been correctly relayed 1126 to the receiving node is important. A provided checksum MUST be 1127 checked against the received data file. If checksum verification 1128 fails, either due to corruption or due to the receiving node not 1129 having the right key for a keyed checksum), the file MUST be 1130 discarded. If the file is to be relayed onwards later to another 1131 Saratoga peer, the metadata, including the checksum, MUST be retained 1132 with the file and SHOULD be retransmitted onwards unchanged with the 1133 file for end-to-end coverage. If it is necessary to recompute the 1134 checksum or encrypted data for the new peer, either because a 1135 different key is in use or the existing checksum algorithm is not 1136 supported, the new checksum MUST be computed before the old checksum 1137 is verified, to ensure overlapping checksum coverage and detect 1138 errors introduced in file storage. 1140 METADATA can be used as an indication to update copies of files. If 1141 the METADATA is in response to a _get_ REQUEST including a file 1142 record, and the record information for the held file matches what the 1143 requester already has, as has been indicated by a previously-received 1144 METADATA advertisement from the requester, then only the METADATA is 1145 sent repeating this information and verifying that the file is up to 1146 date. If the record information does not match and a newer file can 1147 be supplied, the METADATA begins a transfer with following DATA 1148 packets to update the file. 1150 4.4. DATA 1152 A series of DATA packets form the main part of a data transfer 1153 transaction (_get_, _put_, or _getdir_). The payloads constitute the 1154 actual file data being transferred. 1156 Format 1158 0 1 2 3 1159 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 1160 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1161 |0 1| Type | Flags | 1162 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1163 | Id | 1164 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1165 | / 1166 / Timestamp/nonce information (optional) / 1167 / / 1168 / | 1169 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1170 [ Offset (descriptor) ] 1171 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1173 where 1175 +-----------------+-------------------------------------------------+ 1176 | Field | Description | 1177 +-----------------+-------------------------------------------------+ 1178 | Type | 3 | 1179 | Flags 8 and 9 | bit 8 and 9 specify the size of offset | 1180 | | descriptor, as elsewhere. | 1181 | Flag 10 | bit 10, with bit 11, indicates whether a file, | 1182 | | bundle, stream or directory entry is being | 1183 | | carried. This bit will normally be zero for | 1184 | | files. | 1185 | Flag 11 | bit 11 is used with bit 10. Normally this bit | 1186 | | will be zero for files. | 1187 | Flag 12 | bit 12 indicates that an optional timestamp or | 1188 | | nonce is included in the DATA header before the | 1189 | | offset descriptor. | 1190 | Flag 15 | bit 15 requests an immediate STATUS ack to be | 1191 | | generated in response to receiving this packet. | 1192 | Id | identifies the transaction that this packet | 1193 | | belongs to | 1194 | Timestamp/nonce | is an optional 128-bit field providing timing | 1195 | | or identification information unique to this | 1196 | | packet. See Appendix A for details. | 1197 | Offset | the offset in octets to the location where the | 1198 | | first byte of this packet's payload is to be | 1199 | | written | 1200 +-----------------+-------------------------------------------------+ 1202 The DATA packet has a minimum size of ten octets, using sixteen-bit 1203 descriptors and no timestamps. 1205 DATA packets are normally sent error-free using UDP for reliable 1206 transfer (of both content and delivery). However, for transfers that 1207 can tolerate content errors, DATA packets MAY be sent using UDP-Lite. 1208 If UDP-Lite is used, the file-sender must know that the file-receiver 1209 is capable of handling UDP-Lite, and the file contents to be 1210 transferred should be resilient to errors. The UDP-Lite checksum 1211 MUST protect the Saratoga headers, up to and including the offset 1212 descriptor, and MAY protect more of each packet's payload, depending 1213 on the file-sender's knowledge of the internal structure of the file 1214 and the file's reliability requirements. 1216 Flag bits 8 and 9 are set to indicate the size of the offset 1217 descriptor as described for BEACON and METADATA packets, so that each 1218 DATA packet is self-describing. This allows the DATA packet to be 1219 used to construct a file even when the initial METADATA is lost and 1220 must be resent. The flag values for bits 8, 9, 10 and 11 MUST be the 1221 same as indicated in the initial METADATA packet. 1223 +--------+--------+-------------------------------------------------+ 1224 | Bit 10 | Bit 11 | Type of transfer | 1225 +--------+--------+-------------------------------------------------+ 1226 | 0 | 0 | a file is being sent. | 1227 | 0 | 1 | the file being sent should be interpreted as a | 1228 | | | directory record. | 1229 | 1 | 0 | a bundle is being sent. | 1230 | 1 | 1 | an indefinite-length stream is being sent. | 1231 +--------+--------+-------------------------------------------------+ 1233 Also inside the Flags field, bits 10 and 11 indicate what is being 1234 transferred - a file, special file that contains directory records, 1235 bundle, or stream. The value 01 indicates that the METADATA and DATA 1236 packets are being generated in response to a _getdir_ REQUEST, and 1237 that the assembled DATA contents should be interpreted as a sequence 1238 of Directory Records, as defined in Section 5. 1240 +-----+-------+-----------------------------------------------------+ 1241 | Bit | Value | Meaning | 1242 +-----+-------+-----------------------------------------------------+ 1243 | 12 | 0 | This packet does not include an optional | 1244 | | | timestamp/nonce field. | 1245 | 12 | 1 | This packet includes an optional timestamp/nonce | 1246 | | | field. | 1247 +-----+-------+-----------------------------------------------------+ 1249 Flag bit 12 indicates that an optional packet timestamp/nonce is 1250 carried in the packet before the offset field. This packet 1251 timestamp/nonce field is always sixteen octets (128 bits) long. 1252 Timestamps can be useful to the sender even when the receiver does 1253 not understand them, as the receiver can simply echo any provided 1254 timestamps back, as specified for STATUS packets, to allow the sender 1255 to monitor flow conditions. Packet timestamps are particularly 1256 useful when streaming. Packet timestamps are discussed further in 1257 Appendix A. 1259 +-----+-------+-------------------------------+ 1260 | Bit | Value | Meaning | 1261 +-----+-------+-------------------------------+ 1262 | 15 | 0 | No response is requested. | 1263 | 15 | 1 | A STATUS packet is requested. | 1264 +-----+-------+-------------------------------+ 1266 Within the Flags field, if bit 15 of the packet is set, the file- 1267 receiver is to immediately generate a STATUS packet to provide the 1268 file-sender with up-to-date information regarding the status of the 1269 file transfer. This flag is set carefully and rarely. This flag may 1270 be set periodically, but infrequently. Asymmetric links with 1271 constrained backchannels can only carry a limited amount of STATUS 1272 packets before ack congestion becomes a problem. This flag SHOULD 1273 NOT be set if an unreliable stream is being transferred, or if 1274 multicast is in use. This flag SHOULD be set periodically for 1275 reliable file transfers, or reliable streaming. 1277 +-----+-------+----------------------------------+ 1278 | Bit | Value | Meaning | 1279 +-----+-------+----------------------------------+ 1280 | 16 | 0 | Normal use. | 1281 | 16 | 1 | The EOD End of Data flag is set. | 1282 +-----+-------+----------------------------------+ 1284 The End of Data flag is set in DATA packets carrying the last byte of 1285 a transfer. This is useful for streams and for Saratoga 1286 implementations that do not support METADATA. 1288 Immediately following the DATA header is the payload, which consumes 1289 the remainder of the packet and whose length is implicitly defined by 1290 the end of the packet. The payload octets are directly formed from 1291 the continuous octets starting at the specified Offset in the file 1292 being transferred. No special coding is performed. A zero-octet 1293 payload length is allowable. 1295 The length of the Offset fields used within all DATA packets for a 1296 given transaction MUST be consistent with the length indicated by 1297 bits 8 and 9 of the transactions METADATA packet. If the METADATA 1298 packet has not yet been received, a file-receiver SHOULD request it 1299 via a STATUS packet, and MAY choose to enqueue received DATA packets 1300 for later processing after the METADATA arrives. 1302 4.5. STATUS 1304 The STATUS packet type is the single acknowledgement method that is 1305 used for feedback from a Saratoga receiver to a Saratoga sender to 1306 indicate transaction progress, both as a response to a REQUEST, and 1307 as a response to a DATA packet when demanded or volunteered. 1309 When responding to a DATA packet, the STATUS packet MAY, as needed, 1310 include selective acknowledgement (SNACK) 'hole' information to 1311 enable transmission (usually re-transmission) of specific sets of 1312 octets within the current transaction (called "holes"). This 1313 'holestofill' information can be used to clean up losses (or indicate 1314 no losses) at the end of, or during, a transaction, or to efficiently 1315 resume a transfer that was interrupted in a previous transaction. 1317 Format 1319 0 1 2 3 1320 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 1321 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1322 |1 0| Type | Flags | Status | 1323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1324 | Id | 1325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1326 | / 1327 / Timestamp/nonce information (optional) / 1328 / / 1329 / | 1330 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1331 [ Progress Indicator (descriptor) ] 1332 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1333 [ In-Response-To (descriptor) ] 1334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1335 | (possibly, several Hole fields) / 1336 / ... / 1337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1339 where 1340 +----------------+--------------------------------------------------+ 1341 | Field | Description | 1342 +----------------+--------------------------------------------------+ 1343 | Type | 4 | 1344 | Flags | are defined below. | 1345 | Id | identifies the transaction that this packet | 1346 | | belongs to. | 1347 | Status | a value of 0x00 indicates the transfer is | 1348 | | sucessfully proceeding. All other values are | 1349 | | errors terminating the transfer, explained | 1350 | | below. | 1351 | Zero-Pad | an octet fixed at 0x00 to allow later fields to | 1352 | | be conveniently aligned for processing. | 1353 | Timestamp | an optional fixed 128-bit field, that is only | 1354 | (optional) | present and used to return a packet timestamp if | 1355 | | the timestamp flag is set. If the STATUS packet | 1356 | | is voluntary and the voluntary flag is set, this | 1357 | | should repeat the timestamp of the DATA packet | 1358 | | containing the highest offset seen. If the | 1359 | | STATUS packet is in response to a mandatory | 1360 | | request, this will repeat the timestamp of the | 1361 | | requesting DATA packet. The file-sender may use | 1362 | | these timestamps to estimate latency.Packet | 1363 | | timestamps are particularly useful when | 1364 | | streaming. There are special considerations for | 1365 | | streaming, to protect against the ambiguity of | 1366 | | wrapped offset descriptor sequence numbers, | 1367 | | discussed below. Packet timestamps are | 1368 | | discussed further in Appendix A. | 1369 | Progress | the offset of the lowest-numbered octet of the | 1370 | Indicator | file not yet received. | 1371 | In-Response-To | the offset of the highest-numbered octet within | 1372 | (descriptor) | a DATA packet that generated this STATUS packet, | 1373 | | or the offset of the highest-numbered octet seen | 1374 | | if this STATUS is generated voluntarily and the | 1375 | | voluntary flag is set. | 1376 | Holes | indications of offset ranges of missing data, | 1377 | | defined below. | 1378 +----------------+--------------------------------------------------+ 1380 The STATUS packet has a minimum size of twelve octets, using sixteen- 1381 bit descriptors, a progress indicator but no Hole fields, and no 1382 timestamps. The progress indicator is always zero when responding to 1383 requests that may initiate a transfer. 1385 The Id field is needed to associate the STATUS packet with the 1386 transaction that it refers to. 1388 Flags bits 8 and 9 are set to indicate the size of the offset 1389 descriptor as described for BEACON and METADATA packets, so that each 1390 STATUS packet is self-describing. The flag values here MUST be the 1391 same as indicated in the initial METADATA and DATA packets. 1393 Other bits in the Flags field are defined as: 1395 +-----+-------+---------------------------------------------------+ 1396 | Bit | Value | Meaning | 1397 +-----+-------+---------------------------------------------------+ 1398 | 12 | 0 | This packet does not include a timestamp field. | 1399 | 12 | 1 | This packet includes an optional timestamp field. | 1400 +-----+-------+---------------------------------------------------+ 1402 Flag bit 12 indicates that an optional sixteen-byte packet timestamp/ 1403 nonce field is carried in the packet before the Progress Indicator 1404 descriptor, as discussed for the DATA packet format. Packet 1405 timestamps are discussed further in Appendix A. 1407 +-----+-------+----------------------------------------+ 1408 | Bit | Value | Meaning | 1409 +-----+-------+----------------------------------------+ 1410 | 13 | 0 | file's METADATA has been received. | 1411 | 13 | 1 | file's METADATA has not been received. | 1412 +-----+-------+----------------------------------------+ 1414 If bit 13 of a STATUS packet has been set to indicate that the 1415 METADATA has not yet been received, then the METADATA should be 1416 resent. This flag should normally be clear. 1418 A receiver SHOULD tolerate lost METADATA that is later resent, but 1419 MAY insist on receiving METADATA at the start of a transfer. This is 1420 done by responding to early DATA packets with a voluntary STATUS 1421 packet that sets this flag bit, reports a status error code 0x10, 1422 sets the Progress Indicator field to zero, and does not include 1423 HOLESTOFILL information. 1425 +-----+-------+-----------------------------------------------------+ 1426 | Bit | Value | Meaning | 1427 +-----+-------+-----------------------------------------------------+ 1428 | 14 | 0 | this packet contains the complete current set of | 1429 | | | holes at the file-receiver. | 1430 | 14 | 1 | this packet contains incomplete hole-state; holes | 1431 | | | shown in this packet should supplement other | 1432 | | | incomplete hole-state known to the file-sender. | 1433 +-----+-------+-----------------------------------------------------+ 1435 Bit 14 of a 'holestofill' STATUS packet is only set when there are 1436 too many holes to fit within a single STATUS packet due to MTU 1437 limitations. This causes the hole list to be spread out over 1438 multiple STATUS packets, each of which conveys distinct sets of 1439 holes. This could occur, for instance, in a large file _put_ 1440 scenario with a long-delay feedback loop and poor physical layer 1441 conditions. These multiple STATUS packets will share In-Response-To 1442 information. When losses are light and/or hole reporting and repair 1443 is relatively frequent, all holes should easily fit within a single 1444 STATUS packet, and this flag will be clear. Bit 14 should normally 1445 be clear. 1447 In some rare cases of high loss, there may be too many holes in the 1448 received data to convey within a single STATUS's size, which is 1449 limited by the link MTU size. In this case, multiple STATUS packets 1450 may be generated, and Flags bit 14 should be set on each STATUS 1451 packet accordingly, to indicate that each packet holds incomplete 1452 results. The complete group of STATUS packets, each containing 1453 incomplete information, will share common In-Response-To information 1454 to distinguish them from any earlier groups. 1456 +-----+-------+-----------------------------------------------+ 1457 | Bit | Value | Meaning | 1458 +-----+-------+-----------------------------------------------+ 1459 | 15 | 0 | This STATUS was requested by the file-sender. | 1460 | 15 | 1 | This STATUS is sent voluntarily. | 1461 +-----+-------+-----------------------------------------------+ 1463 Flag bit 15 indicates whether the STATUS is sent voluntarily or due 1464 to a request by the sender. It affects content of the In-Response-To 1465 timestamp and descriptor fields. 1467 In the case of a transfer proceeding normally, immediately following 1468 the STATUS packet header shown above, is a set of "Hole" definitions 1469 indicating any lost packets. Each Hole definition is a pair of 1470 unsigned integers. For a 32-bit offset descriptor, each Hole 1471 definition consists of two four-octet unsigned integers: 1473 Hole Definition Format 1475 0 1 2 3 1476 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 1477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1478 [ offset to start of hole (descriptor) ] 1479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1480 [ offset to end of hole (descriptor) ] 1481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1483 The start of the hole means the offset of the first unreceived byte 1484 in that hole. The end of the hole means the last unreceived byte in 1485 that hole. 1487 For 16-bit descriptors, each Hole definition holds two two-octet 1488 unsigned integers, while Hole definitions for 64- and 128-bit 1489 descriptors require two eight- and two sixteen-octet unsigned 1490 integers respectively. 1492 Since each Hole definition takes up eight octets when 32-bit offset 1493 lengths are used, we expect that well over 100 such definitions can 1494 fit in a single STATUS packet, given the IPv6 minimum MTU. (There 1495 may be cases where there is a very constrained backchannel compared 1496 to the forward channel streaming DATA packets. For these cases, 1497 implementations might deliberately request large holes that span a 1498 number of smaller holes and intermediate areas where DATA has already 1499 been received, so that previously-received DATA is deliberately 1500 resent. This aggrgation of separate holes keeps the backchannel 1501 STATUS packet size down to avoid backchannel congestion.) 1503 A 'voluntary' STATUS can be sent at the start of each transaction, 1504 once METADATA information has been received. This indicates that the 1505 receiver is ready to receive the file, or indicates an error or 1506 rejection code, described below. A STATUS indicating a successfully 1507 established transfer has a Progress Indicator of zero and an In- 1508 Response-To field of zero. 1510 On receiving a STATUS packet, the sender SHOULD prioritize sending 1511 the necessary data to fill those holes, in order to advance the 1512 Progress Indicator at the receiver. 1514 The sender infers a completely-received transfer from the reported 1515 receiver window position. In the final STATUS packet sent by the 1516 receiver once the file to be transferred has been completely 1517 received, bit 14 MUST be 0 (indicating a complete set of holes in 1518 this packet), there MUST NOT be any holestofill offset pairs 1519 indicating holes, the In-Response-To field points to the last byte of 1520 the file, and the voluntary flag MUST be set. This 'completed' 1521 STATUS may be repeated, depending on subsequent sender behaviour, 1522 while internal state about the transfer remains available to the 1523 receiver. 1525 Because METADATA is optional in implementations, the file receiver 1526 may not know the length of a file if METADATA is never sent. The 1527 sender MUST set the EOD End of Data flag in each DATA packet that 1528 sends the last byte of the file, and SHOULD request a STATUS 1529 acknowledgement when the EOD flag is set. If METADATA has been sent 1530 and the EOD comes earlier than a previously reported length of a 1531 file, an unspecified error 0x01, as described below, is returned in 1532 the STATUS message responding to that DATA packet and EOD flag. If a 1533 stream is being marked EOD, the receiver acknowledges this with a 1534 Success 0x00 code. 1536 In the case of an error causing a transfer to be aborted, the Status 1537 field holds a code that can be used to explain the cause of the error 1538 to the other peer. A zero value indicates that there have been no 1539 significant errors (this is called a "success STATUS" within this 1540 document), while any non-zero value means the transaction should be 1541 aborted (this is called a "failure STATUS"). 1543 +-------------------+-----------------------------------------------+ 1544 | Error Code Status | Meaning | 1545 | Value | | 1546 +-------------------+-----------------------------------------------+ 1547 | 0x00 | Success, No Errors. | 1548 | 0x01 | Unspecified Error. | 1549 | 0x02 | Unable to send file due to resource | 1550 | | constraints. | 1551 | 0x03 | Unable to receive file due to resource | 1552 | | constraints. | 1553 | 0x04 | File not found. | 1554 | 0x05 | Access Denied. | 1555 | 0x06 | Unknown Id field for transaction. | 1556 | 0x07 | Did not delete file. | 1557 | 0x08 | File length is longer than REQUEST indicates | 1558 | | support for. | 1559 | 0x09 | File offset descriptors do not match expected | 1560 | | use or file length. | 1561 | 0x0A | Unsupported packet type received. | 1562 | 0x0B | DATA flag bits describing transfer have | 1563 | | changed unexpectedly. | 1564 | 0x0C | Receiver is no longer interested in receiving | 1565 | | this file. | 1566 | 0x0D | Receiver wants sender to pause its transfer. | 1567 | 0x0E | Receiver wants sender to resume a | 1568 | | previously-paused transfer. | 1569 | 0x0F | File is in use. | 1570 | 0x10 | METADATA required before transfer can be | 1571 | | accepted. | 1572 +-------------------+-----------------------------------------------+ 1574 The recipient of a failure STATUS MUST NOT try to process the 1575 Progress Indicator, In-Response-To, or Hole offsets, because, in some 1576 types of error conditions, the packet's sender may not have any way 1577 of setting them to the right length for the transaction. 1579 When sending an indefinite-length stream, the possibility of offset 1580 sequence numbers wrapping back to zero must be considered. This can 1581 be protected against by using large offsets, and by the stream 1582 receiver. The receiver MUST separate out holes before the offset 1583 wraps to zero from holes after the wrap, and send Hole definitions in 1584 different STATUS packets, with Flag 14 set to mark them as 1585 incomplete. Any Hole straddling a sequence wrap MUST be broken into 1586 two separate Holes, with the second Hole starting at zero. The 1587 timestamps in STATUS packets carrying any pre-wrap holes should be 1588 earlier than the timestamp in later packets, and should repeat the 1589 timestamp of the last DATA packet seen for that offset sequence 1590 before the following wrap to zero occurred. Receivers indicate that 1591 they no longer wish to receive streams by sending Status Code 0x0C. 1593 5. The Directory Entry 1595 Directory Entries have two uses within Saratoga: 1597 1. Within a METADATA packet, a Directory Entry is used to give 1598 information about the file being transferred, in order to 1599 facilitate proper reassembly of the file and to help the file- 1600 receiver understand how recently the file may have been created 1601 or modified. 1603 2. When a peer requests a directory listing via a _getdir_ REQUEST, 1604 the other peer generates a file containing a series of one or 1605 more concatenated Directory Entry records, and transfers this 1606 file as it would transfer the response to a normal _get_ REQUEST, 1607 sending the records together within DATA packets. This file may 1608 be either temporary or within-memory and not actually a part of 1609 the host's file system itself. 1611 Directory Entry Format 1613 0 1 2 3 1614 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 1615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1616 [ Size (descriptor) ] 1617 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1618 | Mtime | 1619 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1620 | Ctime | 1621 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1622 | Properties | / 1623 +-+-+-+-+-+-+-+-+ / 1624 / / 1625 / File Path (max 1024 octets,variable length) / 1626 / ... // 1627 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1629 where 1631 +------------+------------------------------------------------------+ 1632 | field | description | 1633 +------------+------------------------------------------------------+ 1634 | Size | the size of the file or directory in octets. | 1635 | Mtime | a timestamp showing when the file or directory was | 1636 | | modified. | 1637 | Ctime | a timestamp of the last status change for this file | 1638 | | or directory. | 1639 | Properties | if set, bit 7 of this field indicates that the entry | 1640 | | corresponds to a directory. Bit 6, if set, | 1641 | | indicates that the file is "special". A special | 1642 | | file may not be directly transferable as it | 1643 | | corresponds to a symbolic link, a named pipe, a | 1644 | | device node, or some other "special" filesystem | 1645 | | object. A file-sender may simply choose not to | 1646 | | include these types of files in the results of a | 1647 | | _getdir_ request. | 1648 | File Path | contains the file's name relative within the | 1649 | | requested path of the _getdir_ transaction, a | 1650 | | maximum of 1024-octet UTF-8 string, that is | 1651 | | null-terminated to indicate the beginning of the | 1652 | | next directory entry in _getdir_ results | 1653 +------------+------------------------------------------------------+ 1654 +-------+-------+---------------------+ 1655 | Bit 6 | Bit 7 | Properties conveyed | 1656 +-------+-------+---------------------+ 1657 | 0 | 0 | normal file. | 1658 | 0 | 1 | normal directory. | 1659 | 1 | 0 | special file. | 1660 | 1 | 1 | special directory. | 1661 +-------+-------+---------------------+ 1663 Whether a particular Directory Entry is being interpreted as the 1664 contents of a METADATA packet, or as the result of a _getdir_ 1665 transaction, the width of the Size field is the same as that used for 1666 all lengths and offsets within the transfer, given by the METADATA 1667 and DATA Flags bits 8 and 9. 1669 Streams listed in a directory should be marked as special. If a 1670 stream is being transferred, its size is unknown -- otherwise it 1671 would be a file. The size property of a Directory Entry for a stream 1672 is therefore expected to be zero. 1674 It is expected that files are only listed in Directory Entries if 1675 they can be transferred to the requester. An implementation only 1676 capable of receiving small files using 16-bit descriptors will only 1677 see small files capable of being transferred to it when browsing the 1678 filesystem of an implementation capable of larger sizes. Directory 1679 sizes are not sent, and a Size of 0 is given instead for directories. 1681 The "epoch" format used in the timestamps for Mtime and Ctime in file 1682 object records is the number of seconds since January 1, 2000 in UTC, 1683 which is the same epoch used in the DTN Bundle Protocol for 1684 timestamps and postpones wrapping for 30 years beyond typical 1970- 1685 based timestamps. This should include all leapseconds. 1687 A file-receiver should preserve the timestamp information received in 1688 the METADATA for its own copy of the file, to allow newer versions of 1689 files to propagate and supercede older versions. 1691 6. Behaviour of a Saratoga Peer 1693 This section describes some details of Saratoga implementations and 1694 uses the RFC 2119 standards language to describe which portions are 1695 needed for interoperability. 1697 6.1. Saratoga Transactions 1699 Following are descriptions of the packet exchanges between two peers 1700 for each type of transaction. Exchanges rely on use of the Id field 1701 to match responses to requests, as described earlier in Section 4.2. 1703 6.1.1. The _get_ Transaction 1705 1. A peer (the file-receiver) sends a REQUEST packet to its peer 1706 (the file-sender). The Flags bits are set to indicate that this 1707 is not a _delete_ request, nor does the File Path indicate a 1708 directory. Each _get_ transaction corresponds to a single file, 1709 and fetching multiple files requires sending multiple REQUEST 1710 packets and using multiple different transaction Ids so that 1711 responses can be differentiated and matched to REQUESTs based on 1712 the Id field. If a specific file is being requested, then its 1713 name is filled into the File Path field, otherwise it is left 1714 null and the file-sender will send a file of its choice. 1716 2. If the request is rejected, then a STATUS packet containing an 1717 error code in the Status field is sent and the transaction is 1718 terminated. This STATUS packet MUST be sent to reject and 1719 terminate the transaction. The error code MAY make use of the 1720 "Unspecified Error" value for security reasons. Some REQUESTs 1721 might also be rejected for specifying files that are too large to 1722 have their lengths encoded within the maximum integer field width 1723 advertised by bits 8 and 9 of the REQUEST. 1725 3. If the request is accepted, then a STATUS packet MUST be sent 1726 with an error code of 0x00 and an In-Response-To field of zero. 1728 4. Otherwise, if the request is granted, then the file-sender 1729 generates and sends a METADATA packet along with the contents of 1730 the file as a series of DATA packets. In the absence of STATUS 1731 packets, if the file-sender believes it has finished sending the 1732 file, it MUST send the last DATA packet with the Flags bit set 1733 requesting a STATUS response from the file-receiver, and with the 1734 End of Data (EOD) bit set. This can be followed by empty DATA 1735 packets with the Flags bits set with EOD and requesting a STATUS 1736 until either a STATUS packet is received, or the inactivity timer 1737 expires. All of the DATA packets MUST use field widths for the 1738 file offset descriptor fields that match what the Flags of the 1739 METADATA packet specified. Some arbitrarily selected DATA 1740 packets may have the Flags bit set that requests a STATUS packet. 1741 The file-receiver MAY voluntarily send STATUS packets at other 1742 times, where the In-Response-To field MUST set to zero. The 1743 file-receiver SHOULD voluntarily send a STATUS packet in response 1744 to the first DATA packet. 1746 5. As the file-receiver takes in the DATA packets, it writes them 1747 into the file locally. The file-receiver keeps track of missing 1748 data in a hole list. Periodically the file sender will set the 1749 ack flag bit in a DATA packet and request a STATUS packet from 1750 the file-receiver. The STATUS packet can include a copy of this 1751 hole list if there are holes. File-receivers MUST send a STATUS 1752 packet immediately in response to receiving a DATA packet with 1753 the Flags bit set requesting a STATUS. 1755 6. If the file-sender receives a STATUS packet with a non-zero 1756 number of holes, it re-fetches the file data at the specified 1757 offsets and re-transmits it. If the METADATA packet requires 1758 retransmission, this is indicated by a bit in the STATUS packet, 1759 and the METADATA packet is retransmitted. The file-sender MUST 1760 retransmit data from any holes reported by the file-receiver 1761 before proceeding further with new DATA packets. 1763 7. When the file-receiver has fully received the file data and the 1764 METADATA packet, then it sends a STATUS packet indicating that 1765 the transaction is complete, and it terminates the transaction 1766 locally, although it MUST persist in responding to any further 1767 DATA packets received from the file-sender with 'completed' 1768 STATUSes, as described in Section 4.5, for some reasonable amount 1769 of time. Starting a timer on sending a completed STATUS and 1770 resetting it whenever a received DATA/sent 'completed' STATUS 1771 transaction takes place, then removing all session state on timer 1772 expiry, is one approach to this. 1774 Given that there may be a high degree of asymmetry in link bandwidth 1775 between the file-sender and file-receiver, the STATUS packets should 1776 be carefully generated so as to not congest the feedback path. This 1777 means that both a file-sender should be cautious in setting the DATA 1778 Flags bit requesting STATUSes, and also that a file-receiver should 1779 be cautious in gratuitously generating STATUS packets of its own 1780 volition. When sending on known unidirectional links, a file-sender 1781 cannot reasonably expect to receive STATUS packets, so should never 1782 request them. 1784 6.1.2. The _getdir_ Transaction 1786 A _getdir_ transaction proceeds through the same states as the _get_ 1787 transaction. The two differences are that the REQUEST has the 1788 directory bit set in its Flags field, and that, rather than 1789 transferring the contents of a file from the file-receiver to the 1790 file-sender, a set of records representing the contents of a 1791 directory are transferred. These can be parsed and dealt with by the 1792 file-receiver as desired. There is no requirement that a Saratoga 1793 peer send the full contents of a directory listing; a peer may filter 1794 the results to only those entries that are actually accessible to the 1795 requesting peer. 1797 For _getdir_ transactions, the METADATA's bits 8 and 9 in the Flags 1798 field specify both the width of the offset and length fields used 1799 within the transfers DATA and STATUS packets, and also the width of 1800 file Size fields within Directory Entries in the interpreted _getdir_ 1801 results. These Flags bits are set to the minimum of the file- 1802 sender's locally-supported maximum width and the advertised maximum 1803 width within the REQUEST packet, and any file system entries that 1804 would normally be contained in the results, but that have sizes 1805 greater than this width can convey, MUST be filtered out. 1807 6.1.3. The _delete_ Transaction 1809 1. A peer sends a REQUEST packet with the bit set indicating that it 1810 is a deletion request and the path to be deleted is filled into 1811 the File Path field. The File Path MUST be filled in for 1812 _delete_ transactions, unlike for _get_ transactions. 1814 2. The other peer replies with a feedback STATUS packet whose Id 1815 matches the Id field of the _delete_ REQUEST. This STATUS has a 1816 Status code that indicates whether the deletion was granted and 1817 occurred successfully (indicated by the 0x00 Status field in a 1818 success STATUS), or whether some error occurred (indicated by the 1819 non-zero Status field in a failure STATUS). This STATUS packet 1820 MUST have no Holes and 16-bit width zero-valued Progress 1821 Indicator and In-Response-To fields. 1823 If a request is received to delete a file that is already deleted, a 1824 STATUS with Status code 0x00 and other fields as described above is 1825 sent back in acknowledgement. This ensures that loss of STATUS 1826 acknowledgements and repeated _delete_ requests are handled properly. 1828 6.1.4. The _put_ Transaction 1830 A _put_ transaction proceeds as a _get_ does, except the file-sender 1831 and file-receiver roles are exchanged between peers, and no REQUEST 1832 packet is ever sent. The file-sending end senses that the 1833 transaction is in progress when it receives METADATA or DATA packets 1834 for which it has no knowledge of the Id field. If the file-receiver 1835 decides that it will store and handle this request (at least 1836 provisionally), then it MUST send a voluntary (ie, not requested) 1837 success STATUS packet to the file-sender. Otherwise, it sends a 1838 failure STATUS packet. After sending a failure STATUS packet, it may 1839 ignore future packets with the same Id field from the file-sender, 1840 but it should, at a low rate, periodically regenerate the failure 1841 STATUS packet if the flow of packets does not stop. 1843 6.2. Beacons 1845 Sending BEACON packets is not required in any of the transactions 1846 discussed in this specification, but optional BEACONs can provide 1847 useful information in many situations. If a node periodically 1848 generates BEACON packets, then it should do so at a low rate which 1849 does not significantly affect in-progress data transfers. 1851 A node that supports multiple versions of Saratoga (e.g. version 1 1852 from this specification along with the older version 0), MAY send 1853 multiple BEACON packets showing different version numbers. The 1854 version number in a single BEACON should not be used to infer the 1855 larger set of protocol versions that a peer is compatible with. 1856 Similarly, a node capable of communicating via IPv4 and IPv6 MAY send 1857 separate BEACONs via both protocols, or MAY only send BEACONs on its 1858 preferred protocol. 1860 If a node receives BEACONs from a peer, then it SHOULD NOT attempt to 1861 start any _get_, _getdir_, or _delete_ transactions with that peer if 1862 bit 14 is not set in the latest received BEACONs. Likewise, if 1863 received BEACONs from a peer do not have bit 15 set, then _put_ 1864 transactions SHOULD NOT be attempted to that peer. Unlike the 1865 capabilities bits which prevent certain types of transactions from 1866 being attempted, the willingness bits are advisory, and transactions 1867 MAY be attempted even if the node is not advertising a willingness, 1868 as long as it advertises a capability. This avoids waiting for a 1869 willingness indication across long-delay links. 1871 6.3. Upper-Layer Interface 1873 No particular interface functionality is required in implementations 1874 of this specification. The means and degree of access to Saratoga 1875 configuration settings and transaction control that is offered to 1876 upper layers and applications is completely implementation-dependent. 1877 In general, it is expected that upper layers (or users) can set 1878 timeout values for transaction requests and for inactivity periods 1879 during the transaction, on a per-peer or per-transaction basis, but 1880 in some implementations where the Saratoga code is restricted to run 1881 only over certain interfaces with well-understood operational latency 1882 bounds, then these timers MAY be hard-coded. 1884 6.4. Inactivity Timer 1886 In order to determine the liveliness of a transaction, Saratoga nodes 1887 may implement an inactivity timer for each peer they are expecting to 1888 see packets from. For each packet received from a peer, its 1889 associated inactivity timer is reset. If no packets are received for 1890 some amount of time, and the inactivity timer expires, this serves as 1891 a signal to the node that it should abort (and optionally retry) any 1892 sessions that were in progress with the peer. Information from the 1893 link interface (i.e. link down) can override this timer for point-to- 1894 point links. 1896 The actual length of time that the inactivity timer runs for is a 1897 matter of both implementation and deployment situation. Relatively 1898 short timers (on the order of several round-trip times) allow nodes 1899 to quickly react to loss of contact, while longer timers allow for 1900 transaction robustness in the presence of transient link problems. 1901 This document deliberately does not specify a particular inactivity 1902 timer value nor any rules for setting the inactivity timer, because 1903 the protocol is intended to be used in both long- and short-delay 1904 regimes. 1906 Specifically, the inactivity timer is started on sending REQUEST or 1907 STATUS packets. When sending packets not expected to elicit 1908 responses (BEACON, METADATA, or DATA without acknowledgement 1909 requests), there is no point to starting the local inactivity timer. 1911 For normal file transfers, there are simple rules for handling 1912 expiration of the inactivity timer during a _get_ or _put_ 1913 transaction. Once the timer expires, the file-sender SHOULD 1914 terminate the transaction state and cease to send DATA or METADATA 1915 packets. The file-receiver SHOULD stop sending STATUS packets, and 1916 MAY choose to store the file in some cache location so that the 1917 transfer can be recovered. This is possible by waiting for an 1918 opportunity to re-attempt the transaction and immediately sending a 1919 STATUS that only lists the parts of the file not yet received if the 1920 transaction is granted. In any case, a partially-received file MUST 1921 NOT be handled in any way that would allow another application to 1922 think it is complete. 1924 The file-sender may implement more complex timers to allow rate-based 1925 pacing or simple congestion control using information provided in 1926 STATUS packets, but such possible timers and their effects are 1927 deliberately not specified here. 1929 7. Mailing list 1931 There is a mailing list for discussion of Saratoga and its 1932 implementations. Contact Lloyd Wood for details. 1934 8. Security Considerations 1936 The design of Saratoga provides limited, deliberately lightweight, 1937 services for authentication of session requests, and for 1938 authentication or encryption of data files via keyed metadata 1939 checksums. This document does not specify privacy or access control 1940 for data files transferred. Privacy, access, authentication and 1941 encryption issues may be addressed within an implementation or 1942 deployment in several ways that do not affect the file transfer 1943 protocol itself. As examples, IPSec may be used to protect Saratoga 1944 implementations from forged packets, to provide privacy, or to 1945 authenticate the identity of a peer. Other implementation-specific 1946 or configuration-specific mechanisms and policies might also be 1947 employed for authentication and authorization of requests. 1948 Protection of file data and meta-data can also be provided by a 1949 higher-level file encryption facility. If IPsec is not required, use 1950 of encryption before the file is given to Saratoga is preferable. 1951 Basic security practices like not accepting paths with "..", not 1952 following symbolic links, and using a chroot() system call, among 1953 others, should also be considered within an implementation. 1955 Note that Saratoga is intended for single-hop transfers between 1956 peers. A METADATA checksum using a previously shared key can be used 1957 to decrypt or authenticate delivered DATA files. Saratoga can only 1958 provide payload encryption across a single Saratoga transfer, not 1959 end-to-end across concatenated separate hop-by-hop transfers through 1960 untrusted peers, as checksum verification of file integrity is 1961 required at each node. End-to-end data encryption, if required, MUST 1962 be implemented by the application using Saratoga. 1964 9. IANA Considerations 1966 IANA has allocated port 7542 (tcp/udp) for use by Saratoga. 1968 saratoga 7542/tcp Saratoga Transfer Protocol 1969 saratoga 7542/udp Saratoga Transfer Protocol 1971 IANA has allocated a dedicated IPv4 all-hosts multicast address 1972 (224.0.0.108) and a dedicated IPv6 link-local multicast addresses 1973 (FF02:0:0:0:0:0:0:6c) for use by Saratoga. 1975 10. Acknowledgements 1977 Developing and deploying the on-orbit IP-based infrastructure of the 1978 Disaster Monitoring Constellation, in which Saratoga has proven 1979 useful, has taken the efforts of hundreds of people over more than a 1980 decade. We thank them all. 1982 We thank James H. McKim as an early contributor to Saratoga 1983 implementations and specifications, while working for RSIS 1984 Information Systems at NASA Glenn. We regard Jim as an author of 1985 this document, but are prevented by the boilerplate five-author limit 1986 from naming him earlier. 1988 We thank Stewart Bryant, Cathryn Peoples, Abu Zafar Shahriar and Dave 1989 Stewart for their review comments. 1991 Work on this document at NASA's Glenn Research Center was funded by 1992 NASA's Earth Science Technology Office (ESTO). 1994 11. A Note on Naming 1996 Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier 1997 sunk at Bikini Atoll that is now a popular diving site. 1999 12. References 2001 12.1. Normative References 2003 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 2004 August 1980. 2006 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2007 April 1992. 2009 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2010 Requirement Levels", BCP 14, RFC 2119, March 1997. 2012 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 2013 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 2014 September 2002. 2016 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2017 10646", STD 63, RFC 3629, November 2003. 2019 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and 2020 G. Fairhurst, "The Lightweight User Datagram Protocol 2021 (UDP-Lite)", RFC 3828, July 2004. 2023 12.2. Informative References 2025 [Hogie05] Hogie, K., Criscuolo, E., and R. Parise, "Using Standard 2026 Internet Protocols and Applications in Space", Computer 2027 Networks, Special Issue on Interplanetary Internet, vol. 2028 47, no. 5, pp. 603-650, April 2005. 2030 [I-D.ietf-ledbat-congestion] 2031 Shalunov, S., Hazel, G., and J. Iyengar, "Low Extra Delay 2032 Background Transport (LEDBAT)", 2033 draft-ietf-ledbat-congestion-03 (work in progress), 2034 October 2010. 2036 [I-D.wood-dtnrg-http-dtn-delivery] 2037 Wood, L. and P. Holliday, "Using HTTP for delivery in 2038 Delay/Disruption-Tolerant Networks", 2039 draft-wood-dtnrg-http-dtn-delivery-06 (work in progress) , 2040 November 2010. 2042 [I-D.wood-dtnrg-saratoga] 2043 Wood, L., McKim, J., Eddy, W., Ivancic, W., and C. 2044 Jackson, "Using Saratoga with a Bundle Agent as a 2045 Convergence Layer for Delay-Tolerant Networking", 2046 draft-wood-dtnrg-saratoga-08 (work in progress) , 2047 November 2010. 2049 [Ivancic10] 2050 Ivancic, W., Eddy, W., Stewart, D., Wood, L., Northam, J., 2051 and C. Jackson, "Experience with delay-tolerant networking 2052 from orbit", International Journal of Satellite 2053 Communications and Networking, Special Issue on best 2054 papers of the Fourth Advanced Satellite Mobile Systems 2055 Conference (ASMS 2008), vol. 28, issues 5-6, pp. 335-351, 2056 September-December 2010. 2058 [Jackson04] 2059 Jackson, C., "Saratoga File Transfer Protocol", Surrey 2060 Satellite Technology Ltd internal technical document , 2061 2004. 2063 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 2064 STD 9, RFC 959, October 1985. 2066 [RFC3366] Fairhurst, G. and L. Wood, "Advice to link designers on 2067 link Automatic Repeat reQuest (ARQ)", BCP 62, RFC 3366, 2068 August 2002. 2070 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 2071 Specification", RFC 5050, November 2007. 2073 [RFC5348] Floyd, S., Handley, M., Padhye, J., and J. Widmer, "TCP 2074 Friendly Rate Control (TFRC): Protocol Specification", 2075 RFC 5348, September 2008. 2077 [Wood07a] Wood, L., Ivancic, W., Hodgson, D., Miller, E., Conner, 2078 B., Lynch, S., Jackson, C., da Silva Curiel, A., Cooke, 2079 D., Shell, D., Walke, J., and D. Stewart, "Using Internet 2080 Nodes and Routers Onboard Satellites", International 2081 Journal of Satellite Communications and 2082 Networking, Special Issue on Space Networks, vol. 25, no. 2083 2, pp. 195-216, March/April 2007. 2085 [Wood07b] Wood, L., Eddy, W., Ivancic, W., Miller, E., McKim, J., 2086 and C. Jackson, "Saratoga: a Delay-Tolerant Networking 2087 convergence layer with efficient link utilization", 2088 International Workshop on Satellite and Space 2089 Communications (IWSSC '07) Salzburg, September 2007. 2091 Appendix A. Timestamp/Nonce field considerations 2093 Timestamps are useful in DATA packets when the time that the packet 2094 or its payload was generated is of importance; this can be necessary 2095 when streaming sensor data recorded and packetized in real time. The 2096 format of the optional timestamp, whose presence is indicated by a 2097 flag bit, is implementation-dependent within the available fixed- 2098 length 128-bit field. How the contents of this timestamp field are 2099 used and interpreted depends on local needs and conventions and the 2100 local implementation. However, one simple suggested format for 2101 timestamps is to begin with a POSIX time_t representation of time, in 2102 network byte order. This is either a 32-bit or 64-bit signed integer 2103 representing the number of seconds since 1970. The remainder of this 2104 field can be used either for a representation of elapsed time within 2105 the current second, if that level of accuracy is required, or as a 2106 nonce field uniquely identifying the packet or including other 2107 information. Any locally-meaningful flags identifying a type of 2108 timestamp or timebase can be included before the end of the field. 2109 Unused parts of this field MUST be set to zero. 2111 There are many different representations of timestamps and timebases, 2112 and this draft is too short to cover them in detail. One suggested 2113 flag representation of different timestamp fields is to use the least 2114 significant bits at the end of the timestamp/nonce field as: 2116 +---------+---------------------------------------------------------+ 2117 | Status | Meaning | 2118 | Value | | 2119 +---------+---------------------------------------------------------+ 2120 | 0x00 | No flags set, local interpretation of field. | 2121 | 0x01 | 32-bit timestamp at start of field indicating whole | 2122 | | seconds from epoch. | 2123 | 0x02 | 64-bit timestamp at start of field indicating whole | 2124 | | seconds elapsed from epoch. | 2125 | 0x03 | 32-bit timestamp, as in 0x01, followed by 32-bit | 2126 | | timestamp indicating fraction of the second elapsed. | 2127 | 0x04 | 64-bit timestamp, as in 0x02, followed by 32-bit | 2128 | | timestamp indicating fraction of the second elapsed. | 2129 +---------+---------------------------------------------------------+ 2131 Other values may indicate specific epochs or timebases, as local 2132 requirements dictate. There are many ways to define and use time 2133 usefully. 2135 Echoing timestamps back to the receiver is also useful for tracking 2136 flow conditions, for e.g. optional congestion control. Timestamp 2137 values provide a useful mechanism for Saratoga peers to measure path 2138 and round-trip latency. The use of timestamp values may assist in 2139 developing algorithms for flow control (including TCP-Friendly Rate 2140 Control) or other purposes. 2142 Authors' Addresses 2144 Lloyd Wood 2145 Centre for Communication Systems Research, University of Surrey 2146 Guildford, Surrey GU2 7XH 2147 United Kingdom 2149 Phone: +44-1483-689123 2150 Email: L.Wood@surrey.ac.uk 2152 Wesley M. Eddy 2153 MTI Systems 2154 MS 500-ASRC 2155 NASA Glenn Research Center 2156 21000 Brookpark Road 2157 Cleveland, OH 44135 2158 USA 2160 Phone: +1-216-433-6682 2161 Email: wes@mti-systems.com 2162 Charles Smith 2163 Commonwealth Scientific and Industrial Research Organisation 2164 Cnr Vimiera and Pembroke Roads 2165 Marsfield, New South Wales 2122 2166 Australia 2168 Phone: +61-404-058974 2169 Email: charles.smith@csiro.au 2171 Will Ivancic 2172 NASA Glenn Research Center 2173 21000 Brookpark Road, MS 54-5 2174 Cleveland, OH 44135 2175 USA 2177 Phone: +1-216-433-3494 2178 Email: William.D.Ivancic@grc.nasa.gov 2180 Chris Jackson 2181 Surrey Satellite Technology Ltd 2182 Tycho House 2183 Surrey Space Centre 2184 20 Stephenson Road 2185 Guildford, Surrey GU2 7YE 2186 United Kingdom 2188 Phone: +44-1483-803803 2189 Email: C.Jackson@sstl.co.uk