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